When to use an ontology

Most data modeling on WarmHub does not need an ontology. Shapes, things, and assertions already give you schema validation, stable names, version history, and a graph you can traverse. For the majority of repos, that is the whole job.

An ontology is what you add when the hard part stops being how do I store this and becomes what does this mean — across sources, over time, and according to whom. It costs real work: semantic contracts, identity tests, naming contracts, adversarial cases, review gates. That work pays back only under specific conditions, so the first decision is whether you are in one of them.

You probably don’t need one

• One writer, one meaning. A single system produces the data and your team consumes it. Nobody disputes what a record refers to. Data modeling covers this completely.
• One authoritative source. Nothing else describes the same real-world things under a different identifier, so there is no identity to resolve.
• Nobody asks “who said this?” The data is not contested, not attributed, and carries no interpretation anyone would want to disagree with.
• Short-lived or exploratory data. It is scoped to one application’s lifetime and no one outside will build on it.

In these cases an ontology adds ceremony without adding answers. Model it with shapes and things and move on.

You probably do need one

• Several sources describe the same real-world things. Two systems report the same facility, company, or part under different keys, and something has to decide — with evidence — when two records refer to one thing.
• Answers must carry their evidence. “Why do we believe this?” has to be answerable by traversal down to a specific source snapshot, not by assertion.
• More than one party interprets the same facts. Their disagreement is knowledge worth preserving rather than a conflict to resolve away.
• The knowledge outlives its producer. Other teams, agents, or organizations will depend on it, so it needs stated contracts rather than conventions living in someone’s head.
• You are publishing for strangers. Someone outside your team will build on it, which means the interface has to be explicit.

The more of these hold, the more the discipline in this section pays for itself. If none hold, stop here.

What an ontology gets you

Intelligence is becoming cheap and universal; every organization will rent it. Knowledge is the enduring asset — it compounds, it is ownable, and it produces a reliable stream of future value. An ontology on WarmHub is knowledge in its most durable form: versioned, attributed, auditable, and composable — other ontologies, agents, and organizations can build on it the way software builds on libraries. The value is a property of the network, not any node: you rent the intelligence so that you can own the knowledge.

What makes an ontology valuable is the same thing that makes it composable: someone else can depend on it — stable identities, explicit contracts, evidence behind every claim, and a public record that it answers the questions it promises to answer.

The one-sentence version: decide which questions the ontology must answer, research the established domain semantics and identity providers those questions already rely on, write the smallest contracts that make the answers possible, prove them against adversarial real-world cases, then — and only then — turn them into repos, Shapes, and agents, layered so that grounding, identity, domain knowledge, and belief never blur.

The working mantra:

Ground observations faithfully. Preserve source identity and history. Reuse established domain meaning unless a competency question justifies divergence. Resolve real-world identity explicitly. Normalize domain semantics in composition layers. Preserve interpretations as rich Assertions. Define decision propositions precisely. Express epistemic uncertainty only where the proposition warrants it. Compose knowledge into belief without forking what you build on. Make every actionable belief mechanically traversable to its evidence.

How this section is organized

The pages below are the design method, in order. They assume you have decided an ontology is warranted and know roughly what problem it should address. The initial design is done when one real question can be answered end to end, its evidence is traversable, adversarial cases pass, and the resulting contract can be released and evaluated.

Page	What it covers
The four-layer architecture	Grounding, identity, domain knowledge, belief — and why the boundaries are enforceable
Platform consequences	What Shapes, Things, Assertions, Collections, and wrefs imply for ontology design
The self-describing ontology	The Shape suite that makes a repo document its own ontology
The process	Ten stages, with one worked example carried throughout
Composing ontologies	How independently owned ontologies build on each other
Anti-patterns	The eleven recurring ways ontologies go wrong
Review gates	The checklists a reviewer applies at each decision point
Worked example	Meridian Engineering, end to end, as a traversable pedigree
Ontology Shape reference	Field-level specifications for the eight method Shapes
Grounding Shape reference	Field-level specifications for Source and SourceArtifact

This section does not restate the platform reference. Platform concepts link to the pages where they are defined; only their ontology-design consequences are covered here.

Native component baselines

This method is aligned with two independently installable native components:

Suite	Registry ref	Version
Ontology method	warmhub-data/ontology	2.0.1
Grounding and provenance	warmhub-data/grounding	4.0.0

The component manifests are the installable field-level contracts; these pages are the design method and doctrine that explain how to use them. A component release that changes a Shape, seed, or contract must update the affected text and this baseline in the same review cycle.