Output "Bundle" Format Overview¶

The ClinVar-GKM release file uses a bundle format — a single JSON object with named sections at the root level. A bundle is a dictionary-style approach to organizing a large amount of data across heterogeneous classes in a single file, where each section is a keyed collection of objects of the same class. The key is the object's unique identifier, and the value is the complete object.

This design eliminates duplication (a sequence reference shared by thousands of locations appears once), keeps individual objects compact, and enables efficient lookups by ID.

Structure¶

{
  "sequenceReference": { "<key>": { ... }, ... },
  "location":          { "<key>": { ... }, ... },
  "allele":            { "<key>": { ... }, ... },
  "copyNumberCount":   { "<key>": { ... }, ... },
  "copyNumberChange":  { "<key>": { ... }, ... },
  "gene":              { "<key>": { ... }, ... },
  "variation":         { "<key>": { ... }, ... },
  "condition":         { "<key>": { ... }, ... },
  "conditionSet":      { "<key>": { ... }, ... },
  "therapy":           { "<key>": { ... }, ... },
  "therapyGroup":      { "<key>": { ... }, ... },
  "submitter":            { "<key>": { ... }, ... },
  "propositionPathogenicity":         { "<key>": { ... }, ... },
  "propositionOncogenicity":          { "<key>": { ... }, ... },
  "propositionSomaticClinicalImpact": { "<key>": { ... }, ... },
  "propositionClinvarCustom":         { "<key>": { ... }, ... },
  "evidenceLine":         { "<key>": { ... }, ... },
  "scv":               { "<key>": { ... }, ... },
  "vcv":               { "<key>": { ... }, ... },
  "rcv":               { "<key>": { ... }, ... }
}

Sections¶

Variation Data Sections¶

These sections contain the VRS and Cat-VRS variant data:

sequenceReference — Reference sequences (chromosomes, transcripts) with refget accessions, molecule type, and assembly information. Keyed by refget accession (e.g., SQ.0iKlIQk2oZLoeOG9P1riRU6hvL5Ux8TV).

location — Sequence locations with start/end coordinates. Each location references its sequence via #/sequenceReference/{key}. Keyed by VRS location ID (e.g., ga4gh:SL.Eg_6kV6Bb4FMjm9kEolHZ_4NhU8lBEsZ).

allele — VRS alleles with state, expressions (SPDI, HGVS, gnomAD), and copy number data. Each allele references its location via #/location/{key}. Keyed by VRS allele ID (e.g., ga4gh:VA.ELQCnIBGqaTl0AEE0Az18XZ2cgIHAQIY).

copyNumberCount — VRS CopyNumberCount records for copy number variants with absolute copy counts. Each references its location via #/location/{key}. Keyed by VRS ID.

copyNumberChange — VRS CopyNumberChange records for copy number variants with relative change types (gain, loss). Each references its location via #/location/{key}. Keyed by VRS ID.

gene — Gene MappableConcepts with NCBI Gene primaryCoding and HGNC mapping. Keyed by ncbigene:{gene_id} (e.g., ncbigene:3077).

