vod-source.yaml

$schema: http://json-schema.org/draft/2020-12/schema
title: GA4GH-Value-Object-Descriptor-Definitions
type: object
namespaces:
  vrs: https://raw.githubusercontent.com/ga4gh/vrs/1.2.1/schema/vrs.json#/definitions/

$defs:
  ValueObjectDescriptor:
    description: >-
      The abstract *Value Object Descriptor* parent class. All attributes
      of this parent class are inherited by descendent classes.
    oneOf:
      - $ref: "#/$defs/VariationDescriptor"
      - $ref: "#/$defs/CategoricalVariationDescriptor"
    heritable_properties:
      id:
        $ref_curie: "vrs:CURIE"
        description: >-
          Descriptor ID; MUST be unique within document.
      type:
        type: string
        description: >-
          MUST be VOD class name.
      label:
        type: string
        description: >-
          A primary label for the value object.
      description:
        type: string
        description: >-
          A free-text description of the value object.
      xrefs:
        type: array
        uniqueItems: true
        items:
          $ref_curie: "vrs:CURIE"
        description: >-
          List of CURIEs representing associated concepts.
      alternate_labels:
        type: array
        items:
          type: string
        description: >-
          List of strings representing alternate labels for the value object.
      extensions:
        type: array
        items:
          $ref: "#/$defs/Extension"
        description: >-
          List of resource-specific :ref:`Extensions <Extension>` needed to
          describe the value object.
    heritable_required: ["id", "type"]

  VariationDescriptor:
    description: >-
      This descriptor class is used for describing VRS Variation value objects.
    additionalProperties: false
    type: object
    properties:
      type:
        type: string
        enum: ["VariationDescriptor"]
        default: "VariationDescriptor"
        description: >-
          MUST be "VariationDescriptor".
      variation_id:
        $ref_curie: "vrs:CURIE"
        description: >-
          This SHOULD be provided if *variation* is omitted.
      variation:
        $ref_curie: "vrs:Variation"
        description: >-
          This SHOULD be provided if *variation_id* is omitted.
      molecule_context:
        type: string
        enum: ["genomic", "transcript", "protein"]
        description: >-
          The molecular context of this variant. Must be one of "genomic",
          "transcript", or "protein".
      structural_type:
        $ref_curie: "vrs:CURIE"
        description: >-
          The structural variant type associated with this variant. We RECOMMEND a descendent term of
          `SO:0001537 <http://www.sequenceontology.org/browser/current_release/term/SO:0001537>`_.
      expressions:
        $ref: "#/$defs/Expression"
        description: >-
          Typically HGVS or ISCN nomenclature expressions. Other systems relevant to the description
          of variation MAY be used.
      vcf_record:
        $ref: "#/$defs/VcfRecord"
        description: >-
          A VCF Record of the variant. This SHOULD be a single allele, the VCF genotype (GT) field
          should be represented in the *allelic_state* attribute.
      gene_context:
        description: >-
          A specific gene context that applies to this variant.
        oneOf:
          - $ref_curie: "vrs:CURIE"
          - $ref: "#/$defs/GeneDescriptor"
      vrs_ref_allele_seq:
        $ref_curie: "vrs:Sequence"
        description: >-
          A `VRS Sequence`_ corresponding to a "ref allele", describing the sequence expected at a
          `VRS SequenceLocation`_ reference.
      allelic_state:
        $ref_curie: "vrs:CURIE"
        description: >-
          We RECOMMEND that the *allelic_state* of a variation be described by terms from the
          Genotype Ontology (GENO). These SHOULD descend from concept
          `GENO:0000875 <http://purl.obolibrary.org/obo/GENO_0000875>`.

  Extension:
    description: >-
      The Extension class provides VODs with a means to extend descriptions
      with other attributes unique to a content provider. These extensions
      are not expected to be natively understood under VRSATILE, but may be
      used for pre-negotiated exchange of message attributes when needed.
    properties:
      type:
        type: string
        const: Extension
        description: MUST be "Extension".
      name:
        type: string
        description: A name for the Extension
      value:
        type: ["number", "string", "boolean", "object", "array", "null"]
        description: Any primitive or structured object
    required: ["type", "name"]

  Expression:
    maturity: draft
    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:
      type:
        type: string
        const: Expression
      syntax:
        type: string
        enum: ["hgvs.c", "hgvs.p", "hgvs.g", "hgvs.m", "hgvs.n", "hgvs.r", "iscn", "gnomad", "spdi"]
      value:
        type: string
      syntax_version:
        type: string
    required: ['type', 'syntax', 'value']

  CategoricalVariationDescriptor:
    description: >-
      This descriptor class is used for describing Categorical Variation value objects.
    additionalProperties: false
    type: object
    properties:
      type:
        type: string
        const: VariationDescriptor
        description: MUST be "VariationDescriptor".
      version:
        type: string
        description: The version of the Categorical Variation Descriptor.
      categorical_variation_id:
        $ref_curie: "vrs:CURIE"
        description: >-
          This SHOULD be provided if *categorical_variation* is omitted.
      categorical_variation:
        $ref: catvars.json/$defs/CategoricalVariation
        description: >-
          This SHOULD be provided if *variation_id* is omitted.
      members:
        description: >-
          VariationMember instances that fall within the functional domain
          of the Categorical Variation.
        type: array
        items:
          $ref: VariationMember

  VariationMember:
    description: >-
      A compact class for representing a variation context that is a member of a
      Categorical Variation. It supports one or more Expressions of a Variation
      and optionally an associated VRS ID.
    properties:
      type:
        type: string
        const: VariationMember
        description: MUST be "VariationMember"
      expressions:
        type: array
        items:
          $ref: Expression
        minItems: 1
      variation_id:
        $ref_curie: "vrs:CURIE"
    required: ['expressions']

  VcfRecord:
    deprecated: true
    description: >-
      This data class is used when it is desirable to pass data as expected from a VCF record.
      The class is only used as an optional attribute within a :ref:`VariationDescriptor`.
      The Genotype field from a VCF should be captured by the `allelic_state` attribute in
      the Variation Descriptor.
    additionalProperties: false
    type: object
    properties:
      genome_assembly:
        type: string
        description: Identifier for the genome assembly used to call the allele.
      chrom:
        type: string
        description: A chromosome or contig identifier.
      pos:
        type: string
        description: >-
          The reference residue-coordinate position, with the first
          residue having position 1.
      id:
        type: string
        description: >-
          A semicolon-separated list of unique identifiers where available.
          For example, dbSNP rsIDs. We RECOMMEND storing this information as
          a list in the :ref:`VariationDescriptor` `xrefs` field.
      ref:
        type: string
        description: >-
          Reference base as expected by the VCF specification.
      alt:
        type: string
        description: >-
          Alternate base as expected by the VCF specification.
      qual:
        type: string
        description: >-
          Quality: Phred-scaled quality score for the assertion made in ALT.
      filter:
        type: string
        description: >-
          Filter status: PASS if this position has passed all filters.
      info:
        type: string
        description: >-
          Additional information: Semicolon-separated series of additional
          information fields.
    required: ['genome_assembly', 'chrom', 'pos', 'ref', 'alt']