ADR-0002: Host Ontologies in a Separate Repository
ADR-0002: Host Ontologies in a Separate Repository
Section titled “ADR-0002: Host Ontologies in a Separate Repository”Status
Section titled “Status”Accepted
Context
Section titled “Context”Background and Problem Statement
Section titled “Background and Problem Statement”The mif-docs plugin validates the namespaces of the documents it produces
against an MIF ontology — a knowledge-discovery layer that names the entity
types, namespaces, and relationship vocabulary the genres draw on. That same
ontology is consumed beyond this plugin: it is an org-shared asset used across
modeled-information-format repos. We had to decide where the ontology lives
and how the plugin obtains it, because the obvious shortcut — committing a copy
of the ontology into this repo — makes the plugin a second, independently
edited home for a shared artifact.
Current Limitations
Section titled “Current Limitations”- Shared asset, single consumer view: the ontology serves multiple repos, but committing it here would frame it as this plugin’s private file.
- Drift risk: two committed copies of the same ontology drift the moment either side is edited without the other.
- No single authority: with a local copy, there is no one place that is unambiguously the source of truth for the ontology.
Decision Drivers
Section titled “Decision Drivers”Primary Decision Drivers
Section titled “Primary Decision Drivers”The following factors are weighted most heavily in this decision:
- Org-shared source of truth: the ontology shall have exactly one authoritative home that every consumer resolves from.
- No duplication-driven drift: the plugin shall not carry a committed copy of the ontology that can diverge from the authoritative one.
- Reproducible releases: a released artifact shall contain a fixed ontology so a published plugin validates identically offline.
Secondary Decision Drivers
Section titled “Secondary Decision Drivers”The following factors influenced the decision but were not individually decisive:
- Fast local iteration: a developer with the sibling repo checked out should validate against the live ontology without a publish step.
- CI cost: routine push CI should not depend on fetching an external repo on every run.
Considered Options
Section titled “Considered Options”Option 1: Commit a copy of the ontology in this repo
Section titled “Option 1: Commit a copy of the ontology in this repo”Description: Vendor the ontology as a committed file in mif-docs and edit
it here alongside the genres.
Technical Characteristics:
- The ontology is a tracked file in this repository.
- Validation reads the local committed copy.
Advantages:
- No external dependency to resolve at dev or release.
- Validation works with a single checkout.
Disadvantages:
- Creates a second editable home for an org-shared artifact.
- The committed copy drifts from the authoritative ontology over time.
Disqualifying Factor: a committed copy is a second source of truth, which fails the org-shared-source-of-truth and no-drift drivers directly.
Risk Assessment:
- Technical Risk: Low to obtain, High to keep correct. Drift is the failure.
- Schedule Risk: Medium. Manual reconciliation between copies.
- Ecosystem Risk: High. Consumers see divergent ontologies.
Option 2: Host in a separate repo; hydrate at dev, vendor at release
Section titled “Option 2: Host in a separate repo; hydrate at dev, vendor at release”Description: Keep the ontology in the sibling modeled-information-format/ontologies
repo. The plugin hydrates it from a raw URL at dev time and vendors a fixed copy
into the release artifact.
Technical Characteristics:
- The authoritative ontology lives in the
ontologiesrepo. hydrate-ontologyfetches it;validate-ontologyis the gate; the release bundles a vendored copy.
Advantages:
- One authoritative ontology; no committed duplicate to drift.
- Releases stay reproducible because the vendored copy is fixed at build time.
Disadvantages:
validate-ontologyneeds either a sibling checkout (dev) or the vendored copy (release); it is intentionally not run in routine push CI.
Risk Assessment:
- Technical Risk: Low. Hydration and vendoring are scripted.
- Schedule Risk: Low. No manual copy reconciliation.
- Ecosystem Risk: Low. A single authoritative ontology for all consumers.
Decision
Section titled “Decision”We host the ontology in the separate modeled-information-format/ontologies
repository. The plugin does not commit the ontology here. Instead:
- At dev time,
hydrate-ontologyresolves the ontology from the sibling repo’s raw URL, andvalidate-ontologychecks it against a sibling checkout. - At release time, the ontology is vendored into the release artifact so the published plugin validates against a fixed copy.
validate-ontology therefore runs at dev (sibling checkout) and at release
(vendored copy), and not in routine push CI, because push CI has neither the
sibling checkout nor a reason to fetch the external repo on every run.
Consequences
Section titled “Consequences”Positive
Section titled “Positive”- Single source of truth: one authoritative ontology serves every consumer, satisfying the no-drift driver by construction.
- Reproducible releases: the vendored copy fixes the ontology at build time, so a published plugin validates identically offline.
Negative
Section titled “Negative”- No push-CI ontology gate:
validate-ontologyis not in push CI, so an ontology mismatch is caught at dev or release, not on every push; mitigated by running it as the release gate before any artifact is built. - Dev setup step: validating locally needs the sibling repo checked out;
mitigated because
hydrate-ontologyautomates the fetch.
Neutral
Section titled “Neutral”- Two obtain paths: dev hydrates, release vendors — one ontology reached two ways, a deliberate split rather than an inconsistency.
Decision Outcome
Section titled “Decision Outcome”The decision achieves its primary objective — one authoritative ontology with no
committed duplicate — measured by: no ontology copy tracked in this repo, and
validate-ontology passing against the sibling checkout at dev and the vendored
copy at release.
Mitigations:
hydrate-ontologyautomates resolving the sibling ontology at dev.validate-ontologyis wired as the release gate, covering the absence of a push-CI ontology check.
Related Decisions
Section titled “Related Decisions”- ADR-0001: Align the adr Genre Fully to Structured MADR - another reuse of an org-maintained, separately validated source.
- ADR-0003: Attested-Delivery Release Pattern - the release that vendors the ontology into the verified artifact.
- modeled-information-format/ontologies - the authoritative home of the ontology this plugin hydrates and vendors.
More Information
Section titled “More Information”- Date: 2026-06-30
- Source: mif-docs v0.1.0 ontology-sourcing review
- Related ADRs: ADR-0001, ADR-0003
2026-06-30
Section titled “2026-06-30”Status: Compliant
Findings:
| Finding | Files | Lines | Assessment |
|---|---|---|---|
| No ontology copy committed; hydrate plus vendor | - | - | accepted |
Summary: Decision accepted after the v0.1.0 ontology-sourcing review; the ontology stays in the sibling repo, hydrated at dev and vendored at release.
Action Required: Keep validate-ontology wired as the release gate and out
of routine push CI.