variation — ClinVar variations with their defining constraints, cross-references, HGVS expressions, and gene associations. Most variations are represented as CanonicalAlleles with a defining VRS allele (via #/allele/); copy number variants use a defining location (via #/location/); complex variants use a generalized representation. Keyed by clinvar:{variation_id} (e.g., clinvar:10).

Supporting Data Sections¶

These sections contain the condition, therapy, submitter, and proposition reference data:

condition — Trait and disease concepts from ClinVar, with MedGen primary coding and cross-references to OMIM, MONDO, HPO, Orphanet, and MeSH. Keyed by clinvar.trait:{trait_id} (e.g., clinvar.trait:9580).

conditionSet — Multi-condition groupings with member condition references (concepts → #/condition/) and a membership operator (AND or OR). Keyed by clinvar.traitset:{trait_set_id} (e.g., clinvar.traitset:1234).

therapy — Individual drug therapies (Therapy MappableConcepts) referenced by therapeutic-response propositions. Content-addressed and deduplicated (therapies have no native ClinVar id). Keyed by clinvar.therapy:{sha256}.

therapyGroup — Combination (multi-drug) therapies (TherapyGroup ConceptSets) whose concepts reference member therapies via #/therapy/, with a membership operator. Content-addressed and deduplicated. Keyed by clinvar.therapygroup:{sha256}.

submitter — Submitting organizations with name and identifier. Keyed by clinvar.submitter:{submitter_id} (e.g., clinvar.submitter:500139).

propositionPathogenicity, propositionOncogenicity, propositionSomaticClinicalImpact, propositionClinvarCustom — Classification propositions defining what a statement asserts (proposition type, predicate, subject, object, qualifiers). Propositions are delivered in four sections grouped by meaning (what kind of claim the proposition makes), so a section holds one kind of claim at every level (SCV, VCV, RCV):

• propositionPathogenicity — VariantPathogenicityProposition (germline classifications); subject → object (a #/condition/ or #/conditionSet/), with typed qualifiers on SCVs (geneContextQualifier, modeOfInheritanceQualifier, penetranceQualifier).
• propositionOncogenicity — VariantOncogenicityProposition; subject → object (the tumor type, a #/condition/ or #/conditionSet/).
• propositionSomaticClinicalImpact — VariantClinicalSignificanceProposition (SCV, VCV, RCV) and the VariantDiagnosticProposition, VariantPrognosticProposition and VariantTherapeuticResponseProposition that SCV evidence lines target. For Therapeutic Response, object references the therapy (#/therapy/ single, or #/therapyGroup/ combination) and the condition moves to conditionQualifier (#/condition/ or #/conditionSet/); the others point object at a condition.
• propositionClinvarCustom — the 9 Clinvar* types (e.g. ClinvarRiskFactorProposition, ClinvarDrugResponseProposition) plus ClinvarUndefinedProposition — open subtypes of the VA-Spec SubjectVariantProposition base, each carrying its own real type name; subject → object with typed qualifiers (geneContextQualifier, modeOfInheritanceQualifier, penetranceQualifier).

Each contains the SCV, VCV, and RCV propositions of its kind. Keyed by proposition ID (e.g., SCV001234567-PATH for SCVs, VCV000012582.63-G-PATH-CP for VCVs). A #/proposition<Meaning>/{id} pointer names the exact section a proposition lives in; the section is a function of the proposition type alone.

Statement Sections¶

These sections contain the classification statements:

evidenceLine — Evidence line records referenced by statements via hasEvidenceLines arrays of #/evidenceLine/ pointers. Merges SCV, VCV, and RCV evidence lines into a single section.

scv — Submitted classification statements. Each SCV carries a classification, strength, direction, proposition reference, contributions (with submitter references), evidence line references, citations, assertion method, and extensions with submitted condition provenance. Keyed by clinvar.submission:{scv_id}.{version}.

vcv — Variation-level aggregate classification statements. VCVs aggregate SCVs across a variation by classification, priority (somatic tiers), and submission level contribution. Evidence line references point to records in #/evidenceLine/. Keyed by the VCV layer ID.

rcv — Condition-level aggregate classification statements. RCVs follow the same aggregation structure as VCVs but are scoped to a specific RCV accession (variation + condition). Evidence line references point to records in #/evidenceLine/.

JSON Pointer References¶

Objects reference each other using #/{section}/{key} strings instead of embedding full objects inline. This keeps the file compact and enables consumers to resolve references by looking up the key in the named section.

Reference Patterns¶

Resolving References¶

To resolve a reference string like #/allele/ga4gh:VA.abc123:

1. Split on / — the second segment is the section name (allele), the third is the key (ga4gh:VA.abc123)
2. Look up the key in the named section of the root object
3. The value at that key is the resolved object

Reference Depth¶

References are one level deep — a resolved object may itself contain references, but those are always to other root-level sections, never nested references within references. A consumer can fully resolve any object by following at most 2-3 hops (e.g., variation → allele → location → sequenceReference).

MappableConcept Pattern¶

Several fields across statements use a MappableConcept structure — a typed object with a display name, optional primary coding, and optional extensions:

{
  "conceptType": "Classification",
  "name": "Pathogenic",
  "primaryCoding": {
    "code": "pathogenic",
    "system": "ACMG Guidelines, 2015"
  },
  "extensions": [ ... ]
}

Fields that use this pattern:

• classification — the clinical significance label (conceptType: "Classification")
• strength — the evidence strength (conceptType: "Strength")
• evidenceOutcome — the evidence line outcome (conceptType: "Outcome")
• strengthOfEvidenceProvided — the evidence line strength (conceptType: "Strength")

The conceptType identifies the kind of concept. The name is the human-readable display value. The primaryCoding provides a machine-readable code and system when available. Not all instances carry primaryCoding — aggregate VCV/RCV classifications, for example, may only have conceptType and name.

Bundle Schema¶

The bundle structure described above is formalized as a JSON Schema, authored to the GKM Starter Kit bundle-schema conventions:

JSON Schema: clinvar-gkm-bundle.schema.json

• Draft 2020-12, root type: object — each root property is one of the bundle sections, and additionalProperties: false rejects unknown sections.
• Each section is a keyed map whose keys are constrained by that section's id pattern (patternProperties) and whose values $ref the appropriate GA4GH class schema by versioned W3ID URI — VRS, Cat-VRS, VA-Spec, and GKM-Core for the shared types, and the ClinVar-GKM subtypes (ClinvarScvStatement, ClinvarCategoricalVariant, the Clinvar*Proposition family, …) for the ClinVar-specific ones.
• No section is individually required, so the same schema validates a monthly full bundle, a weekly delta, and a sub-bundle extract — each carries only the sections it touches.

The schema constrains the bundle's shape (which sections may appear, how their keys are formed, and what each value validates against). The starter-kit's companion invariant — that every #/section/key pointer resolves within the bundle — is a producer-side guarantee, not expressible in JSON Schema alone.

Validating with the GKM Toolkit¶

The GKM Toolkit (ga4gh.gkm) validates a bundle against this schema when you supply the ClinVar-GKM schemas and the GA4GH schemas they reference, as a validator= for validate_bundle_schema. Every published bundle is validated this way before release (Release Validation); Working in Python shows the code. The toolkit's loader (load_bundle, resolve, export) needs upstream updates before it reads ClinVar-GKM bundles.

Parquet Output¶

In addition to the JSON bundle, the latest release is published as typed Parquet files, one per table (22 tables: the bundle sections, with the VCV and RCV evidence lines in their own tables). They are written by BigQuery EXPORT DATA queries, not by the assembler, and use columnar storage with named, typed columns for each section's fields, making them suitable for analytical workloads, DuckDB, pandas, or Apache Spark.

See Export & Distribute for how the Parquet files are produced (derived from the bundle, latest release only). To query them — every table's columns, how the tables join, and runnable recipes — see Query the Data.

Inlining References¶

A #/section/key reference resolves with one dictionary lookup in the bundle; ID References shows a small resolve() helper, and Working in Python follows a statement down to its sequence reference. The GKM Toolkit's Bundle.export() inlines references for the bundles it can load; its loader does not yet read ClinVar-GKM 1.1.0 bundles (see Loading bundles).