ClarID: a human-readable and compact identifier specification for biomedical metadata integration

BACKGROUND: In biomedical research, subjects and biospecimens are commonly tracked using simple IDs or UUIDs, which guarantee uniqueness but convey no embedded semantic information. Contextual metadata (such as tissue type, diagnosis, or assay) is often stored separately, making integration, cohort selection, and downstream analysis cumbersome. While structured barcoding systems exist in large consortia (e.g., TCGA, GTEx) or domain-specific contexts (e.g., SPREC, GOLD), no unified, extensible framework currently spans both subjects and biosamples in a human- and machine-readable way. METHODS: We developed ClarID, a domain-agnostic specification that supports two identifier formats: (i) a human-readable form (e.g., ‘CNAG_Test-HomSap-00001-LIV-TUM-RNA-C22.0-TRT-P1W’ that encodes key metadata such as project, species, subject_id, tissue, assay, disease, timepoint and duration (relative to that event); and (ii) a compact version named ‘stub’ (e.g., ‘CT01001LTR0N401T1W’) optimized for filenames, pipelines, and labeling. ClarID is supported by an open-source reference implementation, ClarID-Tools, a command-line tool that processes tabular metadata files (CSV/TSV) and uses a YAML-based codebook to generate, decode, and validate identifiers, as well as to create and read QR codes. The tool supports bulk and single-sample processing and allows easy integration with institutional workflows. RESULTS: To demonstrate ClarID’s utility, we applied it to datasets from the Genomic Data Commons (GDC), generating interpretable identifiers for more than 113,000 clinical records (subjects) and 4,255 biospecimen records. All materials, including pre-processing scripts, input and encoded data, are publicly available and fully reproducible via the accompanying GitHub repository and Google Colab. CONCLUSIONS: ClarID is designed to complement, not replace, persistent identifiers such as UUIDs, by providing a human-readable layer that enhances interpretability and facilitates metadata curation. It enhances traceability, facilitates downstream analysis, and remains adaptable to project-specific needs through a configurable codebook. The accompanying ClarID-Tools software is freely available, together with full documentation and reproducible pipelines, at https://github.com/CNAG-Biomedical-Informatics/clarid-tools .