{
  "$schema": "http://json-schema.org/draft-07/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. In a request, it is used to declare the type of event the Beacon client is looking for. If in queries variants can not be defined through a sequence of one or more bases (`precise` variants) it can be used standalone (i.e. without `alternateBases`) together with positional parameters. Examples here are e.g. queries for 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, with the exception of range queries (single `start` and `end` parameters).",
          "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. As example, a query of `ANNT` the Ns can take take any form of `[ACGT]` and will match `ANNT`, `ACNT`, `ACCT`, `ACGT` ... and so forth. * an *empty value* is used in the case of insertions with the maximally trimmed, inserted sequence being indicated in `AlternateBases`. NOTE: Many Beacon instances could not support UIPAC codes and it is not mandatory for them to do so. In such cases the use of [ACGTN] is mandated.",
          "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 beused as a standalone base of any type or within a partially knownsequence. As example, a query of `ANNT` the Ns can take take any form of[ACGT] and will match `ANNT`, `ACNT`, `ACCT`, `ACGT` ... and so forth.* an *empty value* is used in the case of deletions with the maximally trimmed, deleted sequence being indicated in `ReferenceBases`* Categorical variant queries, e.g. such *not* being represented through sequence & position, make use of the `variantType` parameter. * Either `alternateBases` or `variantType` is required.",
          "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.json"
        },
        "examples": [
          [
            {"id": "dbSNP:rs587780345", "reference": "https://www.ncbi.nlm.nih.gov/snp/rs587780345", "notes": "dbSNP id"},
            {"id": "ClinGen:CA152954", "reference": "http://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": {
       "type": "array",
        "items": {
          "type": "string"
        },
        "examples": [
          ["ACE2"], ["BRCA1"]
        ]
      },
      "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 Ensembl Glossary Variant Consequence (ENSGLOSSARY:0000134 ontology branch) are recommended, e.g. Stop gained, Missense variant, Coding sequence variant.",
        "type": "array",
        "items": {
          "$ref": "https://raw.githubusercontent.com/ga4gh-beacon/beacon-framework-v2/main/common/ontologyTerm.json"
        },
        "examples": [
          { "id": "ENSGLOSSARY:0000143", "label": "Stop gained" },
          { "id": "ENSGLOSSARY:0000150", "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 Ensembl Glossary (ENSGLOSSARY ontology) are recommended, e.g. protein coding gene, non-coding RNA, long non-coding RNA. ",
          "$ref": "https://raw.githubusercontent.com/ga4gh-beacon/beacon-framework-v2/main/common/ontologyTerm.json",
          "examples": [
            { "id": "ENSGLOSSARY:0000158", "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-framework-v2/main/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-framework-v2/main/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-framework-v2/main/common/ontologyTerm.json",
          "examples": [
            {
              "id": "MONDO:0003582",
              "label": "hereditary breast ovarian cancer syndrome"
            },
            { "id": "HP:0000256", "label": "macrocephaly" }
          ]
        },
        "clinicalRelevance": {
          "description": "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 from the Evidence & Conclusion Ontology (ECO). ",
          "$ref": "https://raw.githubusercontent.com/ga4gh-beacon/beacon-framework-v2/main/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": [0.00003186]
        }
      },
      "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-framework-v2/main/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-framework-v2/main/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": "http://www.ensembl.org/vep" }
          ],
          "minProperties": 1
        }
      },
      "required": ["toolName", "version", "toolReferences"]
    }
  },
  "additionalProperties": true
}