# ADR-005 — NCIt as the anchor ontology

Status: accepted (2026-09-08)

## Context

CancerIndex must cover every recognised malignant disease entity, not a list of common cancers, and
must reconcile labels from registries (ICD-10/ICD-O site groups), clinical sequencing (OncoTree),
curated evidence (CIViC uses DOID), trials (free text), literature (MeSH) and cohorts (GDC
project/disease types). No single vocabulary covers all of these; a canonical spine is needed to
which the others map.

Candidates: NCI Thesaurus (NCIt), Disease Ontology (DOID), MONDO, OncoTree, ICD-O-3, MeSH.

## Decision

The NCI Thesaurus is the anchor: canonical cancer entities are created from NCIt neoplasm concepts
(roots in `packages/ontology/src/top-level.ts`: Neoplasm C3262, Malignant Neoplasm C9305, by-site
C3263, by-morphology C4741, hematopoietic/lymphoid C27134, childhood malignant neoplasm C4005…),
`cancers.primary_ncit_code` is unique, and the `ncit` hierarchy is the default tree for descendant
aggregation. Reasons: NCIt is maintained monthly by the NCI, is the terminology of ClinicalTrials.gov
condition coding and of CTRP/caDSR, carries rich synonyms with their source, includes
cross-references to UMLS/MeSH/ICD-O/DOID (via EVS), is public domain, and its EVS REST API is open.

Other vocabularies are kept as **additional dimensions and codes**, never discarded:

- OncoTree provides the tissue-based tree (`hierarchy_type = oncotree`) and `cancer_codes.system =
  oncotree`, mapped to NCIt through OncoTree's own NCI cross-references (`EXACT_IDENTIFIER`).
- DOID (CIViC), MeSH (PubMed), ICD-10 / ICD-O (registries), UMLS CUIs, MONDO, GDC project codes are
  stored in `cancer_codes` with a `match_type`.
- Registry site groups used for burden rankings are a curated overlay (`TOP_LEVEL_CANCERS`, 36 ICD-10
  groups anchored to NCIt concepts), not taxonomy nodes.

Qualified disease states in NCIt (stage, recurrent, metastatic, laterality, treatment history) are
recognised by deterministic rules (`packages/ontology/src/qualifiers.ts`) and kept as source records
attached to their base disease rather than as canonical entities (spec §217-218).

## Consequences

- One concept, one row, one `CI-CAN` id; aliases from every vocabulary hang off it, which is what
  makes deterministic reconciliation (`CancerResolver`) possible.
- NCIt's own updates (retired concepts, merges) flow into `status = deprecated|merged` and
  `entity_merges`, with `classification_version` recorded on entities.
- Where NCIt and another ontology disagree on granularity, the mapping is recorded as
  `CURATED_BROADER` / `CURATED_NARROWER` rather than forced to exact, and the difference is visible
  in the API.
- The choice can be revisited if MONDO's harmonised cross-walks prove more complete for rare
  cancers; the model already stores MONDO codes, so the change would be a re-anchoring migration,
  not a schema change.