ADR-0002: Identifiers, IRIs and ontology-valued slots¶

Status: Proposed
Date: 2026-09-15

Context¶

Integration only works if the same thing has the same identifier everywhere. The blueprint also has to produce RDF that SPARQL can traverse, including ontology hierarchies. Early prototyping showed two technical pitfalls:

LinkML serialises enum values as string literals in RDF, so they can't be linked to ontology hierarchies.
Class-typed ranges make the generated SHACL require every referenced ontology term to be typed in the data, which contributors would find tedious.

Decision¶

Reuse ontology identifiers for biological, chemical, environmental and disease entities. Mint micokg:<type>/<local-id> only for instance data (samples, observations, associations, studies, hosts, gene records).
Namespace: https://w3id.org/micokg/. The w3id redirect is to be registered once the GitHub organisation is agreed.
Ontology-valued slots use range: uriorcurie plus a prefix pattern, and optionally bindings to a dynamic enum for branch checks. They are serialised as IRIs, and a test enforces this.
Expand prefixes to OBO PURLs (http://purl.obolibrary.org/obo/ENVO_), matching the ontologies' own IRIs. The canonical_prefixes lint rule (identifiers.org) is disabled.
Preferred prefixes per entity:

Entity	Prefixes
Taxon	NCBITaxon; GTDB accepted for MAG-derived taxa
Disease	MONDO preferred; DOID, NCIT and EFO accepted and bridged by SSSOM (to be decided: the proposal names DO)
Metabolite	CHEBI (HMDB accepted)
Habitat / environment	ENVO
Anatomy	UBERON
Function	GO; KEGG orthology and EC as gene families
AMR	ARO
Food	FOODON (CHEBI for defined compounds)
Evidence	ECO

Consequences¶

Pro: Data from different resources joins on identifiers, not labels.
Pro: Queries can use rdfs:subClassOf* over ontology slims or full ontologies.
Con: YAML patterns check the prefix only, not whether the term exists or sits in the right branch. make terms runs linkml-term-validator for that.
Con: SHACL sh:pattern constraints written for CURIEs don't apply to expanded IRIs, so they are dropped when validating RDF (see tests/test_rdf_shacl.py).