.. _clinvar-structure:

ClinVar XML Structure
=====================

ClinVar distributes variant data in XML format with three main record types:
VCV, RCV, and SCV. 
Understanding their relationship is essential for effective database design.

Record Types
------------

**VCV (Variation ClinVar)**
    The aggregate record for a single genetic variant. Each VCV represents
    one unique variant (e.g., a specific SNV or deletion) and consolidates
    all submissions and interpretations for that variant. 
    VCV accessions follow the format ``VCV000000123``.

**RCV (Reference ClinVar)**
    Condition-specific interpretation records. Each RCV links a variant
    to a specific condition (e.g., "BRCA1 variant AND Breast cancer").
    A single VCV may have multiple associated RCVs if the variant has
    been interpreted for different conditions.
    RCV accessions follow the format ``RCV000000123``.

**SCV (Submitted ClinVar)**
    Individual submission records from clinical laboratories and research
    groups.
    Each SCV represents one submitter's interpretation of a 
    variant-condition pair.
    Multiple SCVs are aggregated into RCVs.
    SCV accessions follow the format ``SCV000000123``.

Record Hierarchy
----------------

.. code-block:: text

   VCV (Variant)
   ├── RCV (Variant + Condition A)
   │   ├── SCV (Submission 1)
   │   └── SCV (Submission 2)
   └── RCV (Variant + Condition B)
       └── SCV (Submission 3)

XML File Distribution
---------------------

ClinVar provides two separate XML files:

``ClinVarVCVRelease_*.xml.gz``
    Contains VCV records with embedded RCV summaries. 
    Use this file for variant-centric queries.

``ClinVarRCVRelease_*.xml.gz``
    Contains full RCV records with detailed SCV data.
    Use this file for condition-centric queries or when detailed submission 
    information is required.

Choosing a Database Structure
-----------------------------

For most use cases, building both VCV and RCV databases and joining
them via ``canonical_spdi`` provides the most flexibility. 
The VCV database offers efficient variant lookups, while the RCV database
provides detailed condition and submission data for enrichment.