defaultSchema.yaml

$schema: https://json-schema.org/draft/2020-12/schema
title: Genomic Variation
$comment: 'version: ga4gh-beacon-variant-v2.0.0'
description: >-
  Schema for a genomic variant entry.
type: object
required:
  - variantInternalId
  - variation
properties:
  variation:
    oneOf:
      - $ref: https://raw.githubusercontent.com/ga4gh/vrs/1.2/schema/vrs.json#/definitions/MolecularVariation
      - $ref: https://raw.githubusercontent.com/ga4gh/vrs/1.2/schema/vrs.json#/definitions/SystemicVariation
      - $ref: '#/definitions/LegacyVariation'
  variantInternalId:
    description: >-
      Reference to the **internal** variant ID. This represents the primary
      key/identifier of that variant **inside** a given Beacon instance. Different
      Beacon instances may use identical id values, referring to unrelated variants.
      Public identifiers such as the GA4GH Variant Representation Id (VRSid) MUST
      be returned in the `identifiers` section. A Beacon instance can, of course,
      use the VRSid as their own internal id but still MUST represent this then in
      the `identifiers` section.
    type: string
    examples:
      - var00001
      - v110112
  identifiers:
    $ref: '#/definitions/Identifiers'
  molecularAttributes:
    $ref: '#/definitions/MolecularAttributes'
  caseLevelData:
    type: array
    description: caseLevelData reports about the variation instances observed in individual
      analyses.
    items:
      $ref: '#/definitions/CaseLevelVariant'
  variantLevelData:
    $ref: '#/definitions/VariantLevelData'
  frequencyInPopulations:
    type: array
    items:
      $ref: '#/definitions/FrequencyInPopulations'
