# Controlled Vocabularies vs. Free-Text Annotations in Genomics Metadata A controlled vocabulary restricts a metadata field to a fixed list of approved terms, each with a stable identifier and a written definition, while a free-text annotation is any natural-language string the depositor chooses to write. The difference between controlled vocabulary and free text in genomics metadata is the difference between values a machine can filter, count, and join, and prose that only a human can interpret. Rule of thumb: make a field controlled if you will ever filter, group, count, join, or validate it, and leave it free text if the field exists to carry nuance, caveats, or context for a human reader. Most working groups use both, in the same sample sheet, on purpose. The common failure is not picking the wrong philosophy. It is leaving free text in fields that later need aggregation, then discovering the problem after deposit, when the strings sit in a public archive, cited by papers you cannot fix. ## Why Metadata Decides Whether Genomics Data Is Reusable Metadata is the data about the data. For a sequencing experiment, metadata includes the organism, tissue or environment, disease state, cell line, library preparation, instrument, protocol, collection date, geographic location, and the identifiers that link reads to samples to projects. The reads in a FASTQ file are identical whether they came from healthy liver or a cirrhotic one. Only the metadata tells you which. Public archives are the backbone of genomics data storage. The three members of the International [Nucleotide Sequence](/knowledge/molecular-biology/nucleotide-sequence) Database Collaboration (the Sequence Read Archive at NCBI, the European Nucleotide Archive at EMBL-EBI, and DDBJ in Japan) mirror one another and hold read data at petabase scale. The scientific value of those reads depends almost entirely on the structured fields submitted alongside them. A run with no organism, no tissue, and no condition is storage cost with no reuse value. Information retrieval research has documented the core problem since the 1980s: different people rarely choose the same word for the same thing. One depositor writes breast cancer, the next writes invasive ductal carcinoma, the next writes TNBC (triple negative), and the next writes mammary tumor. A literal string search for any one of those phrases misses the others. Counts come out wrong. Meta-analyses miss eligible datasets. Pipelines that select samples by metadata select the wrong samples, silently. The FAIR principles, published in 2016, name the fix. Metadata should be rich enough to find and reuse the data, and it should use formal, accessible, shared, and broadly applicable vocabularies. Good bioinformatics [data management](/blog/guides/data-management-basics-principles-processes-and-best-practices) treats the vocabulary decision as part of experimental design, made before the first sample is collected, not as a formality to clean up at submission. Scale settles the argument. At 20 samples, you can fix strings by hand at analysis time. At 20,000 samples across 12 sites, you cannot, and neither can the next person who wants your data. ## What a Controlled Vocabulary Is A controlled vocabulary is a finite, curated list of terms. Each term carries a stable identifier (an ID that never changes), a preferred human-readable label, a written definition, and usually a set of synonyms and relationships to other terms. The list is governed: someone decides what belongs, publishes dated releases, and retires terms through an explicit obsolescence process rather than by deleting them. Four related structures get called vocabularies, and the differences matter for design: - A codelist (also called an enumeration) is a flat list of allowed values with no internal structure. A status field that accepts exactly draft, submitted, and published is a codelist. - A thesaurus adds synonyms, so a search on any synonym retrieves the concept. MeSH, the Medical Subject Headings maintained by the US National Library of Medicine, is the classic example. - A taxonomy is a classification tree. NCBI Taxonomy, which assigns every named organism a stable numeric identifier, is the workhorse example in genomics. Human is 9606, house mouse is 10090. - An ontology is a controlled vocabulary plus typed relationships (is_a, part_of, regulates) that software can reason over. The Gene Ontology, UBERON, and the Human Phenotype Ontology are ontologies. Every ontology is a controlled vocabulary. Not every controlled vocabulary is an ontology, and you do not always need the ontology. ### The Anatomy of a Term The Gene Ontology term for programmed cell death shows the parts a well-formed term carries: | Property | Value for this term | |--|--| | Identifier | GO:0006915 | | Preferred label | apoptotic process | | Definition | A programmed cell death process (paraphrased from the ontology text) | | Parent class | GO:0008219 (cell death) | | Retained synonym | apoptosis (the term's earlier label) | Two properties make identifiers like this useful in genomics data storage and reuse. First, they resolve. Ontology identifiers follow the PURL convention (a persistent URL scheme), so GO:0006915 resolves at purl.obolibrary.org/obo/GO_0006915 and the full Gene Ontology downloads at purl.obolibrary.org/obo/go.owl. Second, they are versioned. Each release carries a version identifier, and retired terms are marked obsolete with a pointer to any replacement rather than deleted. The retained synonym for apoptosis is why a string search still finds the term in ontology-aware systems, while a plain file search across depositor prose does not get the same guarantee. ### Vocabularies You Will Actually Use | Metadata field | Vocabulary | Example value | |--|--|--| | Organism | NCBI Taxonomy | 9606 (human), 10090 (house mouse) | | Anatomy across species | UBERON | UBERON:0002107 (liver) | | Cell type | Cell Ontology (CL) | CL:0000084 (T cell) | | Disease | MONDO, EFO, Disease Ontology | IDs of the form MONDO:nnnnnnn | | Phenotype | Human Phenotype Ontology (HPO) | HP:0001250 (seizure) | | Molecular process and function | Gene Ontology (GO) | GO:0006915 (apoptotic process) | | Sequence features | Sequence Ontology (SO) | SO:0000704 (gene) | | Environment | ENVO | IDs of the form ENVO:nnnnnnn | | Bioinformatics topics and operations | EDAM | IDs of the form topic_XXXX and operation_XXXX | | Chemical entities | ChEBI | CHEBI:15377 (water) | | Units | Units of Measurement (UO), UCUM | IDs of the form UO:nnnnnnn | | Cell lines | Cellosaurus | CVCL identifiers | | Literature indexing | MeSH | Descriptor codes | The OBO Foundry coordinates many of these vocabularies under shared principles: open licensing, a common format, one identifier space per ontology, regular releases, and an explicit obsolescence policy. EFO, maintained at EMBL-EBI, follows similar practices and is served through the same channels. Standards lean on vocabularies explicitly. The Genomic Standards Consortium's MIxS standard (Minimum Information about any (x) Sequence) defines the checklist fields a sequence record should carry, and its three environment fields (env_broad_scale, env_local_scale, env_medium) are meant to be filled with ENVO terms. UniProt shows the hybrid pattern inside a single database entry: a controlled keyword list, each keyword with its own stable identifier, sits beside free-text comment sections that describe function, subunit structure, tissue specificity, and post-translational modification in prose. Public archives apply controlled vocabularies at submission time. A Sequence Read Archive submission must name the organism with a taxonomy-valid scientific name and identifier. BioSample records draw on definition packs that specify required attributes for common sample classes, such as pathogen isolates needing collection date and geographic location. Custom attributes beyond the pack are free text, which is exactly where cross-study harmonization pain begins. ## What a Free-Text Annotation Is A free-text annotation is a natural-language string with no constraints on vocabulary, structure, or length. In a submitted sample it might be the description attribute of a BioSample record or a custom attribute such as notes. In a project directory it might be a README file. In a [laboratory information management system](/knowledge/bioinformatics/lims-explained-lab-information-management-systems) (LIMS) it is usually a comment field. In a paper it is the methods section. Free text has real strengths. It costs nothing to set up. It expresses anything, including things no ontology anticipated. And it is the natural home for the specific, one-off facts that make a dataset trustworthy: sample X hemolyzed on arrival and a second draw was used, run Y used a different reagent lot, plate Z sat over a weekend before extraction. No controlled vocabulary has a term for any of that. A curator who deletes such notes to make a table tidy has destroyed information. Its weaknesses mirror its strengths. Strings carry no machine-readable meaning, so nothing joins, filters, or counts correctly without human cleanup. Spelling variants, abbreviations, case differences, stray whitespace, and punctuation fragment what is conceptually one value. Ambiguity is invisible. Does liver mean the tissue, the disease, or a dietary condition in a metagenomic study? Only the surrounding context knows, and only a human reads it. A useful mental model: free text is a message from the depositor to every future user. Controlled terms are the filing system. A dataset needs both, and the design question is which field gets which treatment. ## Controlled Vocabulary vs Free Text: Side-by-Side Comparison | Criterion | Controlled vocabulary | Free text | |--|--|--| | Value space | Closed set of terms, each with a stable ID, preferred label, definition, and synonyms | Any string, any length | | Machine readability | High. IDs act as join keys across datasets and databases | Low. Strings have no semantics a machine can use | | Search and recall | High. Synonyms and hierarchy retrieve paraphrases and subtypes | Low. Literal matches only, so synonyms and variants are missed | | Aggregation | Direct. Count, group, and pivot immediately | Requires cleanup or mapping first | | Semantics | Explicit relationships (is_a, part_of) support rollup and reasoning | Implicit. Meaning lives in the reader's head | | Setup cost | High. Choose, learn, and possibly extend a vocabulary | Zero | | Cost per record | Low. Pick a term from a list | Low to write, high to clean later | | Error profile | Wrong-but-valid term, or a wrong mapping. Looks clean, propagates silently | Typos, variants, ambiguity. Looks messy, often accurate | | Expressiveness | Bounded by the term list | Unbounded | | Novel facts | Blocked until a term exists, or pushed to a notes field | Recorded immediately | | Versioning | Explicit releases, which must be recorded | None | | Validation | Automatic. Allowed values, ID resolution, logic checks | Not automatable beyond spellcheck | | FAIR fit | Directly serves the interoperability and reuse principles | Serves human findability only | | Best for | Organism, tissue, cell type, disease, phenotype, environment, assay type, units, evidence | Descriptions, caveats, provenance, protocol quirks, exploratory labels | The error profiles differ in kind, and that difference should drive the choice. Controlled fields fail by commission: a depositor picks a term that is technically valid but wrong, such as recording the sampling site as the tissue, or maps a legacy string to a plausible but incorrect term. The error looks clean and propagates silently. Free-text fields fail by fragmentation: the information is present and often accurate, but scattered across spellings and phrasings, so aggregation misses it. Clean-looking wrong terms are more dangerous than messy right ones, which is why mapping workflows end with human review. ## Controlled Vocabulary or Free Text? The Decision Criteria ![Decision path asking whether a field will be filtered, joined, validated or found by strangers, ending in controlled term or free text.](/article-images/illustrations/controlled-vocabulary-vs-free-text-genomics-metadata-vocab-or-free-text.webp) The question of controlled vocabulary vs free text for genomics metadata is really a question about the future use of each field. Five criteria settle most cases. ### When to Use a Controlled Vocabulary Use one whenever any of the following is true: 1. You will filter, group, count, or pivot on the field. Tissue, organism, disease status, treatment arm, cell type, environment, assay type, and units all qualify. 2. The field must join across datasets or studies. Joins require shared keys, and term IDs are shared keys. 3. Strangers must find the data. Public deposits compete for discovery with every other deposit, and faceted search (filtering results by structured attribute) only works on structured attributes. 4. The field feeds a pipeline or a model. Sample-selection logic written against term IDs survives synonym drift and typos. 5. Validation must be automatic. A field with an allowed-value list can be checked at submission time. Prose cannot. These five cases cover most fields that matter for reuse. If a field meets none of them, free text is usually fine. ### When Free Text Is the Right Choice Keep a field free text when it exists to carry meaning for a human reader rather than structure for a machine: - Descriptions and caveats that no term list covers. - Provenance notes about what went wrong or what was unusual. - Protocol quirks and batch context that would require dozens of bespoke fields to structure. - Exploratory domains where no vocabulary exists yet. Record rich free text now, map to terms later, and keep the mapping table. The mistake to avoid is the reverse of the usual one: stripping free text because it looks unstructured. Unstructured is not the same as worthless. ### Does a Vocabulary Already Exist? Before inventing anything, search the OBO Foundry registry, the Ontology Lookup Service at EMBL-EBI, and BioPortal. If a maintained vocabulary covers your field, adopt it. If a vocabulary covers most but not all of your values, adopt it, record the unmapped values in a free-text column plus a local codelist, and propose new terms upstream if the gap persists. If nothing fits, define a small local codelist, document the allowed values in the README, and version it like software. ### Stable Domain or Moving Target? Vocabularies work best where the domain is settled: organism, anatomy, assay type, units. They strain where discovery is fast. Novel cell types appear in the literature before the Cell Ontology has a term, and new disease entities appear before MONDO does. In fast-moving areas, pair the nearest existing term with a free-text qualifier, and revisit the mapping at each release. ## Worked Scenarios ### Scenario 1: A Multi-Site RNA-Seq Study Three sites collect tumor and adjacent-normal tissue from 200 patients. The analysis plan requires pooling by tissue, disease status, and site, and the data will be deposited in a public archive. The sample sheet splits each fact into the column that carries it: | sample_id | organism_tax_id | tissue_uberon_id | tissue_label | disease_status | site | collection_date | notes_free_text | |--|--|--|--|--|--|--|--| | TUM-001 | 9606 | UBERON:0002107 | liver | tumor | site A | 2026-01-12 | pathology report marked necrosis in segment 4, segment excluded from histology | | TUM-002 | 9606 | UBERON:0002107 | liver | adjacent_normal | site A | 2026-01-14 | second thaw, RIN 6.1 | | TUM-017 | 9606 | UBERON:0002048 | lung | tumor | site B | 2026-02-02 | | Design decisions, made explicit: - organism_tax_id uses NCBI Taxonomy, the identifier the archive validates against. - tissue uses a UBERON ID plus the label for human readability. The ID is the join key, the label is a courtesy. - disease_status is a local codelist (tumor, adjacent_normal, normal) documented in the README. A full disease ontology was overkill for a three-value field, and a local codelist is unambiguous at this scale. - collection_date uses ISO 8601 (the international YYYY-MM-DD date format) so it sorts and parses. - notes_free_text carries everything else. Nothing in it is needed for aggregation, and everything in it would be lost in a structured column. - RIN ([RNA Integrity Number](/knowledge/diagnostics/molecular/rna-integrity-assessment-rin-values-gel-electrophoresis)) is recorded in the note because it is a per-sample quality observation, not a category. At analysis time, grouping by tissue and disease status is a groupby on two columns. At deposit time, the archive validates the organism and the required fields. At reuse time, a stranger filters UBERON:0002107 plus tumor and finds exactly the right samples, including the ones whose free-text notes they would never have guessed. ### Scenario 2: Metagenomics Under MIxS and ENVO A soil microbiome study deposits shotgun data. The MIxS checklist defines the fields, and the environment fields draw their values from ENVO: env_broad_scale for the biome class, env_local_scale for the habitat class, and env_medium for the material the sample came from. A coastal dune sample gets an ENVO class for the dune biome, an ENVO class for the dune habitat, and an ENVO class for sand as the medium, plus lat_lon, geo_loc_name, and collection_date in the MIxS formats. Free text carries the rest: recent fire in the catchment, sampling after the first autumn rain. The payoff is concrete. Every ENVO-tagged sample across every metagenomic study, from any consortium, can be pooled by environment class. That cross-study rollup is impossible with depositor prose, and it is the reason the field converged on MIxS plus ENVO. ### Scenario 3: Clinical Genomics with HPO Phenotypes A diagnostic laboratory stores a pediatric case in a research database. The phenotype fields use Human Phenotype Ontology terms: HP:0001250 (seizure) rather than fits, convulsions, or seizure-like episodes. Each term carries its HPO ID, so the case joins to other cases with the same phenotype across institutions, and variant interpretation tools that reason over phenotype terms can weigh the evidence. The clinical narrative, the family history in prose, and the geneticist's caveats stay in free-text fields, because that is what those fields are for. The pattern generalizes: phenotype terms make cases computable, prose keeps them complete. ### Scenario 4: Mapping Legacy Free Text to Terms A laboratory inherits 12 years of LIMS records with a tissue column holding 340 distinct strings. The workflow: 1. Export distinct values with counts. The frequency list collapses fast, because a small number of values covers most records. 2. Match exact labels first (liver), then synonyms (hepatic tissue), using the vocabulary's own synonym lists and a lookup service. 3. Route compound values to the right column. Liver with fibrosis is a tissue value plus a disease value, not one string. 4. Review every remaining value by hand, ideally by someone who knows the domain. 5. Record each decision in a mapping table: | raw_value | term_id | preferred_label | method | curator | mapped_on | |--|--|--|--|--|--| | hepatic tissue | UBERON:0002107 | liver | exact synonym | J.D. | 2026-01-12 | | Liver | UBERON:0002107 | liver | case-normalized | J.D. | 2026-01-12 | | liver, fibrotic | UBERON:0002107 | liver | manual, disease moved to disease column | J.D. | 2026-01-15 | | unknown | (blank) | (blank) | left unmapped, flagged | J.D. | 2026-01-15 | The mapping table is now part of the dataset. It is versioned, it carries provenance, and the next harmonization starts from it instead of from scratch. ## Putting It Into Practice ### Pin the Release and Record It Ontologies change. A term's label, parents, or status can differ between releases, and a term that exists today can be obsolete next year. Pin the release you validated against: ```bash wget https://purl.obolibrary.org/obo/uberon.owl grep -m1 "versionIRI" uberon.owl ``` The version identifier (versionIRI in the file header) goes into the dataset README and into the metadata record itself. When a term is missing from a newer release, the version identifier is how you find out why. ### Structure the Sample Sheet for Validation Four rules prevent most downstream pain: 1. One fact per column. Value, unit, and term ID get separate columns. A string like 5 ng/µL cannot be sorted or unit-converted. A numeric column plus a unit column drawn from a unit vocabulary (UO or UCUM) can be both. 2. IDs in their own columns, labels as a courtesy. The ID is the key, the label is for humans. 3. ISO 8601 dates (2026-01-12), decimal points, no thousands separators. 4. Import CSVs into spreadsheet software as text. Gene symbols and long numeric strings otherwise become dates and scientific notation, a well-documented source of corrupted supplementary tables. ### Validate Before You Deposit Check that every term ID in the sheet exists in the pinned release and that the label matches. A short script with pronto, a Python library for ontologies: ```python import csv from pronto import Ontology uberon = Ontology("https://purl.obolibrary.org/obo/uberon.owl") with open("samples.csv", newline="") as handle: for row in csv.DictReader(handle): term_id = row["tissue_uberon_id"] try: term = uberon[term_id] except KeyError: print(f"FAIL {row['sample_id']}: {term_id} not in pinned UBERON") else: print(f"OK {row['sample_id']}: {term_id} = {term.name}") ``` Loading a full ontology takes a minute or more, so run this once per batch, not once per row. For the ontology files themselves, robot (a command-line toolkit for ontology development) runs standard quality-control reports: ```bash robot report --input uberon.owl --output uberon_report.tsv ``` When many people enter metadata by hand, form-based capture tools such as DataHarmonizer provide built-in validation against standards like MIxS and catch errors at the keyboard rather than at submission. ### Ask the Ontology Questions with SPARQL Ontologies in RDF (Resource Description Framework) and OWL (Web Ontology Language) are queryable with SPARQL, the RDF query language. A common question: which terms in the pinned release fall anywhere under liver in the hierarchy? Save this as liver_descendants.rq: ```sparql PREFIX rdfs: PREFIX obo: SELECT ?term ?label WHERE { ?term rdfs:subClassOf* obo:UBERON_0002107 . ?term rdfs:label ?label . } ``` Then run it with robot: ```bash robot query --input uberon.owl --query liver_descendants.rq --format csv --output liver_descendants.csv ``` The rdfs:subClassOf* path follows the hierarchy to any depth, which is the rollup behavior (rolling child values up to a parent) that flat lists cannot provide. Reasoners such as ELK and HermiT go further and check that a term placement is logically consistent with the rest of the ontology. ### Find Terms with a Lookup Service Two services answer most where-is-the-term-for-X questions: the Ontology Lookup Service at EMBL-EBI and BioPortal at Stanford. Both search across hundreds of ontologies by label and synonym and return the ID, definition, and hierarchy position. For programmatic access, the PURL convention is stable: purl.obolibrary.org/obo/UBERON_0002107 resolves a term, and purl.obolibrary.org/obo/uberon.owl resolves the ontology. ### Run the Hybrid Pattern The default design for most projects: - Controlled columns for every field that will be filtered, counted, joined, or validated. - One free-text notes column for everything else, with a stated convention (one fact per line, dated). - A mapping table for any legacy values, with method, curator, and date. - A README that lists every vocabulary and release used. This mirrors what mature databases already do. UniProt pairs controlled keywords with prose comment sections. Public archives pair required structured fields with depositor descriptions. That pattern is the design, not a compromise. ## Common Mistakes and Limitations 1. Storing the label but not the ID. Labels change and collide across vocabularies. Store the ID, and store the release. 2. Storing the ID but not the release. The same ID can carry a different label or a different parent set in a different release. Pin versions in the README and in the metadata. 3. Deleting free text after mapping. The term records what the sample was. The note records what went wrong. Keep both. 4. Assuming the archive will fix your strings. Archives validate required fields and normalize some formats. They do not reconcile cancer with carcinoma in your custom attributes. 5. Packing value and unit into one field. A string like 5 ng/µL cannot be sorted or converted. Use a numeric column and a unit column. 6. Letting spreadsheet software edit term IDs and gene symbols. Import as text, every time. 7. Building an ontology where a codelist would do. A five-value status field needs five allowed strings, not OWL. 8. Building a flat list where rollup is needed. If two values must both count as a third, the list needs hierarchy or an explicit mapping. 9. Matching legacy strings by exact string equality only. Synonyms carry most of the signal. Match on labels and synonyms first, then review the remainder by hand. 10. Recording mappings without provenance. Who mapped what, to which term, by which method, on what date. Without that, the next person redoes the work or trusts it blindly. 11. Adopting obsolete terms. Check the obsolescence status before adopting a term, and check it again at every release bump. 12. Treating cross-vocabulary matches as identity. The SKOS (Simple Knowledge Organization System) predicates exactMatch and closeMatch exist because most cross-vocabulary agreement is approximate. Say which one you mean. Limitations to accept rather than fight. Vocabularies lag discovery, so a novel cell type or disease entity may have no term yet. Curators disagree, so two trained people can choose different valid terms for the same sample. Cross-vocabulary mappings are approximate, and legacy harmonization is judgment work. A specific dataset needs someone who knows both the domain and the vocabulary to review the result. None of these limitations argues for free text. They argue for keeping a free-text channel alongside the controlled fields. ## Frequently Asked Questions ### What is the difference between controlled vocabulary and free text in genomics metadata? A controlled vocabulary limits a metadata field to approved terms with stable identifiers, while free text accepts any string the depositor writes. Controlled fields can be filtered, counted, and joined across studies. Free-text fields carry nuance and context for human readers. ### When should I use a controlled vocabulary instead of free text? Use one whenever a field will be filtered, grouped, counted, joined, or validated, or when strangers must find and reuse the data. Organism, tissue, cell type, disease status, phenotype, environment, assay type, and units are the classic cases. ### Do I need a full ontology, or is a simple list of allowed values enough? Start with the simplest structure that answers your questions. A flat codelist handles status fields. Add a thesaurus when synonyms hurt recall. Add an ontology when you need hierarchy-aware rollup or automated reasoning. ### How do I convert existing free-text metadata into controlled terms? Build a mapping table with one row per distinct raw value, match on exact labels and synonyms first, review every remaining value by hand, and record the term ID, method, curator, and date for each decision. ### Which vocabularies cover common fields like organism, tissue, and disease? NCBI Taxonomy for organisms, UBERON for anatomy, the Cell Ontology for cell types, MONDO or EFO for disease, HPO for phenotypes, ENVO for environments, and the Gene Ontology for molecular processes and functions. ### Can I keep free-text fields alongside controlled fields? Yes, and you usually should. UniProt pairs controlled keywords with free-text comment sections, and public archives pair required structured fields with depositor descriptions. Use controlled columns for anything you will compute on, and a notes column for everything else.