vrs-source.yaml

# VRS uses yaml as the source document for json schema
#
# To convert vrs.yaml to vrs.json:
#   make vrs.json
# You'll probably have to `pip install pyyaml` first.
#
# To watch for changes and update automatically:
#   make watch &

# https://json-schema.org/understanding-json-schema/reference/schema.html
$schema: "https://json-schema.org/draft/2020-12/schema"
$id: "https://w3id.org/ga4gh/schema/vrs/2.x/vrs-source.yaml"
title: "GA4GH-VRS-Definitions"
type: object
strict: true

imports:
  gks.core-im: ../core-im/core-im-source.yaml

$defs:
  # VRS definitions are presented top-down.  Everything rolls up to
  # Variation, which is a polymorphic abstraction of many kinds of
  # variation.

  # =============================================================================
  # Kinds of Variation
  # =============================================================================

  Ga4ghIdentifiableObject:
    inherits: gks.core-im:Entity
    description: >-
      An object for which a GA4GH computed identifier can be created.
    ga4ghDigest:
      keys:
        - type
    heritableProperties:
      type:
        type: string
      digest:
        description: A sha512t24u digest created using the VRS Computed Identifier algorithm.
        type: string
        pattern: '^[0-9A-Za-z_\-]{32}$'

  Variation:
    inherits: Ga4ghIdentifiableObject
    description: >-
      A representation of the state of one or more biomolecules.
    oneOf:
      - $ref: "#/$defs/MolecularVariation"
      - $ref: "#/$defs/SystemicVariation"
    heritableProperties:
      expressions:
        type: array
        ordered: false
        items:
          $ref: "#/$defs/Expression"
    discriminator:
      propertyName: type

  Expression:
    type: object
    maturity: draft
    # protectedClassOf: Variation
    description: >-
      Representation of a variation by a specified nomenclature or syntax for a Variation object.
      Common examples of expressions for the description of molecular variation include the HGVS
      and ISCN nomenclatures.
    properties:
      syntax:
        type: string
        enum: ["hgvs.c", "hgvs.p", "hgvs.g", "hgvs.m", "hgvs.n", "hgvs.r", "iscn", "gnomad", "spdi"]
        description: >-
          The syntax used to describe the variation. The value should be one of the supported syntaxes.
      value:
        type: string
        description: >-
          The expression of the variation in the specified syntax. The value should be a valid
          expression in the specified syntax.
      syntax_version:
        type: string
        description: >-
          The version of the syntax used to describe the variation. This is particularly important for
          HGVS expressions, as the syntax has evolved over time.
    required:
      - syntax
      - value


  MolecularVariation:
    inherits: Variation
    description: >-
      A :ref:`variation` on a contiguous molecule.
    oneOf:
      - $ref: "#/$defs/Allele"
      - $ref: "#/$defs/CisPhasedBlock"
      - $ref: "#/$defs/Adjacency"
      - $ref: "#/$defs/Terminus"
      - $ref: "#/$defs/DerivativeMolecule"
    discriminator:
      propertyName: type

  SystemicVariation:
    inherits: Variation
    description: >-
      A Variation of multiple molecules in the context of a system, e.g.
      a genome, sample, or homologous chromosomes.
    oneOf:
      - $ref: "#/$defs/CopyNumberCount"
      - $ref: "#/$defs/CopyNumberChange"
    discriminator:
      propertyName: type

  # =============================================================================
  # IDENTIFIABLE TYPES
  # Have a `type` and `_id` attribute
  # =============================================================================

  # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  # Molecular Variation

  Allele:
    maturity: draft
    ga4ghDigest:
      prefix: VA
      keys:
        - location
        - state
    inherits: MolecularVariation
    description: >-
      The state of a molecule at a :ref:`Location`.
    type: object
    properties:
      type:
        extends: type
        const: "Allele"
        default: "Allele"
        description: >-
          MUST be "Allele"
      location:
        oneOf:
          - $ref: "/ga4gh/schema/gks-common/1.x/core-im/json/IRI"
          - $ref: "#/$defs/Location"
        description: >-
          The location of the Allele
      state:
        $ref: "#/$defs/SequenceExpression"
        description: >-
          An expression of the sequence state
    required: [ "location", "state" ]

  CisPhasedBlock:
    maturity: draft
    ga4ghDigest:
      prefix: CPB
      keys:
        - members
    inherits: MolecularVariation
    description: >-
      An ordered set of co-occurring :ref:`variants <Variation>` on the same molecule.
    type: "object"
    properties:
      type:
        extends: type
        const: "CisPhasedBlock"
        default: "CisPhasedBlock"
        description: >-
          MUST be "CisPhasedBlock"
      members:
        type: array
        ordered: false
        minItems: 2
        uniqueItems: false
        items:
          oneOf:
            - $ref: "#/$defs/Allele"
            - $ref: "/ga4gh/schema/gks-common/1.x/core-im/json/IRI" 
        description: >-
          A list of :ref:`Alleles <Allele>` that are found in-cis on a shared molecule.
      sequenceReference:
        $ref: "#/$defs/SequenceReference"
        description: >-
          An optional Sequence Reference on which all of the in-cis Alleles are found.
          When defined, this may be used to implicitly define the `sequenceReference`
          attribute for each of the CisPhasedBlock member Alleles.

    required: [ "members" ]

  # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  # SystemicVariation

  CopyNumber:
    ga4ghDigest:
      keys:
        - location
    inherits: SystemicVariation
    description: >-
      A measure of the copies of a :ref:`Location` within a system (e.g. genome, cell, etc.)
    heritableProperties:
      location:
        oneOf:
          - $ref: "/ga4gh/schema/gks-common/1.x/core-im/json/IRI"
          - $ref: "#/$defs/Location"
        description: >-
          A location for which the number of systemic copies is described.
    heritableRequired: [ "location" ]

  CopyNumberCount:
    maturity: draft
    ga4ghDigest:
      keys:
        - copies
      prefix: CN
    inherits: CopyNumber
    type: object
    description: >-
      The absolute count of discrete copies of a :ref:`Location` or :ref:`Gene`,
      within a system (e.g. genome, cell, etc.).
    properties:
      type:
        extends: type
        const: "CopyNumberCount"
        default: "CopyNumberCount"
        description: >-
          MUST be "CopyNumberCount"
      copies:
        oneOf:
          - type: integer
          - $ref: "#/$defs/Range"
        description: >-
          The integral number of copies of the subject in a system
    required: [ "copies" ]

  CopyNumberChange:
    maturity: draft
    ga4ghDigest:
      keys:
        - copyChange
      prefix: CX
    inherits: CopyNumber
    type: object
    description: >-
      An assessment of the copy number of a :ref:`Location` or a :ref:`Gene` within a system (e.g. genome, cell,
      etc.) relative to a baseline ploidy.
    properties:
      type:
        extends: type
        const: "CopyNumberChange"
        default: "CopyNumberChange"
        description: >-
          MUST be "CopyNumberChange"
      copyChange:
        $ref: "/ga4gh/schema/gks-common/1.x/core-im/json/Coding"
        description: >-
          MUST be a :ref:`Coding` representing one of "EFO:0030069" (complete genomic loss), "EFO:0020073" (high-level loss),
          "EFO:0030068" (low-level loss), "EFO:0030067" (loss), "EFO:0030064" (regional base ploidy),
          "EFO:0030070" (gain), "EFO:0030071" (low-level gain), "EFO:0030072" (high-level gain).
    required: [ "copyChange" ]

  # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  # Locations

  Location:
    inherits: Ga4ghIdentifiableObject
    description: >-
      A contiguous segment of a biological sequence.
    $ref: "#/$defs/SequenceLocation"
    discriminator:
      propertyName: type

  SequenceLocation:
    maturity: draft
    ga4ghDigest:
      keys:
        - start
        - end
        - sequenceReference
      prefix: SL
    inherits: Location
    description: >-
      A :ref:`Location` defined by an interval on a referenced :ref:`Sequence`.
    type: object
    properties:
      type:
        extends: type
        const: "SequenceLocation"
        default: "SequenceLocation"
        description: MUST be "SequenceLocation"
      sequenceReference:
        oneOf:
          - $ref: "/ga4gh/schema/gks-common/1.x/core-im/json/IRI"
          - $ref: "#/$defs/SequenceReference"
        description: A reference to a :ref:`Sequence` on which the location is defined.
      start:
        oneOf:
          - type: integer
          - $ref: "#/$defs/Range"
        description: >-
          The start coordinate or range of the SequenceLocation.
          The minimum value of this coordinate or range is 0.
          MUST represent a coordinate or range less than or equal to the value of `end`.
      end:
        oneOf:
          - type: integer
          - $ref: "#/$defs/Range"
        description: >-
          The end coordinate or range of the SequenceLocation.
          The minimum value of this coordinate or range is 0.
          MUST represent a coordinate or range greater than or equal to the value of `start`.
      sequence:
        description: >-
          The literal sequence encoded by the `sequenceReference` at these coordinates.
        $ref: "#/$defs/SequenceString"

  SequenceReference:
    maturity: draft
    inherits: gks.core-im:Entity
    ga4ghDigest:
      keys:
        - refgetAccession
        - type
    type: object
    description: A sequence of nucleic or amino acid character codes.
    properties:
      type:
        extends: type
        const: "SequenceReference"
        default: "SequenceReference"
        description: MUST be "SequenceReference"
      refgetAccession:
        description: >-
          A `GA4GH RefGet <http://samtools.github.io/hts-specs/refget.html>`_ identifier for the referenced sequence,
          using the sha512t24u digest.
        type: string
        pattern: '^SQ.[0-9A-Za-z_\-]{32}$'
      residueAlphabet:
        type: string
        description: >-
          The interpretation of the character codes referred to by the refget accession, where "aa" specifies an
          amino acid character set, and "na" specifies a nucleic acid character set.
        enum:
          - aa
          - na
      circular:
        type: boolean
        description: >-
          A boolean indicating whether the molecule represented by the sequence is circular (true) or linear (false).
    required: ["refgetAccession"]

  # =============================================================================
  # NON-IDENTIFIABLE TYPES
  # These types have a `type` attribute
  # =============================================================================

  # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  # SequenceExpression

  SequenceExpression:
    inherits: gks.core-im:Entity
    ga4ghDigest:
      keys:
        - type
    description: >-
      An expression describing a :ref:`Sequence`.
    oneOf:
      - $ref: "#/$defs/LiteralSequenceExpression"
      - $ref: "#/$defs/ReferenceLengthExpression"
      - $ref: "#/$defs/LengthExpression"
    discriminator:
      propertyName: type
    heritableProperties:
      type:
        extends: type
        description: >-
          The SequenceExpression class type. MUST match child class type.
    heritableRequired:
      - type

  ReferenceLengthExpression:
    maturity: draft
    inherits: SequenceExpression
    ga4ghDigest:
      keys:
        - length
        - repeatSubunitLength
    description: >-
      An expression of a sequence that is derived from repeating a subsequence
      of an associated :ref:`SequenceLocation`.
    type: object
    properties:
      type:
        extends: type
        const: "ReferenceLengthExpression"
        default: "ReferenceLengthExpression"
        description: MUST be "ReferenceLengthExpression"
      length:
        oneOf:
          - type: integer
          - $ref: "#/$defs/Range"
        description: The number of residues in the expressed sequence.
      sequence:
        $ref: "#/$defs/SequenceString"
        description: the literal :ref:`Sequence` encoded by the Reference Length Expression.
      repeatSubunitLength:
        type: integer
        description: The number of residues in the repeat subunit.
    required:
      - length
      - repeatSubunitLength

  LengthExpression:
    maturity: draft
    inherits: SequenceExpression
    ga4ghDigest:
      keys:
        - length
    type: object
    description: A sequence expressed only by its length.
    properties:
      type:
        extends: type
        const: "LengthExpression"
        default: "LengthExpression"
        description: MUST be "LengthExpression"
      length:
        description: The length of the sequence.
        oneOf:
          - $ref: "#/$defs/Range"
          - type: integer

  LiteralSequenceExpression:
    maturity: draft
    inherits: SequenceExpression
    ga4ghDigest:
      keys:
        - sequence
    description: An explicit expression of a Sequence.
    type: object
    properties:
      type:
        extends: type
        const: "LiteralSequenceExpression"
        default: "LiteralSequenceExpression"
        description: MUST be "LiteralSequenceExpression"
      sequence:
        $ref: "#/$defs/SequenceString"
        description: the literal sequence
    required:
      - sequence

  # - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  # Numerics, Comparators, and Ranges

  Range:
    maturity: draft
    description: An inclusive range of values bounded by one or more integers.
    type: array
    ordered: true
    items:
      oneOf:
        - type: integer
        - type: "null"
    maxItems: 2
    minItems: 2

  Residue:
    maturity: draft
    description: >-
      A character representing a specific residue (i.e., molecular species)
      or groupings of these ("ambiguity codes"), using `one-letter IUPAC
      abbreviations <https://en.wikipedia.org/wiki/International_Union_of_Pure_and_Applied_Chemistry#Amino_acid_and_nucleotide_base_codes>`_
      for nucleic acids and amino acids.
    type: string
    pattern: '[A-Z*\-]'

  SequenceString:
    maturity: draft
    description: >-
      A character string of :ref:`Residues <Residue>` that represents a biological
      sequence using the conventional sequence order (5’-to-3’ for
      nucleic acid sequences, and amino-to-carboxyl for amino acid
      sequences). IUPAC ambiguity codes are permitted in Sequence Strings.
    type: string
    pattern: '^[A-Z*\-]*$'


  # =============================================================================
  # NEW PROPOSED SV Classes
  # These classes are not yet organized within the vrs-source.yaml document
  # These classes are under active discussion.
  # =============================================================================

  Adjacency:
    maturity: draft
    ga4ghDigest:
      prefix: AJ
      keys:
        - adjoinedSequences
        - linker
    inherits: MolecularVariation
    description: >-
      The `Adjacency` class can represent either the termination of a sequence
      or the adjoining of the end of a sequence with the beginning of an
      adjacent sequence, potentially with an intervening linker sequence.
    type: object
    properties:
      type:
        extends: type
        const: Adjacency
        default: Adjacency
        description: MUST be "Adjacency".
      adjoinedSequences:
        type: array
        uniqueItems: false
        ordered: true
        items:
          oneOf:
          - $ref: "/ga4gh/schema/gks-common/1.x/core-im/json/IRI"
          - $ref: "#/$defs/Location"
        description: The terminal sequence or pair of adjoined sequences that defines in the adjacency.
        minItems: 2
        maxItems: 2
      linker:
        $ref: "#/$defs/SequenceExpression"
        description: The sequence found between adjoined sequences.
      homology:
        type: boolean
        maturity: draft
        description: >-
          A flag indicating if coordinate ambiguity in the adjoined sequences is from sequence homology
          (true) or other uncertainty, such as instrument ambiguity (false).
    required:
      - adjoinedSequences

  Terminus:
    maturity: draft
    ga4ghDigest:
      prefix: TM
      keys:
        - location
    inherits: MolecularVariation
    description: >-
      The `Terminus` data class provides a structure for describing the end (terminus)
      of a molecule. Structurally similar to Adjacency, but used for describing where
      a molecule terminates (instead of adjoining another molecule).
    type: object
    properties:
      type:
        extends: type
        const: Terminus
        default: Terminus
        description: MUST be "Terminus".
      location:
        oneOf:
          - $ref: "/ga4gh/schema/gks-common/1.x/core-im/json/IRI"
          - $ref: "#/$defs/Location"
        description: The location of the terminus.
    required:
      - location

  DerivativeMolecule:
    maturity: draft
    ga4ghDigest:
      prefix: DM
      keys:
        - components
    inherits: MolecularVariation
    description: >-
      A molecule derived from segments of multiple adjoined molecular sequences, typically resulting from
      structural variation.
    type: object
    properties:
      type:
        extends: type
        const: DerivativeMolecule
        default: DerivativeMolecule
        description: MUST be "DerivativeMolecule".
      components:
        type: array
        uniqueItems: false
        ordered: true
        items:
          oneOf:
          - $ref: "/ga4gh/schema/gks-common/1.x/core-im/json/IRI"
          - $ref: "#/$defs/TraversalBlock"
        description: >-
          The molecular components that constitute the derivative molecule.
        minItems: 2
      circular:
        type: boolean
        description: >-
          A boolean indicating whether the molecule represented by the sequence is circular (true) or linear (false).
    required:
      - components

  TraversalBlock:
    maturity: draft
    inherits: gks.core-im:Entity
    type: object
    # protectedClassOf: DerivativeMolecule
    ga4ghDigest:
      keys:
        - type
        - component
        - orientation
    description: >-
      A component used to describe the orientation of a molecular variation within a
      DerivativeMolecule.
    properties:
      type:
        extends: type
        const: TraversalBlock
        default: TraversalBlock
        description: MUST be "TraversalBlock".
      component:
        description: >-
          The unoriented molecular variation component.
        oneOf:
          - $ref: "#/$defs/Allele"
          - $ref: "#/$defs/CisPhasedBlock"
          - $ref: "#/$defs/Adjacency"
          - $ref: "#/$defs/Terminus"
      orientation:
        type: string
        description: >-
          The orientation of the molecular variation component.
        enum:
          - "forward"
          - "reverse_complement"