definitions:
  LegacyVariation:
    type: object
    required:
      - variantType
      - alternateBases
      - location
    properties:
      location:
        $ref: https://raw.githubusercontent.com/ga4gh/vrs/main/schema/vrs.json#/definitions/Location
      variantType:
        description: >-
          The `variantType` declares the nature of the variation in relation
          to a reference. In a response, it is used to describe the variation. Examples
          here are e.g. structural variants such as `DUP` (increased allelic
          count of material from the genomic region  between `start` and `end` positions
          without assumption about the placement of the additional sequence) or `DEL`
          (deletion of sequence following `start`). Either `alternateBases` or `variantType`
          is required in representing a `LegacyVariation`.
        type: string
        examples:
          - SNP
          - DEL
          - DUP
          - BND
        default: SNP
      referenceBases:
        description: >-
          Reference bases for this variant (starting from `start`).
          * Accepted values: IUPAC codes for nucleotides (e.g. `https://www.bioinformatics.org/sms/iupac.html`).
          * N is a wildcard, that denotes the position of any base, and can be used
            as a standalone base of any type or within a partially known sequence.
          * an *empty value* is used in the case of insertions with the maximally
            trimmed, inserted sequence being indicated in `AlternateBases`.
        type: string
        pattern: ^([ACGTUNRYSWKMBDHV\-\.]*)$
        examples:
          - A
          - T
          - N
          - ''
          - ACG
      alternateBases:
        description: >-
          Alternate bases for this variant (starting from `start`).
          * Accepted values: IUPAC codes for nucleotides (e.g. `https://www.bioinformatics.org/sms/iupac.html`).
          * N is a wildcard, that denotes the position of any base, and can be used as
            a standalone base of any type or within a partially known sequence.
          * an *empty value* is used in the case of deletions with the maximally
            trimmed, deleted sequence being indicated in `ReferenceBases`
        type: string
        pattern: ^([ACGTUNRYSWKMBDHV\-\.]*)$
        examples:
          - T
          - G
          - N
          - AG
          - ''
  Identifiers:
    type: object
    properties:
      variantAlternativeIds:
        description: >-
          List of cross-referencing ID(s), for the variant in other databases
          (e.g. dbSNP, ClinVar, ClinGen, COSMIC), as `externalReferences` with CURIE(s).
        type: array
        items:
          $ref: ../common/externalReference.yaml
        examples:
          -   - id: dbSNP:rs587780345
                reference: https://www.ncbi.nlm.nih.gov/snp/rs587780345
                notes: dbSNP id
              - id: ClinGen:CA152954
                reference: https://reg.clinicalgenome.org/redmine/projects/registry/genboree_registry/by_caid?caid=CA152954
                notes: ClinGen Allele Registry id
              - id: UniProtKB:P35557#VAR_003699
                reference: https://www.uniprot.org/uniprot/P35557#VAR_003699
          -   - id: OMIM:164757.0001
                reference: https://www.omim.org/entry/164757#0001
      genomicHGVSId:
        description: HGVSId descriptor.
        type: string
        examples:
          - NC_000017.11:g.43057063G>A
      transcriptHGVSIds:
        description: List of HGVSId descriptor(s) at transcript level.
        type: array
        items:
          type: string
        examples:
          -   - NC 000023.10(NM004006.2):c.357+1G
      proteinHGVSIds:
        description: >-
          List of HGVSId descriptor(s) at protein level (for protein-altering
          variants).
        type: array
        items:
          type: string
        examples:
          -   - NP_009225.1:p.Glu1817Ter
          -   - LRG 199p1:p.Val25Gly (preferred)
      clinvarVariantId:
        description: ClinVar variant id. Other id values used by ClinVar can be added
          to `variantAlternativeIds`
        pattern: ^(clinvar:)?\d+$
        type: string
        examples:
          - clinvar:12345
          - '9325'
  MolecularAttributes:
    type: object
    properties:
      geneIds:
        description: >-
          Symbolic names or identifiers used for a gene
        type: array
        items:
          type: string
        examples:
          -   - ACE2
          -   - BRCA1
              - ENSG00000012048
      genomicFeatures:
        description: List of Genomic feature(s) affected by the variant.
        type: array
        items:
          $ref: '#/definitions/GenomicFeature'
      molecularEffects:
        description: >-
          Ontology term that includes describes the class of molecular
          consequence generated by the variant. Values from SO (Sequence Ontology) are recommended, e.g. 
          `SO:0001583: missense variant`.
        type: array
        items:
          $ref: https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/framework/json/common/ontologyTerm.json
        examples:
          - id: SO:0002322
            label: stop gained NMD escaping 
          - id: SO:0001583
            label: missense variant
      aminoacidChanges:
        description: Lisf of change(s) at aminoacid level for protein affecting variants.
        type: array
        items:
          type: string
        examples:
          -   - V304*
  GenomicFeature:
    description: >-
      Genomic feature(s) related to the variant.
      NOTE: Although genes could also be referenced using these attributes, they
      have an independent section to allow direct queries.
    type: object
    properties:
      featureClass:
        description: >-
          Ontology term that describes the class of genomic feature affected
          by the variant. Values from SO (Sequence ontology) are recommended, e.g.
          `SO:0001623: 5 prime UTR variant`
        $ref: https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/framework/json/common/ontologyTerm.json
        examples:
          - id: SO:0001623
            label: 5 prime UTR variant
      featureID:
        description: >-
          Where applicable, ID/accession/name of genomic feature related
          to the `featureClass`, preferably in CURIE format. If the value is a gene
          id or name, it points to the gene related to the `featureClass`, e.g. `the
          5 prime UTR upstream of TP53`
        $ref: https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/framework/json/common/ontologyTerm.json
        examples:
          - id: HGNC:11998
            label: TP53
    required:
      - featureClass
  PhenoClinicEffect:
    description: >-
      List of annotated effects on disease or phenotypes.
    type: object
    properties:
      conditionId:
        description: Internal identifier of the phenotype or clinical effect.
        type: string
        examples:
          - disease1
          - phen2234
      category:
        description: Ontology term for the type of disease, condition, phenotypic measurement, etc.
        $ref: https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/framework/json/common/ontologyTerm.json
        examples:
          - id: MONDO:0000001
            label: disease or disorder
          - id: HP:0000118
            label: phenotypic abnormality
      effect:
        description: >-
          Ontology term for the phenotypic or clinical effect
        $ref: https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/framework/json/common/ontologyTerm.json
        examples:
          - id: MONDO:0003582
            label: hereditary breast ovarian cancer syndrome
          - id: HP:0000256
            label: macrocephaly
      clinicalRelevance:
        description: >-
          Indication of the clinical relevance of the variant
          Recommended: A value from the five-tiered classification from the American
          College of Medical Genetics (ACMG) designed to describe the likelihood that
          a genomic sequence variant is causative of an inherited disease. (NCIT:C168798).
        type: string
        enum:
          - benign
          - likely benign
          - uncertain significance
          - likely pathogenic
          - pathogenic
        example: pathogenic
      evidenceType:
        description: >-
          Ontology term for the type of evidence supporting variant-disease association
          Recommended: values from the Evidence & Conclusion Ontology (ECO)
        $ref: https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/framework/json/common/ontologyTerm.json
        examples:
          - id: ECO:0000361
            label: inferential evidence
          - id: ECO:0000006
            label: experimental evidence
      annotatedWith:
        $ref: '#/definitions/SoftwareTool'
    required:
      - conditionId
      - effect
  FrequencyInPopulations:
    type: object
    properties:
      source:
        type: string
        description: The study
        examples:
          - The Genome Aggregation Database (gnomAD)
          - The European Genome-phenome Archive (EGA)
      sourceReference:
        type: string
        description: A reference to further documentation or details.
        examples:
          - https://gnomad.broadinstitute.org/
          - https://ega-archive.org/
      version:
        type: string
        description: version of the source data.
        examples:
          - gnomAD v3.1.1
      frequencies:
        type: array
        items:
          $ref: '#/definitions/PopulationFrequency'
        minItems: 1
    required:
      - source
      - sourceReference
      - frequencies
  PopulationFrequency:
    type: object
    properties:
      population:
        type: string
        description: >-
          A name for the population. A population could an ethnic, geographical
          one or just the members of a study.
        examples:
          - East Asian
          - ICGC Chronic Lymphocytic Leukemia-ES
          - Men
          - Children
      alleleFrequency:
        type: number
        description: Allele frequency between 0 and 1.
        examples:
          - 3.186e-05
    required:
      - population
      - alleleFrequency
  CaseLevelVariant:
    type: object
    description: ''
    properties:
      id:
        description: >-
          Internal id of this case level *instance* of the variant. This
          is an optional housekeeping parameter and should not be confused with the
          identifier of the variant (`variantInternalId`).
        type: string
        examples:
          - id0001-var101101118
      individualId:
        description: Reference to individual ID (`individual.id`)
        type: string
        examples:
          - ind0001
      biosampleId:
        description: Reference to biosample ID (`biosample.id`)
        type: string
        examples:
          - bs001104
      analysisId:
        description: Reference to the bioinformatics analysis ID (`analysis.id`)
        type: string
        examples:
          - pgxcs-kftvldsu
      runId:
        description: Reference to the experimental run ID (`run.id`)
        type: string
        examples:
          - SRR10903401
      zygosity:
        description: >-
          Ontology term for zygosity in which variant is present in the
          sample from the Zygosity Ontology (GENO:0000391) , e.g `heterozygous` (GENO:0000135)
        $ref: https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/framework/json/common/ontologyTerm.json
        examples:
          - id: GENO:0000135
            label: heterozygous
          - id: GENO:0000136
            label: homozygous
          - id: GENO:0000604
            label: hemizygous X-linked
      alleleOrigin:
        description: >-
          Ontology value for allele origin of variant in sample from the
          Variant Origin (SO:0001762). Categories are `somatic variant`, `germline
          variant`, `maternal variant`, `paternal variant`, `de novo variant`, `pedigree
          specific variant`, `population specific variant`. Corresponds to Variant
          Inheritance in FHIR.
        $ref: https://raw.githubusercontent.com/ga4gh-beacon/beacon-v2/main/framework/json/common/ontologyTerm.json
        examples:
          - id: SO:0001777
            label: somatic variant
          - id: SO:0001778
            label: germline variant
          - id: SO:0001775
            label: maternal variant
          - id: SO:0001776
            label: paternal variant
          - id: SO:0001781
            label: de novo variant
          - id: SO:0001779
            label: pedigree specific variant
          - id: SO:0001780
            label: population specific variant
      clinicalInterpretations:
        type: array
        items:
          $ref: '#/definitions/PhenoClinicEffect'
      phenotypicEffects:
        type: array
        items:
          $ref: '#/definitions/PhenoClinicEffect'
    required:
      - biosampleId
  VariantLevelData:
    type: object
    properties:
      clinicalInterpretations:
        type: array
        items:
          $ref: '#/definitions/PhenoClinicEffect'
      phenotypicEffects:
        type: array
        items:
          $ref: '#/definitions/PhenoClinicEffect'
  SoftwareTool:
    type: object
    properties:
      toolName:
        description: Name of the tool.
        type: string
        examples:
          - Ensembl Variant Effect Predictor (VEP)
      version:
        description: Version used.
        type: string
        examples:
          - rel 104
      toolReferences:
        description: References to the tool
        type: object
        properties: {}
        additionalProperties: true
        examples:
          - bio.toolsId: https://bio.tools/vep
          - url: https://www.ensembl.org/vep
        minProperties: 1
    required:
      - toolName
      - version
      - toolReferences
additionalProperties: true