Skip to content

Categorical Variant Extensions

Overview

Schema Reference

For the canonical extension reference tables (extension names, value types, and descriptions), see Variations — Extensions.

Categorical variant records contain extensions arrays at multiple levels of the JSON structure. Extensions carry ClinVar-specific information, VRS processing details, and linked data that are not part of the GA4GH Cat-VRS specification but are essential for interpreting the data.

All extensions follow the structure { "name": "<extension_name>", "value": <value> }, where the value type varies by extension. Most extensions carry simple scalar values (string, boolean, etc.). Extensions with complex value types — arrays of structured objects — are documented as custom extension structures in a dedicated section below.

CategoricalVariant Extensions

Extensions on the top-level CategoricalVariant record.

Extension Type Description
categoricalVariationType string The Cat-VRS category assigned to this variation: CanonicalAllele, CategoricalCnvChange, CategoricalCnvCount, or Undefined. Determines which constraint types are generated.
definingVrsVariationType string The VRS class assigned during variation identity processing (e.g., Allele, CopyNumberChange, CopyNumberCount, Not Available). Reflects the upstream classification used to route the variant through VRS processing.
clinvarVariationType string The variation type as reported by ClinVar (e.g., Deletion, single nucleotide variant, Duplication, Indel). Present when ClinVar provides a variation type.
clinvarSubclassType string The variation subclass as reported by ClinVar (e.g., SimpleAllele, Haplotype, CompoundHeterozygote). Present when ClinVar provides a subclass type.
clinvarCytogeneticLocation string The cytogenetic band location of the variation (e.g., 1p36.22, 17q21.31). Present when ClinVar provides a cytogenetic location.
vrsPreProcessingIssue string Issues detected during VRS pre-processing of the variation's input expressions. Present only when issues exist. May contain multiple issues separated by newlines.
vrsProcessingException string Errors returned by the external VRS Python processing service. Present only when errors occurred during VRS resolution.
clinvarHgvsList array
HgvsListItem		 Complete list of HGVS expressions from ClinVar for this variation, including nucleotide and protein expressions, molecular consequences (SO terms), and MANE transcript designations. See HGVS List custom extension structure below.
clinvarGeneList array
GeneListItem		 Gene associations for this variation from ClinVar: a #/gene/ reference to each gene's MappableConcept, with ClinVar's relationship type and source. See Gene List custom extension structure below.

Example

A complete extensions array for a successfully resolved CategoricalVariant:

[
  { "name": "categoricalVariationType", "value": "CanonicalAllele" },
  { "name": "definingVrsVariationType", "value": "Allele" },
  { "name": "clinvarVariationType", "value": "Deletion" },
  { "name": "clinvarSubclassType", "value": "SimpleAllele" },
  { "name": "clinvarCytogeneticLocation", "value": "1p36.22" },
  {
    "name": "clinvarHgvsList",
    "value": [
      {
        "nucleotideExpression": { "syntax": "hgvs.c", "value": "NM_004958.4:c.5992_5993del" },
        "nucleotideType": "coding",
        "maneSelect": true,
        "proteinExpression": { "syntax": "hgvs.p", "value": "NP_004949.3:p.Met1998fs" },
        "molecularConsequence": [
          {
            "name": "frameshift_variant",
            "system": "http://www.sequenceontology.org/browser/",
            "code": "SO:0001589",
            "iris": ["http://www.sequenceontology.org/browser/release_2.5.3/term/SO:0001589"]
          }
        ]
      },
      {
        "nucleotideExpression": { "syntax": "hgvs.g", "value": "NC_000001.11:g.11128044_11128045del" },
        "nucleotideType": "genomic, top-level"
      },
      {
        "nucleotideExpression": { "syntax": "hgvs.g", "value": "NC_000001.10:g.11188101_11188102del" },
        "nucleotideType": "genomic, top-level"
      }
    ]
  },
  {
    "name": "clinvarGeneList",
    "value": [
      {
        "gene": "#/gene/ncbigene:2475",
        "relationship_type": "within single gene",
        "source": "calculated"
      }
    ]
  }
]

When VRS processing issues are present, the error extensions appear alongside the classification extensions:

[
  { "name": "categoricalVariationType", "value": "Undefined" },
  { "name": "definingVrsVariationType", "value": "Not Available" },
  { "name": "clinvarVariationType", "value": "Microsatellite" },
  { "name": "clinvarSubclassType", "value": "SimpleAllele" },
  { "name": "vrsPreProcessingIssue", "value": "HGVS expression not valid: repeat expression" },
  { "name": "vrsProcessingException", "value": "Unable to resolve variant expression" }
]

SequenceReference Extensions

Extensions on SequenceReference objects nested within constraints[].allele.location.sequenceReference and members[].location.sequenceReference.

Extension Type Description
assembly string The genome assembly name for this sequence reference (e.g., GRCh38, GRCh37, NCBI36).

Example

{
  "type": "SequenceReference",
  "refgetAccession": "SQ.Ya6Rs7DHhDeg7YaOSg1EoNi3U_nQ9SvO",
  "residueAlphabet": "na",
  "molecularType": "genomic",
  "extensions": [
    { "name": "assembly", "value": "GRCh38" }
  ]
}

Custom Extension Structures

Extensions with complex value types use structured objects rather than simple scalars. The structures below define the shape of each custom extension's value field.

HGVS List

The clinvarHgvsList extension contains an array of HGVS expression objects, each representing one expression entry from ClinVar's HGVSlist element for the variation. Each object may contain:

Field Type Description
nucleotideExpression object The nucleotide HGVS expression with syntax (e.g., hgvs.c, hgvs.g) and value (the HGVS string). From 1.1.0, when ClinVar supplies an expression with no HGVS type letter, its submitted text is kept, unaltered, in this expression's extensions: invalidClinvarExpression (the submitted text) with expressionMerged: true when ClinVar also supplies a valid expression for the accession, which is the one listed; otherwise originalClinvarExpression (the submitted text) with expressionRepaired: true, on a listed expression with the type letter restored.
nucleotideType string The type of nucleotide expression as reported by ClinVar (e.g., coding, genomic, genomic, top-level).
maneSelect boolean true if this transcript is designated as MANE Select. Absent when not applicable.
manePlus boolean true if this transcript is designated as MANE Plus Clinical. Absent when not applicable.
proteinExpression object The protein HGVS expression with syntax (typically hgvs.p) and value. Present only when a protein-level expression exists for the nucleotide expression.
molecularConsequence array Sequence Ontology terms describing the predicted molecular consequence. Each entry includes code (SO identifier), system, name (SO term label), and iris (identifiers.org link).

Gene List

The clinvarGeneList extension contains an array of gene association objects (GeneListItem). Gene details (symbol, NCBI Gene id, HGNC mapping) are on the referenced gene MappableConcept in the gene section. Each object has all three fields:

Field Type Description
gene string #/gene/ncbigene:{id} reference to the gene MappableConcept in the gene bundle section.
relationship_type string The relationship between the variation and the gene as reported by ClinVar: within single gene, within multiple genes by overlap, genes overlapped by variant, near gene, upstream, near gene, downstream or asserted, but not computed.
source string The source of the gene association: submitted or calculated.