RFC: MIF Extension Ecosystem - Packaging, Distribution, and Discovery

[zircote]

Summary

This RFC proposes a design for building and sharing MIF ontology extensions as separate repositories, usable both privately and as shared community resources across industries.

The design follows these principles:

• No new CLI tooling: extensions are consumed via Git and existing tools
• Hybrid discovery: a central index for browsing, direct Git URLs for resolution
• Breaking schema changes are acceptable since we are pre-1.0
• Works the same for enterprise teams and open-source contributors

---

Ontology Schema Evolution (v0.2.0)

The ontology: block gets new fields so each file is a complete package on its own. No sidecar manifest.

New Fields

Field	Required	Type	Purpose
mif_compat	yes	string (SemVer range)	MIF spec versions this works with
depends	no	map (ID to SemVer range)	Version constraints on dependencies
provides	no	string list	Exported trait/entity/namespace names
keywords	no	string list	Discovery tags
license	no	string (SPDX)	License identifier
homepage	no	string (URL)	Docs/repo link
authors	no	list of objects	Maintainer info
registry	no	string (URL)	Link back to index entry
components	no	list of relative paths	Multi-ontology repos: paths to other ontology files

Design Decisions

extends stays simple. It remains a flat list of ontology IDs. No inline version pinning. All version constraints live exclusively in depends.

• extends = structural ("I inherit these traits and namespaces")
• depends = contractual ("I require these at these versions")

Every ID in extends should have a corresponding depends entry. Tooling warns when it doesn't, but doesn't fail. This keeps single-file ontologies that just extends: [mif-base] valid without requiring a depends block.

Example

ontology:
  id: regenerative-agriculture
  version: "0.2.0"
  description: "Regenerative agriculture ontology covering farm ops, supply chain, carbon markets, and certification"
  schema_url: "https://mif-spec.dev/schema/ontology/ontology.schema.json"
  extends:
    - mif-base
    - shared-traits
  mif_compat: ">=0.2.0 <1.0.0"
  depends:
    mif-base: ">=0.1.0"
    shared-traits: ">=0.1.0"
  provides:
    - "trait:geolocated"
    - "trait:soil_tested"
    - "entity:field"
    - "entity:soil_test"
    - "namespace:_semantic/farm_ops"
  keywords: [agriculture, carbon, soil, sustainability, certification]
  license: "Apache-2.0"
  homepage: "https://github.com/zircote/mif-agriculture"
  authors:
    - name: "Allen R"
      url: "https://github.com/zircote"
  registry: "https://github.com/mif-spec/index/blob/main/index/zircote/regenerative-agriculture.yaml"

---

Multi-Ontology Repos

Default convention: one ontology per repo, file named {repo-name}.ontology.yaml at root.

Multi-ontology repos are allowed but must declare their components via the components field in a root-level umbrella ontology:

ontology:
  id: agriculture-suite
  version: "0.1.0"
  description: "Suite of agriculture-related ontologies"
  extends: [mif-base]
  mif_compat: ">=0.2.0"
  components:
    - ontologies/crop-management.ontology.yaml
    - ontologies/soil-science.ontology.yaml
    - ontologies/supply-chain.ontology.yaml

Each component is independently versioned and independently consumable. The umbrella is a convenience grouping. Index entries for multi-ontology repos include a path field pointing to the specific file.

---

Hybrid Index

A Git repository (github.com/mif-spec/index) serves as the central discovery mechanism. Extensions not in the index can still be consumed by direct Git URL.

The closest model here is Homebrew taps: a lightweight YAML index backed by Git repos. For trust tiers, think Docker Official vs. Verified Publisher.

Index Structure

mif-index/
  index/
    mif/                              # official (core team only)
      mif-base.yaml
      shared-traits.yaml
    {org}/                            # verified (namespace-claimed orgs)
      {extension}.yaml
    community/{user}/                 # open (anyone via PR)
      {extension}.yaml
  owners/
    {org}.yaml                        # namespace ownership claims
  schema/
    index-entry.schema.json
  GOVERNANCE.md
  CONTRIBUTING.md

Index Entry Format

