$schema: http://json-schema.org/draft-07/schema
title: GA4GH-VRS-Definitions
type: object
definitions:
  Variation:
    description: A representation of the state of one or more biomolecules.
    oneOf:
    - $ref: '#/definitions/MolecularVariation'
    - $ref: '#/definitions/SystemicVariation'
    - $ref: '#/definitions/UtilityVariation'
    discriminator:
      propertyName: type
  MolecularVariation:
    description: A variation on a contiguous molecule.
    oneOf:
    - $ref: '#/definitions/Allele'
    - $ref: '#/definitions/Haplotype'
    discriminator:
      propertyName: type
  UtilityVariation:
    description: A collection of Variation subclasses that cannot be constrained to
      a specific class of biological variation, but are necessary for some applications
      of VRS.
    oneOf:
    - $ref: '#/definitions/Text'
    - $ref: '#/definitions/VariationSet'
    discriminator:
      propertyName: type
  SystemicVariation:
    description: A Variation of multiple molecules in the context of a system, e.g.
      a genome, sample, or homologous chromosomes.
    oneOf:
    - $ref: '#/definitions/CopyNumber'
    discriminator:
      propertyName: type
  Allele:
    description: The state of a molecule at a Location.
    additionalProperties: false
    type: object
    properties:
      _id: &id001
        $ref: '#/definitions/CURIE'
        description: Variation Id. MUST be unique within document.
      type:
        type: string
        const: Allele
        default: Allele
        description: MUST be "Allele"
      location:
        oneOf:
        - $ref: '#/definitions/CURIE'
        - $ref: '#/definitions/Location'
        description: Where Allele is located
      state:
        oneOf:
        - $ref: '#/definitions/SequenceExpression'
        - $ref: '#/definitions/SequenceState'
        description: An expression of the sequence state
        deprecated:
        - $ref: '#/definitions/SequenceState'
    required:
    - location
    - state
    - type
  Haplotype:
    description: A set of non-overlapping Allele members that co-occur on the same
      molecule.
    additionalProperties: false
    type: object
    properties:
      _id: *id001
      type:
        type: string
        const: Haplotype
        default: Haplotype
        description: MUST be "Haplotype"
      members:
        type: array
        minItems: 1
        uniqueItems: true
        items:
          oneOf:
          - $ref: '#/definitions/Allele'
          - $ref: '#/definitions/CURIE'
        description: List of Alleles, or references to Alleles, that comprise this
          Haplotype.
    required:
    - members
    - type
  Text:
    description: A free-text definition of variation.
    additionalProperties: false
    type: object
    properties:
      _id: *id001
      type:
        type: string
        const: Text
        default: Text
        description: MUST be "Text"
      definition:
        type: string
        description: A textual representation of variation not representable by other
          subclasses of Variation.
    required:
    - definition
    - type
  VariationSet:
    description: An unconstrained set of Variation members.
    type: object
    additionalProperties: false
    properties:
      _id: *id001
      type:
        type: string
        const: VariationSet
        default: VariationSet
        description: MUST be "VariationSet"
      members:
        type: array
        uniqueItems: true
        items:
          oneOf:
          - $ref: '#/definitions/CURIE'
          - $ref: '#/definitions/Variation'
        description: List of Variation objects or identifiers. Attribute is required,
          but MAY be empty.
    required:
    - members
    - type
  CopyNumber:
    additionalProperties: false
    type: object
    description: The absolute count of discrete copies of a MolecularVariation, Feature,
      SequenceExpression, or a CURIE reference within a system (e.g. genome, cell,
      etc.).
    properties:
      _id: *id001
      type:
        type: string
        const: CopyNumber
        default: CopyNumber
        description: MUST be "CopyNumber"
      subject:
        oneOf:
        - $ref: '#/definitions/MolecularVariation'
        - $ref: '#/definitions/Feature'
        - $ref: '#/definitions/SequenceExpression'
        - $ref: '#/definitions/CURIE'
        description: Subject of the Copy Number object
      copies:
        oneOf:
        - $ref: '#/definitions/Number'
        - $ref: '#/definitions/IndefiniteRange'
        - $ref: '#/definitions/DefiniteRange'
        description: The integral number of copies of the subject in a system
    allOf:
    - if:
        properties:
          copies:
            $ref: '#/definitions/Number'
      then:
        properties:
          copies:
            properties:
              value:
                minimum: 0
    - if:
        properties:
          copies:
            $ref: '#/definitions/IndefiniteRange'
      then:
        properties:
          copies:
            properties:
              value:
                minimum: 0
    - if:
        properties:
          copies:
            $ref: '#/definitions/DefiniteRange'
      then:
        properties:
          copies:
            properties:
              min:
                minimum: 0
              max:
                minimum: 0
    required:
    - copies
    - subject
    - type
  Location:
    description: A contiguous segment of a biological sequence.
    oneOf:
    - $ref: '#/definitions/ChromosomeLocation'
    - $ref: '#/definitions/SequenceLocation'
    discriminator:
      propertyName: type
  ChromosomeLocation:
    additionalProperties: false
    description: A Location on a chromosome defined by a species and chromosome name.
    type: object
    properties:
      _id: &id002
        $ref: '#/definitions/CURIE'
        description: Location Id. MUST be unique within document.
      type:
        type: string
        const: ChromosomeLocation
        default: ChromosomeLocation
        description: MUST be "ChromosomeLocation"
      species_id:
        $ref: '#/definitions/CURIE'
        default: taxonomy:9606
        description: 'CURIE representing a species from the [NCBI species taxonomy](https://registry.identifiers.org/registry/taxonomy).
          Default: "taxonomy:9606" (human)'
      chr:
        type: string
        description: The symbolic chromosome name. For humans, For humans, chromosome
          names MUST be one of 1..22, X, Y (case-sensitive)
      interval:
        $ref: '#/definitions/CytobandInterval'
        description: The chromosome region defined by a CytobandInterval
    required:
    - chr
    - interval
    - species_id
    - type
  SequenceLocation:
    additionalProperties: false
    description: A Location defined by an interval on a referenced Sequence.
    type: object
    properties:
      _id: *id002
      type:
        type: string
        const: SequenceLocation
        default: SequenceLocation
        description: MUST be "SequenceLocation"
      sequence_id:
        $ref: '#/definitions/CURIE'
        description: A VRS Computed Identifier for the reference Sequence.
      interval:
        oneOf:
        - $ref: '#/definitions/SequenceInterval'
        - $ref: '#/definitions/SimpleInterval'
        description: Reference sequence region defined by a SequenceInterval.
    required:
    - interval
    - sequence_id
    - type
  SequenceInterval:
    description: A SequenceInterval represents a span on a Sequence. Positions are
      always represented by contiguous spans using interbase coordinates or coordinate
      ranges.
    type: object
    additionalProperties: false
    properties:
      type:
        type: string
        const: SequenceInterval
        default: SequenceInterval
        description: MUST be "SequenceInterval"
      start:
        oneOf:
        - $ref: '#/definitions/Number'
        - $ref: '#/definitions/IndefiniteRange'
        - $ref: '#/definitions/DefiniteRange'
        description: The start coordinate or range of the interval. The minimum value
          of this coordinate or range is 0. MUST represent a coordinate or range less
          than the value of `end`.
      end:
        oneOf:
        - $ref: '#/definitions/Number'
        - $ref: '#/definitions/IndefiniteRange'
        - $ref: '#/definitions/DefiniteRange'
        description: The end coordinate or range of the interval. The minimum value
          of this coordinate or range is 0. MUST represent a coordinate or range greater
          than the value of `start`.
    allOf:
    - if:
        properties:
          start:
            $ref: '#/definitions/Number'
      then:
        properties:
          start:
            properties:
              value:
                minimum: 0
    - if:
        properties:
          start:
            $ref: '#/definitions/IndefiniteRange'
      then:
        properties:
          start:
            properties:
              value:
                minimum: 0
    - if:
        properties:
          start:
            $ref: '#/definitions/DefiniteRange'
      then:
        properties:
          start:
            properties:
              min:
                minimum: 0
              max:
                minimum: 0
    - if:
        properties:
          end:
            $ref: '#/definitions/Number'
      then:
        properties:
          end:
            properties:
              value:
                minimum: 0
    - if:
        properties:
          end:
            $ref: '#/definitions/IndefiniteRange'
      then:
        properties:
          end:
            properties:
              value:
                minimum: 0
    - if:
        properties:
          end:
            $ref: '#/definitions/DefiniteRange'
      then:
        properties:
          end:
            properties:
              min:
                minimum: 0
              max:
                minimum: 0
    required:
    - end
    - start
    - type
  CytobandInterval:
    description: A contiguous span on a chromosome defined by cytoband features. The
      span includes the constituent regions described by the start and end cytobands,
      as well as any intervening regions.
    type: object
    additionalProperties: false
    properties:
      type:
        type: string
        const: CytobandInterval
        default: CytobandInterval
        description: MUST be "CytobandInterval"
      start:
        $ref: '#/definitions/HumanCytoband'
        description: The start cytoband region. MUST specify a region nearer the terminal
          end (telomere) of the chromosome p-arm than `end`.
      end:
        $ref: '#/definitions/HumanCytoband'
        description: The start cytoband region. MUST specify a region nearer the terminal
          end (telomere) of the chromosome q-arm than `start`.
    example:
      type: CytobandInterval
      start: q22.2
      end: q22.3
    required:
    - end
    - start
    - type
  SequenceExpression:
    description: An expression describing a Sequence.
    oneOf:
    - $ref: '#/definitions/LiteralSequenceExpression'
    - $ref: '#/definitions/DerivedSequenceExpression'
    - $ref: '#/definitions/RepeatedSequenceExpression'
    discriminator:
      propertyName: type
  LiteralSequenceExpression:
    description: An explicit expression of a Sequence.
    type: object
    additionalProperties: false
    properties:
      type:
        type: string
        const: LiteralSequenceExpression
        default: LiteralSequenceExpression
        description: MUST be "LiteralSequenceExpression"
      sequence:
        $ref: '#/definitions/Sequence'
        description: the literal Sequence expressed
    required:
    - sequence
    - type
  DerivedSequenceExpression:
    description: An approximate expression of a sequence that is derived from a referenced
      sequence location. Use of this class indicates that the derived sequence is
      *approximately equivalent* to the reference indicated, and is typically used
      for describing large regions in contexts where the use of an approximate sequence
      is inconsequential.
    type: object
    additionalProperties: false
    properties:
      type:
        type: string
        const: DerivedSequenceExpression
        default: DerivedSequenceExpression
        description: MUST be "DerivedSequenceExpression"
      location:
        $ref: '#/definitions/SequenceLocation'
        description: The location from which the approximate sequence is derived
      reverse_complement:
        type: boolean
        description: A flag indicating if the expressed sequence is the reverse complement
          of the sequence referred to by `location`
    required:
    - location
    - reverse_complement
    - type
  RepeatedSequenceExpression:
    description: An expression of a sequence comprised of a tandem repeating subsequence.
    additionalProperties: false
    type: object
    properties:
      type:
        type: string
        const: RepeatedSequenceExpression
        default: RepeatedSequenceExpression
        description: MUST be "RepeatedSequenceExpression"
      seq_expr:
        oneOf:
        - $ref: '#/definitions/LiteralSequenceExpression'
        - $ref: '#/definitions/DerivedSequenceExpression'
        description: An expression of the repeating subsequence
      count:
        oneOf:
        - $ref: '#/definitions/Number'
        - $ref: '#/definitions/IndefiniteRange'
        - $ref: '#/definitions/DefiniteRange'
        description: The count of repeated units, as an integer or inclusive range
    allOf:
    - if:
        properties:
          count:
            $ref: '#/definitions/Number'
      then:
        properties:
          count:
            properties:
              value:
                minimum: 0
    - if:
        properties:
          count:
            $ref: '#/definitions/IndefiniteRange'
      then:
        properties:
          count:
            properties:
              value:
                minimum: 0
    - if:
        properties:
          count:
            $ref: '#/definitions/DefiniteRange'
      then:
        properties:
          count:
            properties:
              min:
                minimum: 0
              max:
                minimum: 0
    required:
    - count
    - seq_expr
    - type
  Feature:
    description: A named entity that can be mapped to a Location. Genes, protein domains,
      exons, and chromosomes are some examples of common biological entities that
      may be Features.
    oneOf:
    - $ref: '#/definitions/Gene'
    discriminator:
      propertyName: type
  Gene:
    description: A reference to a Gene as defined by an authority. For human genes,
      the use of [hgnc](https://registry.identifiers.org/registry/hgnc) as the gene
      authority is RECOMMENDED.
    type: object
    additionalProperties: false
    properties:
      type:
        type: string
        const: Gene
        default: Gene
        description: MUST be "Gene"
      gene_id:
        $ref: '#/definitions/CURIE'
        description: A CURIE reference to a Gene concept
    required:
    - gene_id
    - type
  Number:
    description: A simple integer value as a VRS class.
    type: object
    additionalProperties: false
    properties:
      type:
        type: string
        const: Number
        default: Number
        description: MUST be "Number"
      value:
        type: integer
        description: The value represented by Number
    required:
    - type
    - value
  DefiniteRange:
    description: A bounded, inclusive range of numbers.
    type: object
    additionalProperties: false
    properties:
      type:
        type: string
        const: DefiniteRange
        default: DefiniteRange
        description: MUST be "DefiniteRange"
      min:
        type: number
        description: The minimum value; inclusive
      max:
        type: number
        description: The maximum value; inclusive
    required:
    - max
    - min
    - type
  IndefiniteRange:
    description: 'A half-bounded range of numbers represented as a number bound and
      associated comparator. The bound operator is interpreted as follows: ''>=''
      are all numbers greater than and including `value`, ''<='' are all numbers less
      than and including `value`.'
    type: object
    additionalProperties: false
    properties:
      type:
        type: string
        const: IndefiniteRange
        default: IndefiniteRange
        description: MUST be "IndefiniteRange"
      value:
        type: number
        description: The bounded value; inclusive
      comparator:
        type: string
        enum:
        - <=
        - '>='
        description: MUST be one of "<=" or ">=", indicating which direction the range
          is indefinite
    required:
    - comparator
    - type
    - value
  CURIE:
    additionalProperties: false
    description: A [W3C Compact URI](https://www.w3.org/TR/curie/) formatted string.
      A CURIE string has the structure ``prefix``:``reference``, as defined by the
      W3C syntax.
    type: string
    pattern: ^\w[^:]*:.+$
    example: ensembl:ENSG00000139618
  HumanCytoband:
    additionalProperties: false
    description: A character string representing cytobands derived from the *International
      System for Human Cytogenomic Nomenclature* (ISCN) [guidelines](http://doi.org/10.1159/isbn.978-3-318-06861-0).
    type: string
    pattern: ^cen|[pq](ter|([1-9][0-9]*(\.[1-9][0-9]*)?))$
    example: q22.3
  Residue:
    additionalProperties: false
    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*\-]'
  Sequence:
    additionalProperties: false
    description: "A character string of Residues that represents a biological sequence\
      \ using the conventional sequence order (5\u2019-to-3\u2019 for nucleic acid\
      \ sequences, and amino-to-carboxyl for amino acid sequences). IUPAC ambiguity\
      \ codes are permitted in Sequences."
    type: string
    pattern: ^[A-Z*\-]*$
  SequenceState:
    deprecated: true
    description: DEPRECATED. A Sequence as a State. This is the State class to use
      for representing "ref-alt" style variation, including SNVs, MNVs, del, ins,
      and delins. This class is deprecated. Use LiteralSequenceExpression instead.
    additionalProperties: false
    type: object
    properties:
      type:
        type: string
        const: SequenceState
        default: SequenceState
        description: MUST be "SequenceState"
      sequence:
        $ref: '#/definitions/Sequence'
        description: A string of Residues
    example:
      type: SequenceState
      sequence: C
    required:
    - sequence
    - type
  SimpleInterval:
    deprecated: true
    description: 'DEPRECATED: A SimpleInterval represents a span of sequence. Positions
      are always represented by contiguous spans using interbase coordinates. This
      class is deprecated. Use SequenceInterval instead.'
    additionalProperties: false
    type: object
    properties:
      type:
        type: string
        const: SimpleInterval
        default: SimpleInterval
        description: MUST be "SimpleInterval"
      start:
        type: integer
        description: The start coordinate
      end:
        type: integer
        description: The end coordinate
    example:
      type: SimpleInterval
      start: 11
      end: 22
    required:
    - end
    - start
    - type
