ID References¶

Overview¶

The ClinVar-GKM bundle uses typed identifiers and #/ JSON pointer references to link objects across bundle sections. This page documents all identifier formats, reference patterns, and how to resolve them.

Identifier Namespaces¶

All ClinVar-GKM identifiers use a prefix namespace to indicate the resource type:

VCV and RCV aggregate statement IDs use a hierarchical format without a namespace prefix — see VCV Statement IDs and RCV Statement IDs.

JSON Pointer References¶

Objects reference each other using #/{section}/{key} strings. To resolve a reference:

1. Split the string on / — the second segment is the bundle section name, the third is the key
2. Look up the key in the named section of the bundle

Reference Patterns¶

Where References Appear¶

Resolution Example¶

import gzip
import json

# Load the bundle
with gzip.open("clinvar-gkm_00-latest.json.gz", "rt") as f:
    bundle = json.load(f)

def resolve(bundle, ref):
    """Resolve a #/section/key reference to the target object."""
    parts = ref.lstrip("#/").split("/", 1)
    return bundle[parts[0]][parts[1]]

# Look up a variation
variant = bundle["variation"]["clinvar:10"]

# Resolve its allele member
allele = resolve(bundle, variant["members"][0])

# Resolve the allele's location
location = resolve(bundle, allele["location"])

# Resolve the location's sequence reference
seq_ref = resolve(bundle, location["sequenceReference"])

SCV Proposition IDs¶

SCV proposition IDs combine the SCV accession with an uppercase proposition type code:

{scv_id}-{PROP_CODE}

Examples: SCV001234567-PATH, SCV004565358-PROG, SCV004565358-TR

Target (somatic evidence line) propositions use the clinical impact assertion type codes: PROG, DIAG, TR.

VCV Statement IDs¶

VCV aggregate statements use a hierarchical ID format reflecting the aggregation layer:

Components:

• group — statement group: G (Germline), S (Somatic), O (Oncogenicity)
• PROP — proposition type code (uppercase): PATH, ONCO, SCI, ASSOC, etc.
• level — submission level: PG, EP, CP, NOCP, NOCL, FLAG
• TIER — classification tier (somatic only, uppercase): TIER 1, TIER 2, etc.

RCV Statement IDs¶

RCV aggregate statements follow the same pattern as VCV but with an RCV accession:

The component abbreviations are the same as VCV.

VCV/RCV Proposition IDs¶

VCV and RCV proposition IDs use the accession (without version) in the same layered format:

External Cross-References¶

Variation records contain mappings to external databases using standardized URL formats:

Condition records contain mappings to disease/phenotype databases (OMIM, MONDO, HPO, Orphanet, MeSH) and a primaryCoding from MedGen.