name: regenerative-agriculture
namespace: zircote
source: https://github.com/zircote/mif-agriculture
path: "regenerative-agriculture.ontology.yaml"
description: "Regenerative agriculture ontology covering farm ops and supply chain"
keywords: [agriculture, carbon, soil, sustainability]
license: Apache-2.0
tier: verified
versions:
  "0.2.0":
    ref: v0.2.0
    mif_compat: ">=0.2.0"
    sha256: "abc123..."
    depends:
      mif-base: ">=0.1.0"
      shared-traits: ">=0.1.0"

Publishing Flow (no CLI needed)

1. Author pushes their extension to a Git repo, tags a release
2. Author opens a PR to mif-index adding/updating their entry YAML
3. CI validates: schema compliance, checksums match, mif_compat is satisfiable, no namespace collisions
4. Merge = published

---

Trust Tiers

Tier	Namespace	How to get in	Signals
Official	mif/	Core team only	Ships with MIF spec
Verified	{org}/	Claim namespace via owners/{org}.yaml PR with proof of org control	Namespace locked to owners; CI-gated
Community	community/{user}/	Open PR, passes CI	Automated validation only

Namespace Claiming

An org submits a PR adding owners/{org}.yaml containing GitHub org name or GPG key fingerprints. Once merged, only those identities can add/modify entries under index/{org}/. One-time process.

Private Extensions

Private extensions never enter the public index. They're consumed by direct Git URL. Enterprises can fork the index structure for internal discovery using the same format.

---

Composability Rules

1. Namespace isolation is the default. Each extension's entity types and custom namespaces are prefixed by their ontology ID. agriculture:soil_test and biology:soil_test can't collide.

2. Traits inherited via extends are shared, not duplicated. If both agriculture and supply-chain extend shared-traits, the certified trait is the same trait. No conflict.

3. A conflict exists when two extensions that share no common ancestor in the extends DAG both define a trait with the same name. Tooling detects this by walking the DAG.

4. Conflict resolution is the consumer's job. The consumer creates their own ontology that extends both conflicting extensions and explicitly redefines the contested trait. No magic merging, no implicit precedence.

5. No new syntax is needed for any of this. The extends DAG + traits map + provides list give tooling enough information to detect conflicts. The existing validate_ontology.sh can be extended to walk the DAG.

---

Versioning Contract

What counts as a breaking change for ontologies:

Change	Version Impact
Remove entity type, trait, or namespace	Major
Change field type	Major
Add required field to existing trait/entity	Major
Change ontology id	Major
Add new entity type, trait, or namespace	Minor
Add optional field to existing trait/entity	Minor
Loosen constraints (expand enum, relax validation)	Minor
Description/doc/keyword changes	Patch

---

Extension Repo Convention

Minimal extension

my-extension/
  my-extension.ontology.yaml     # THE extension (required)
  README.md                       # human-readable docs (required)
  LICENSE                         # SPDX license (required)

Full-featured extension

my-extension/
  my-extension.ontology.yaml     # primary ontology
  ontologies/                     # additional ontologies (multi-ontology)
    sub-domain-a.ontology.yaml
    sub-domain-b.ontology.yaml
  examples/                       # example memory files
    sample-decision.mif.yaml
    sample-incident.mif.yaml
  tests/                          # validation test cases
    valid/
    invalid/
  CHANGELOG.md
  README.md
  LICENSE

Tooling discovers the primary ontology by looking for {repo-name}.ontology.yaml at the repo root.

---

Explicitly Deferred

Concern	Status	Future Path
MIF CLI (mif install)	Not building	If adoption warrants it
Lock file / dependency resolver	Not needed	depends is advisory; Git tags pin versions
Cryptographic signing	Deferred	Cosign/Sigstore when trust tier demands it
OCI artifact distribution	Designed for	Index format can point to OCI refs later
Registry API server	Deferred	TBD

---

Feedback Requested

• Does the extends (structural) vs depends (contractual) separation make sense, or is it confusing to have both? I went back and forth on this. The alternative is inline version pinning on extends, but that muddies the inheritance semantics.
• Is the three-tier trust model (official/verified/community) the right granularity? Two tiers might be enough early on.
• Should the versioning contract (what counts as breaking) be formalized in the spec itself, or left as guidance?
• The multi-ontology repo convention with components might be over-designed for now. Worth keeping, or cut it until someone needs it?
• What other distribution models should we look at for inspiration?