BIH-CEI · aslgraefe · Mar 24, 2026 · Mar 24, 2026 · Mar 24, 2026 · Mar 24, 2026
diff --git a/.gitignore b/.gitignore
@@ -61,6 +61,11 @@ local_settings.py
 db.sqlite3
 db.sqlite3-journal
 
+# macOS metadata
+.DS_Store
+**/.DS_Store
+res/.DS_Store
+
 # Flask stuff:
 instance/
 .webassets-cache

diff --git a/README.md b/README.md
@@ -1,15 +1,15 @@
 # ontology-based rare disease common data model
 
-Welcome to the repo of the ontology-based rare disease common data model (RD-CDM) harmonising international registry use, HL7® FHIR®, and the GA4GH Phenopacket Schema.
+Welcome to the repo of the ontology-based rare disease common data model (RD-CDM)
+harmonising international registry use, HL7® FHIR®, and the GA4GH Phenopacket Schema.
 
-<!-- Badges -->
 [![CI](https://github.com/BIH-CEI/rd-cdm/actions/workflows/ci.yml/badge.svg)](https://github.com/BIH-CEI/rd-cdm/actions/workflows/ci.yml)
 [![Documentation Status](https://readthedocs.org/projects/rd-cdm/badge/?version=latest)](https://rd-cdm.readthedocs.io/en/latest/?badge=latest)
 [![DOI](https://zenodo.org/badge/863993011.svg)](https://doi.org/10.5281/zenodo.13891625)
 ![Python Versions](https://img.shields.io/badge/python-3.10%20|%203.11%20|%203.12-blue)
 [![PyPI](https://img.shields.io/pypi/v/rd-cdm.svg)](https://pypi.org/project/rd-cdm/)
 [![Downloads](https://img.shields.io/pypi/dm/rd-cdm.svg?label=downloads)](https://pypi.org/project/rd-cdm/)
-[![LinkML](https://img.shields.io/badge/LinkML-1.8.0+-green.svg)](https://linkml.io/)
+[![LinkML](https://img.shields.io/badge/LinkML-1.9.0+-green.svg)](https://linkml.io/)
 
 **Latest docs:** https://rd-cdm.readthedocs.io/en/latest/
 
@@ -29,7 +29,6 @@ https://www.nature.com/articles/s41597-025-04558-z
   - [Quick start (pip)](#quick-start-pip)
   - [Development install](#development-install)
 - [CLI tools](#cli-tools)
-- [Versioning & File Layout](#versioning--file-layout)
 - [Validating with BioPortal](#validating-with-bioportal)
 - [Contributing & Contact](#contributing--contact)
 - [Resources](#resources)
@@ -41,7 +40,11 @@ https://www.nature.com/articles/s41597-025-04558-z
 
 ## Project Description
 
-The ontology-based RD-CDM harmonizes rare disease data capture across registries. It integrates ERDRI-CDS, HL7 FHIR, and GA4GH Phenopacket Schema to support interoperable data for research and care. RD-CDM v2.0.x comprises 78 data elements covering formal criteria, personal information, patient status, disease, genetic findings, phenotypic findings, and family history.
+The ontology-based RD-CDM harmonizes rare disease data capture across registries.
+It integrates ERDRI-CDS, HL7 FHIR, and GA4GH Phenopacket Schema to support
+interoperable data for research and care. RD-CDM v2.0.x comprises 78 data elements
+covering formal criteria, personal information, patient status, disease, genetic
+findings, phenotypic findings, and family history.
 
 ---
 
@@ -50,24 +53,28 @@ The ontology-based RD-CDM harmonizes rare disease data capture across registries
 Installing `rd-cdm` from PyPI provides:
 
 - **Schema**
-  - `src/rd_cdm/schema/rd_cdm.yaml`
-
-- **Versioned instances (data packs)**
-  - `src/rd_cdm/instances/v2_0_1/*.yaml` (e.g., `code_systems.yaml`, `data_elements.yaml`, `value_sets.yaml`)
-  - merged file: `src/rd_cdm/instances/v2_0_1/rd_cdm_v2_0_1.yaml`
-  - exports (if present or generated locally):
-    - `src/rd_cdm/instances/v2_0_1/jsons/*.json`
-    - `src/rd_cdm/instances/v2_0_1/csvs/*.csv`
-
-- **Generated Python & Pydantic classes (LinkML)**
-  - `src/rd_cdm/python_classes/rd_cdm.py` (LinkML runtime dataclasses)
-  - `src/rd_cdm/python_classes/rd_cdm_pydantic.py` (generated from the schema via LinkML’s Pydantic generator)
-
-- **Utilities / CLI entry points**
-  - `rdcdm-merge` – merge instance parts into `rd_cdm_vX_Y_Z.yaml`
-  - `rdcdm-json` – per-file JSON export + combined `rd_cdm_vX_Y_Z.json`
-  - `rdcdm-csv` – per-file CSV export + combined `rd_cdm_vX_Y_Z.csv`
-  - `rdcdm-validate` – validate ontology codes via BioPortal
+  - `src/rd_cdm/schema/rd_cdm.yaml` — LinkML schema defining the data model
+    structure. The `version` and `date` fields here are the single source of
+    truth for the data model version.
+
+- **Instances**
+  - `src/rd_cdm/instances/code_systems.yaml`
+  - `src/rd_cdm/instances/data_elements.yaml`
+  - `src/rd_cdm/instances/value_sets.yaml`
+  - `src/rd_cdm/instances/rd_cdm.yaml` — merged instance, version-stamped
+    with `rd_cdm_version` and `rd_cdm_date` at the top
+  - `src/rd_cdm/instances/jsons/rd_cdm.json`
+  - `src/rd_cdm/instances/csvs/rd_cdm.csv`
+
+- **Generated Python classes (LinkML)**
+  - `src/rd_cdm/python_classes/rd_cdm.py` — LinkML runtime dataclasses
+  - `src/rd_cdm/python_classes/rd_cdm_pydantic.py` — Pydantic v2 models
+
+- **CLI entry points**
+  - `rd-cdm-merge` — merge instance parts into `rd_cdm.yaml`
+  - `rd-cdm-json` — export to `jsons/rd_cdm.json`
+  - `rd-cdm-csv` — export to `csvs/rd_cdm.csv`
+  - `rd-cdm-validate` — validate ontology codes via BioPortal
 
 ---
 
@@ -76,154 +83,148 @@ Installing `rd-cdm` from PyPI provides:
 - **Interoperability**: Aligns with HL7 FHIR v4.0.1 and GA4GH Phenopacket v2.0
 - **Ontology-driven**: Uses SNOMED CT, LOINC, NCIT, MONDO, OMIM, HPO, and more
 - **Modular**: Clear separation of schema, instances, and exports
-- **Versioned data**: Instances shipped and resolved per version (e.g., `v2_0_1`)
-- **Tooling**: Merge, export, and validation utilities with simple CLIs
-- **(Optional) Pydantic models**: Strict runtime validation generated from LinkML
+- **Self-describing exports**: Every YAML, JSON, and CSV file carries
+  `rd_cdm_version` and `rd_cdm_date` so outputs are unambiguous without
+  needing to know which package version was installed
+- **Tooling**: Merge, export, and validation utilities via simple CLI commands
+- **Pydantic models**: Runtime validation generated from the LinkML schema
 
 ---
 
-### Installation
+## Installation
 
 From PyPI:
-
 ```bash
 pip install rd-cdm
 ```
 
-Optional extras for testing/docs:
-
+Optional extras:
 ```bash
-pip install rd-cdm[test]     # pytest, etc.
-# or
-pip install rd-cdm[docs]
+pip install rd-cdm[test]   # pytest, requests-mock
+pip install rd-cdm[docs]   # sphinx, sphinx-rtd-theme, sphinx-copybutton
+pip install rd-cdm[dev]    # linkml (for regenerating Python classes)
 ```
 
 ### Development install
-
 ```bash
 git clone https://github.com/BIH-CEI/rd-cdm.git
 cd rd-cdm
-# (Recommended) create a venv
 python -m venv .venv && source .venv/bin/activate
 pip install -U pip
-pip install -e .[test]
+pip install -e ".[test,dev]"
 pytest -q
 ```
 
-> We use a **src/** layout. If you run tools directly, ensure `PYTHONPATH=src` or use the installed CLI entry points shown below.
+> We use a **src/** layout. Use the installed CLI entry points shown below
+> rather than running scripts directly.
 
 ---
 
 ## CLI tools
 
-After installation you should have these commands:
-
+After installation the following commands are available:
 ```bash
-# Merge the versioned parts into rd_cdm_vX_Y_Z.yaml (auto-resolves latest if not given)
-rdcdm-merge                  # or: rdcdm-merge --version 2.0.1
+# Merge instance parts → src/rd_cdm/instances/rd_cdm.yaml
+rd-cdm-merge
 
-# Export JSON (per-file .json + combined rd_cdm_vX_Y_Z.json)
-rdcdm-json                   # or: rdcdm-json -v 2.0.1
+# Export merged YAML → src/rd_cdm/instances/jsons/rd_cdm.json
+rd-cdm-json
 
-# Export CSV (per-file .csv + combined rd_cdm_vX_Y_Z.csv)
-rdcdm-csv                    # or: rdcdm-csv -v 2.0.1
+# Export merged YAML → src/rd_cdm/instances/csvs/rd_cdm.csv
+rd-cdm-csv
 
-# Validate merged instance file against ontologies via BioPortal
-rdcdm-validate               # or: rdcdm-validate -v 2.0.1 (Note: set up BioPortal API key for this)
+# Validate all ontology codes against BioPortal
+rd-cdm-validate
 ```
 
-### BioPoratal API Key Setup for Validation
-The ``rdcdm-validate`` command uses the BioPortal API
-to check ontology term validity. This requires an API key to be set as an environment variable.
+The recommended order when updating the model is:
+```bash
+rd-cdm-merge && rd-cdm-json && rd-cdm-csv && rd-cdm-validate
+```
+
+---
+
+## Validating with BioPortal
 
-#### Get an API key:
+`rd-cdm-validate` checks all ontology codes in the merged instance against
+BioPortal and reports version drift and missing or deprecated terms.
 
-Sign up (or log in) at https://bioportal.bioontology.org/accounts/new
+### Get an API key
 
-- Go to your account settings and copy your API Key.
-- Set the API key in your environment
+Sign up at https://bioportal.bioontology.org/accounts/new, go to your account
+settings, and copy your API key.
 
-#### macOS / Linux (bash/zsh): 
+### Set the environment variable
 
+macOS / Linux:
 ```bash
 export BIOPORTAL_API_KEY="your-key-here"
 ```
 
-#### Windoes (PowerShell):
-```bash
+Windows (PowerShell):
+```powershell
 setx BIOPORTAL_API_KEY "your-key-here"
 ```
 
 ---
 
 ## Contributing and Contact
 
-The RD-CDM is a community-driven effort and we invite open and international
-collaboration. Please feel free to create issues, discuss features, 
-or submit pull requests to help enhance this project. For larger contributions, 
-consider reaching out to discuss collaboration opportunities. 
-Please find more information on how to contact us and contribute 
-in the [`Contribution` section of our documentation](https://rd-cdm.readthedocs.io/en/latest/contributing.html).
+The RD-CDM is a community-driven effort. Please feel free to open issues,
+discuss features, or submit pull requests. For larger contributions consider
+reaching out directly.
 
-## RareLink 
+See the [`Contributing` section of our documentation](https://rd-cdm.readthedocs.io/en/latest/contributing.html)
+for full guidelines.
 
-RareLink is a novel rare disease framework in REDCap linking international 
-registries, FHIR, and Phenopackets based on the RD-CDM. It is designed to 
-support the collection of harmonized data for rare disease research 
-across any REDCap project worldwide and allows for the preconfigured export of 
-the RD-CDM data in FHIR and Phenopackets formats.
+## RareLink
 
-For more information on RareLink, please see the: 
+RareLink is a REDCap-based framework for rare disease research linking
+international registries to FHIR and Phenopackets, built on the RD-CDM.
 
 - [RareLink Documentation](https://rarelink.readthedocs.io/en/latest/index.html)
 - [RareLink GitHub](https://github.com/BIH-CEI/rarelink)
 
-## Resources 
+---
+
+## Resources
 
 ### Ontologies
+
 - Human Phenotype Ontology [🔗](http://www.human-phenotype-ontology.org)
 - Monarch Initiative Disease Ontology [🔗](https://mondo.monarchinitiative.org/)
 - Online Mendelian Inheritance in Man [🔗](https://www.omim.org/)
 - Orphanet Rare Disease Ontology [🔗](https://www.orpha.net/)
 - SNOMED CT [🔗](https://www.snomed.org/snomed-ct)
-- ICD 11 [🔗](https://icd.who.int/en)
-- ICD10CM [🔗](https://www.cdc.gov/nchs/icd/icd10cm.htm)
-- National Center for Biotechnology Information Taxonomy [🔗](https://www.ncbi.nlm.nih.gov/taxonomy)
-- Logical Observation Identifiers Names and Codes [🔗](https://loinc.org/)
-- HUGO Gene Nomenclature Committee [🔗](https://www.genenames.org/)
-- Gene Ontology [🔗](https://geneontology.org/)
+- ICD-11 [🔗](https://icd.who.int/en)
+- ICD-10-CM [🔗](https://www.cdc.gov/nchs/icd/icd10cm.htm)
+- NCBI Taxonomy [🔗](https://www.ncbi.nlm.nih.gov/taxonomy)
+- LOINC [🔗](https://loinc.org/)
+- HGNC [🔗](https://www.genenames.org/)
 - NCI Thesaurus OBO Edition [🔗](https://obofoundry.org/ontology/ncit.html)
 
-For the versions used in a specific RD-CDM version, please see the 
-[resources in our documentation](https://rd-cdm.readthedocs.io/en/latest/resources/resources_file.html).
+For the ontology versions used in each RD-CDM release, see the
+[resources page in our documentation](https://rd-cdm.readthedocs.io/en/latest/resources/resources_file.html).
 
-### Submodules
-- [RareLink](https://github.com/BIH-CEI/RareLink)
+---
 
 ## License
 
-This project is licensed under the terms of the [MIT License](https://github.com/BIH-CEI/rd-cdm/blob/develop/LICENSE)
+[MIT License](https://github.com/BIH-CEI/rd-cdm/blob/develop/LICENSE)
 
 ## Citing
 
-If you use the model for your research, do not hesitate to reach out and 
-please cite our article: 
-
-> Graefe, A.S.L., Hübner, M.R., Rehburg, F. et al. An ontology-based rare disease common data model harmonising international registries, FHIR, and Phenopackets. Sci Data 12, 234 (2025). https://doi.org/10.1038/s41597-025-04558-z
+> Graefe, A.S.L., Hübner, M.R., Rehburg, F. et al. An ontology-based rare
+> disease common data model harmonising international registries, FHIR, and
+> Phenopackets. *Sci Data* 12, 234 (2025).
+> https://doi.org/10.1038/s41597-025-04558-z
 
 ## Acknowledgements
 
-We would like to extend our thanks to all the authors involved in the 
-development of this RD-CDM model.
-
----
-
-- Authors:
-  - [Adam SL Graefe](https://github.com/aslgraefe)
-  - [Filip Rehburg](https://github.com/frehburg) 
-  - [Samer Alkarkoukly](https://github.com/alkarkoukly)
-  - [Daniel Danis](https://github.com/ielis)
-  - [Peter N. Robinson](https://github.com/pnrobinson)
-  - Oya Beyan
-  - Sylvia Thun
-
+- [Adam SL Graefe](https://github.com/aslgraefe)
+- [Filip Rehburg](https://github.com/frehburg)
+- [Samer Alkarkoukly](https://github.com/alkarkoukly)
+- [Daniel Danis](https://github.com/ielis)
+- [Peter N. Robinson](https://github.com/pnrobinson)
+- Oya Beyan
+- Sylvia Thun