Schema

A schema is the explicit, machine-readable contract for a dataset: the field names, their types, their units, their allowed values, and the ontology terms they point at. Without one, a file is bytes you have to reverse-engineer. With one, a program can validate, join, and query it.

The questions people usually arrive with are adjacent. “Genetic data” typically means a small set of targeted markers, a few SNPs or one gene panel. “Genomic data” means the whole genome or a large, unbiased fraction of it, plus the derived layers: alignments, variant calls, expression matrices. The distinction matters mainly because the schemas differ. A 23andMe-style array export is a tab file with roughly 600,000 rows of rsID, chromosome, position, genotype. A whole-genome VCF is a specification with a typed header, INFO and FORMAT keys, and per-sample fields. And yes, two unrelated humans are roughly 99.9% identical at the single-nucleotide level, but that figure is an artifact of how you count: it excludes structural variation and it excludes sequence absent from the reference entirely. Long-read assemblies of diverse individuals recover tens of megabases of sequence missing from GRCh38, which is why the field moved toward pangenome references ¹. Ancestry also changes what you see in a personal genome, including how many variants get called and how well they are annotated ².

How it works

A usable schema does four things.

It names fields and fixes types. In VCF 4.2+, the header declares ##INFO=<ID=AF,Number=A,Type=Float,...> so a parser knows AF is one float per alternate allele, not a string.

It fixes units. Proteomics comes as NPX (arbitrary log2 units, Olink) or relative fluorescence (SomaScan) or ng/mL from an immunoassay. A column named IL6 with no unit field is unusable across platforms.

It binds terms to an ontology. “Fasting glucose” resolves to a LOINC code, a phenotype to an HPO term, a variant to HGVS plus a ClinVar accession. This is what makes cross-dataset joins possible instead of string-matching.

It specifies cardinality and required fields. One subject, many samples, many assays, many time points. Get this wrong and longitudinal data collapses into a single row.

Two standards are worth knowing. The GA4GH Phenopacket schema is a protobuf-defined representation that links phenotypic descriptions, measurements, and variant interpretations to a single subject using HPO, LOINC, and HGVS ³. It is the closest thing to a canonical container for “one person’s clinical plus genomic record” and has reference implementations in Java and Python ⁴. FAIR Genomes is a more prescriptive modality-level metadata schema built for NGS data reuse, with explicit modules for subject, material, sequencing run, and analysis ⁵. Use Phenopackets when you want interpretation-ready records, FAIR Genomes when you want provenance on the wet-lab side. Extensions that push omics into RDF exist as well ⁶.

In your own data

Where the schema physically lives:

• bcftools view -h your.vcf.gz — read the whole header. Check ##reference=, every ##INFO and ##FORMAT line, and ##FILTER. If the reference line is missing or says hg19 while your annotation database is GRCh38, every coordinate is wrong by a variable offset. This is the most common error we see.
• samtools view -H sample.cram — @SQ lines give contig names and lengths (SN:chr1 LN:248956422 is GRCh38; LN:249250621 is hg19). @RG gives read groups; without them GATK tools fail.
• RNA-seq: keep the exact GTF version next to the counts matrix. Ensembl 110 gene IDs are not interchangeable with GENCODE v44 at the edges, and dropping the .12 version suffix off ENSG00000141510.12 silently merges retired IDs.
• Proteomics: demand a long-format table with sample_id, time, assay, analyte, value, unit, lod_flag, plus a plate/batch column. Wide matrices with bare protein names in the header are where batch effects go to hide.
• CGM: store UTC plus an explicit offset. A 5-minute-interval trace with local timestamps loses or duplicates an hour at DST transitions, and postprandial windows computed across that boundary are garbage.

Write the contract down as JSON Schema or a Frictionless datapackage.json in the same directory, and run validation in CI. A 20-line check that asserts column presence, dtype, and unit strings will catch more real problems than any downstream model.

Limitations

A schema constrains structure, not truth. A perfectly valid VCF can be full of false positives in low-complexity regions. Ontology binding forces continuous biology into discrete codes, and the code you need sometimes does not exist. Schemas also age: adding a new assay usually means a migration, and long-term stewardship of personal genomic data is an unsolved operational problem, not just a format question ⁷. Rich, well-structured personal data is also more re-identifiable and more consequential to share, which is an ethical constraint on design, not an afterthought ⁸. Anything that looks clinically actionable in your files belongs in front of a clinician or genetic counselor, not in a notebook conclusion.

Woolf Software builds longitudinal molecular profiles of individuals: whole-genome sequencing, RNA sequencing, proteomics, blood biomarkers, and continuous glucose data, integrated into one model of you. Build your profile.