Idea: house the ontologies in a dedicated modeled-information-format/ontologies repository

[zircote]

ADR Precursor — Structured MADR seed. Recast of this ideation seed into Structured MADR shape. Deliberately undecided (status: proposed, Decision: PENDING). Feedback and alternatives are welcome. When it matures, it drops into adr/ADR-NNN-...md (next free number) with the frontmatter below.

title: "House the Ontologies in a Dedicated modeled-information-format/ontologies Repository"
description: "Whether to move ontology definitions out of the MIF spec repo into the dedicated ontologies repo, keeping the ontology schema + JSON-LD context in MIF as the format contract."
type: adr
category: infrastructure
tags:
  - ontologies
  - repository-structure
  - release-cadence
  - distribution
  - governance
status: proposed
created: 2026-06-28
updated: 2026-06-28
author: MIF Maintainers
project: MIF
technologies:
  - yaml
  - json-ld
  - github-actions
audience:
  - developers
  - architects
related:
  - ADR-004-three-tier-trait-inheritance.md
  - ADR-005-underscore-namespace-prefix.md
  - ADR-007-github-raw-urls-for-schema-ids.md

ADR Precursor: House the Ontologies in a Dedicated modeled-information-format/ontologies Repository

Status

Proposed — precursor / undecided. No option is selected. Seed for design input.

Context

Background and Problem Statement

Proposal: move the ontology definitions out of the MIF (Modeled Information Format) specification repository and into the dedicated modeled-information-format/ontologies repository. The repository already exists as an empty placeholder, so this seed is about what moves, what stays, and how consumers reference the result.

What would move

• The base and shared definitions: mif-base.ontology.yaml and shared-traits.ontology.yaml.
• The domain and example ontologies: regenerative-agriculture, k12-educational-publishing, biology-research-lab, software-engineering, backstage and csi-5w1h.
• The ontology validators and the ontology-manager tooling, or a shared copy of them.

What stays in MIF

The ontology schema (schema/ontology/ontology.schema.json) and its JSON-LD context are normative. The lean is to keep them in the specification repository as part of the format contract, and have the ontologies repository validate against the published schema on mif-spec.dev. The alternative is to move the schema as well; that is not favored, because it splits the format contract across two repositories.

Decision Drivers (why separate them)

1. Independent release cadence. Ontologies evolve faster than the normative format and on a different schedule. A dedicated repository lets domain ontologies version and ship without waiting on a specification release.
2. A clearer contribution surface. Domain experts can propose and refine ontologies without navigating the specification site and its full gate suite.
3. A smaller, focused specification repository. MIF keeps the normative format, the JSON Schemas and the tooling. A consumer who wants only ontologies does not need to clone the specification site.
4. Cleaner distribution. The dedicated repository can publish versioned ontology bundles that downstream consumers pin to.

Considered Options

Option 1: Move all ontologies (incl. mif-base + shared-traits); keep the ontology schema + context in MIF; publish versioned bundles — author's current preference

Advantages: cleanest separation of cadence and contribution surface; one home for every ontology; format contract (schema + context) stays singular in MIF; downstream pins to versioned bundles.
Disadvantages: the foundational mif-base now resolves from a different repo than the schema; examples referencing it must resolve the new location; cross-repo validation/resolution wiring required.
Risk: Technical: Medium. Schedule: Medium. Ecosystem: Low.

Option 2: Move only the domain + example ontologies; keep mif-base + shared-traits in MIF

Advantages: foundational definitions stay next to the schema/contract; lower resolution risk for the base; domain content still gets its own cadence.
Disadvantages: ontologies split across two repos (base in MIF, domain elsewhere) — a fuzzier boundary; the "smaller spec repo" driver only partially met.
Risk: Technical: Low–Medium. Schedule: Low. Ecosystem: Low.

Option 3: Move everything, including the ontology schema — disfavored

Advantages: the ontologies repo is fully self-contained.
Disadvantages: splits the format contract across two repositories — the schema is normative and belongs with the format. Author explicitly does not favor this.
Risk: Technical: Medium. Schedule: Medium. Ecosystem: Medium.

Option 4 (exculpatory — do nothing): Keep all ontologies in MIF

Advantages: single repository, single gate suite, one CI trust root; no cross-repo validation or resolution complexity; stable id values and namespace IRIs already do not change, so there is no correctness pressure forcing a move; mif-base stays adjacent to the schema it instantiates.
Disadvantages: ontologies remain coupled to the spec release cadence; contribution surface stays heavier; consumers wanting only ontologies still clone the spec site.
Risk: Technical: Low. Schedule: Low. Ecosystem: Low.

Considerations

• Cross-repository validation. The ontologies repository would run its own CI that validates each ontology against the published ontology.schema.json. MIF would drop its ontology gates, or keep a thin smoke test over any example bundles the specification site still ships.
• Stable identifiers. Ontology id values and namespace IRIs do not change, so memories and bundles that reference an ontology by id keep working after the move.
• The base ontology is foundational. If mif-base moves, the examples that reference it must resolve it from the new location.

Decision

PENDING. Deliberately undecided. The author's current leaning is Option 1 (move all, keep the schema in MIF, publish versioned bundles), but this is recorded as a leaning, not a decision — feedback and alternatives are welcome.

Open Questions

1. Scope: move every ontology, or keep mif-base and shared-traits in MIF and move only the domain and example ontologies?
2. Consumption: how should consumers reference ontologies (a git submodule, released bundles, or raw URLs on a published site)?
3. Versioning: independent versioning per ontology, or a single repository-wide version?

Links

• modeled-information-format/ontologies (placeholder repo) · schema/ontology/ontology.schema.json
• ADR-004 (three-tier trait inheritance) · ADR-005 (underscore namespace prefix) · ADR-007 (schema $id URLs)

[zircote]

Additional context that strengthens this: the research-harness-template repository has independently grown a sizable ontology collection of its own.

It now carries roughly a dozen domain packs under packs/ontologies/ (among them scientific, observability, data-engineering, psycholinguistics, market-research, regulatory-legal, trend-analysis and software-security) plus versioned base ontologies under schemas/ontologies/ (mif-base, mif-generic, engineering-base and shared-traits). Each pack ships its own README and pack manifest, and the repository carries its own copy of the ontology-manager tooling.

Several of these overlap the MIF set: biology-research-lab, regenerative-agriculture and software-engineering exist in both repositories, and mif-base and shared-traits are duplicated outright. That divergence is exactly what a shared repository would resolve. The fact that ontologies are accumulating in two places, with copies drifting apart, is the strongest argument for giving them a single home. A dedicated modeled-information-format/ontologies repository would let both the specification and the harness consume published, versioned ontologies rather than vendor their own copies.

[zircote]

My current positions on the open questions, which refine the tentative preference in the original post:

1. Scope. Keep mif-base and shared-traits in MIF, and move only the domain and example ontologies. The base and shared-trait definitions are part of the format contract and belong with the specification. The domain ontologies are the ones that proliferate, so they are the ones that benefit from a separate home.

2. Consumption. This is under active research. I am not ready to settle on a submodule, released bundles or raw URLs, and will report back once that work concludes.

3. Versioning. I lean toward individual, per-ontology versioning. A single repository-wide version would force a bump across an inordinate number of files for any one change, which churns the version on files that did not change. Per-ontology versioning keeps each ontology's history accurate.

[zircote]

#186 186