Ontology Shape reference

The warmhub-data/ontology component (2.0.2) is the installable field-level contract. It owns the eight method Shapes below and seeds no repository content. This page explains their doctrine and well-known names; where field metadata is needed for a write, read the installed Shape.

SemanticContract, PredicateDeclaration, NamingContract, and CompetencyEvaluation each declare composes: ["Assertion"]. Their effective contract includes the native about field: write the target in data.about and declare the method Shape in shapes; a separate Assertion declaration is unnecessary. For contracts about a Shape, use its exact installed hub/shapes/<Name>@vN reference. See composite Shapes.

Field types use the platform’s Shape vocabulary; ? marks optional. Every reference field is wref-typed (see anti-pattern 11), and where the target is a shaped Thing, constrain it to the target Shape — {"type": "wref", "shape": "Source"} — which the platform enforces at write. The constraint passes when the named Shape is in the target’s Shape set: a Shape the target declares, or one reached from those through composition. Any one match is enough; no Shape in the set is primary. A shapeless thing and a Shape definition never pass, so Shape-referencing fields like requiredConcepts stay unconstrained.

These specifications are the Shapes as they should be committed — put these descriptions in the Shape and field descriptions so the repo teaches its own ontology vocabulary.

Instances are named under ontology/<kind>/..., such as ontology/questions/... or ontology/contracts/... (see naming as navigation). A name does not give an instance its Shape; each instance declares its Shape in shapes. The charter and the release Set are the two exceptions to the naming pattern: they keep fixed historical names, described in their sections below.

OntologyCharter

Thing. One active charter per repo — the constitution of this repo’s ontology. Because it is a singleton, it has a fixed, well-known name: OntologyCharter/ontology/charter — any agent can fetch it in any repo without discovery. This is a historical name, kept for compatibility with the warmhub-data/ontology component and the design-warmhub-ontology toolkit, which fetch it by this exact name. Its first segment does not select a Shape: the charter declares its Shape in shapes (["OntologyCharter"]), like any other Thing. Because it does not start with ontology/, a glob such as ontology/** does not match it; fetch it by name.

Field	Type	Description	Example
mission	string	What this repo’s ontology represents and for whom (the audience belongs in the mission; per-question personas live on the questions) — one paragraph a reviewer can test proposals against.	“Canonical identity and regulatory knowledge for US public water infrastructure — for the engineers, analysts, and agents who compose beliefs over it.”
nonGoals	string[]	What this ontology deliberately is not. As load-bearing as the mission.	["Utility finance and rates", "Hydraulic process modeling"]
commitments	string[]	Binding design rules (identity, epistemic, temporal, layering). A proposal that violates one requires an OntologyDecision, not a silent exception.	["Evaluate established domain identities before minting alternatives; never assume or reject source identity categorically"]
dependsOn	wref[]?	Upstream ontologies this repo composes over — each entry the canonical wref of an upstream release Set (preferred: pins the exact contract versions depended on, like a lockfile) or an upstream charter. Dependencies, never membership: this charter binds only its own repo.	[wh:pub/us.environmental.epa-npdes/Set/ontology/release@v4]

CompetencyQuestion

Thing. A question the ontology must answer — the unit of scope, evaluation, and acceptance. The deletion test runs against these. Naming: ontology/questions/{domain}/{id}.

Field	Type	Description	Example
question	string	The question, phrased as its persona would actually ask it — including the decision it feeds, where that matters.	“Which NC wastewater facilities show recurring warm-season ammonia exceedances — and on what evidence?”
personas	string[]	Who asks it.	["water-practice lead", "market analyst"]
requiredConcepts	wref[]	The Shapes this question depends on — the deletion-test receipts. A Shape no question cites does not ship.	[hub/shapes/Facility, hub/shapes/Measurement, hub/shapes/PermitLimit, hub/shapes/PerformancePattern]
temporalSemantics	string?	Observation window, seasonality, as-of semantics the answer must honor.	“Warm season = May–Sep; windows 2022–2025; answer as-of latest complete quarter”
provenanceRequirement	enum? (none, source-level, artifact-hash-level)	How deep the answer’s pedigree must reach to count as answered.	artifact-hash-level

SemanticContract

Assertion, about a Shape this repo owns. The semantic contract governing a type, version-bound to the exact Shape revision it governs. Naming: ontology/contracts/{type}.

Field	Type	Description	Example
definition	string	What the concept is, in domain language and, when adopted, the established authority’s terms.	“A facility, site, or place of environmental interest identified under the reviewed EPA FRS contract”
identityTest	string	When do two records refer to the same one of these? The heart of the contract — most ontology failures are identity failures.	“Same EPA FRS Registry ID under the reviewed FRS lifecycle and correction rules”
examples	string[]?	Things that are this concept.	["FRS Registry ID 110012345678"]
counterexamples	string[]?	Things that look like this concept and are not under the adopted authority contract.	["A linked NPDES program record", "A permit held by the facility"]
lifecycleNotes	string?	How identity begins and ends, including adopted authority correction, merge, split, reuse, and succession behavior.	“Follow reviewed FRS correction, merge, and split semantics; display-name or program-link changes preserve identity”
lifecycleStatus	enum (candidate, experimental, approved, promoted, deprecated)	Contract maturity; consumers read this before depending.	approved

Which questions a type serves is not stored — it is the backlink query over CompetencyQuestion.requiredConcepts. Never store what the graph already encodes.

PredicateDeclaration

Assertion, about a predicate Shape this repo owns. The relationship’s ontological metadata — everything a writer or reader needs that does not belong on the predicate Shape’s field list. Naming: ontology/predicates/{predicate}.

Field	Type	Description	Example
subjectPattern	string	Name-glob for the relationship subject (Arc from / first Bond end).	identity/organizations/**
objectPattern	string	Name-glob for the relationship object (Arc to / second Bond end).	identity/facilities/**
forwardLabel	string	Subject→object reading.	“owns”
inverseLabel	string	Object→subject reading.	“is owned by”
subjectForm	enum (arc, bond)	Directed or symmetric relationship subject.	arc
subjectNameRecipe	string?	Deterministic recipe for naming the Arc/Bond. The platform never converges independent writers; this recipe is what makes them mint one relationship subject instead of two. State what happens on member rename.	identity/relations/{subject-last-segment}--{object-last-segment} → identity/relations/town-of-millbrook--millbrook-wrf
structuralCardinality	enum (one:one, one:many, many:one, many:many)	Across all modeled history.	many:many
concurrentCardinality	enum? (same values)	During overlapping valid time — a different question (joint ownership is real).	one:many
epistemicClass	enum? (source-claim, normalized-state, binomial-proposition)	Which kind of claim this predicate makes. Never collapse the three into one Shape.	normalized-state
prohibitedSemantics	string[]?	Meanings this predicate must not be used for (Ownership is not operation, not permitteeship).	["operation", "permitteeship"]
antiInferences	string[]?	The seductive shortcuts agents must not take. Put these where agents will read them.	["permit-issued-to does not imply ownership"]

Whether instances carry valid time is visible from the predicate Shape’s own fields; evidence expectations belong in the Shape’s field constraints and description.

NamingContract

Assertion, about a Shape this repo owns. The namespace contract for a Shape’s Things. Naming: ontology/naming-contracts/{shape}. A name template does not assign a Shape: a Thing named by the template still declares the Shape in shapes.

Field	Type	Description	Example
nameTemplate	string	The name template for this Shape’s Things.	identity/facilities/epa-frs/{registry-id}
segmentSemantics	string[]	What each segment means and why it is where it is (leading segments = the dimensions agents narrow by; layer segment = cross-shape scoping; kind segment = keeps this Shape’s names apart from other Shapes’ names).	["identity — the layer; scopes globs and tokens", "facilities — the kind of record", "epa-frs — adopted identity authority", "registry-id — authority-managed key"]
exampleNames	string[]	Enough real examples that an agent can infer the convention and predict nearby Things (depth included).	[identity/facilities/epa-frs/110012345678]
globs	string[]?	The subtree selections this namespace is designed to serve — the same vocabulary scopes queries, subscriptions, and tokens.	[identity/facilities/epa-frs/**, identity/**]
identityStabilityTest	string	Which real-world changes must not falsify a name. If an identity-preserving change breaks the name, the contract is wrong. (No-relationships-in-names is a global rule, not per-shape configuration.)	“FRS display-name, address, owner, and program-link changes must not break the Registry ID name; follow reviewed correction/split/merge semantics”

GoldenCase

Thing. An adversarial real-world case, pointing at the live data that models it. Naming: ontology/golden-cases/{slug}.

Field	Type	Description	Example
title	string	The case in a phrase.	“Several program records, one FRS identity”
narrative	string	The real-world situation, precisely why it is adversarial (which identity test or cardinality assumption it attacks), and what passing looks like. The review question is always the same: is the ontology lying?	“Linked NPDES and state program records attack the temptation to mint private facilities. Passing: both resolve to the authority-managed FRS identity while their source claims remain distinct.”
exemplarWrefs	wref[]	The live Things and Assertions modeling this case — the fixture is production data.	[identity/facilities/epa-frs/110012345678, identity/facility-references/epa-npdes/NC0071234]

OntologyDecision

Thing. A deliberately open or explicitly resolved consequential design decision. Create one only when a meaningful alternative was considered, the rationale will matter later, the choice could plausibly be revisited, and concrete settling or reopening evidence can be named. Routine fields, implementation choices, profiled source facts, and conclusions forced by accepted contracts do not earn decision Things. Unresolved-on-purpose beats silently-inconsistent. Naming: ontology/decisions/{id}.

Field	Type	Description	Example
title	string	The decision in a phrase.	“Pump stations: Facilities or components?”
question	string	What is actually being decided.	“Do pump stations get their own Facility identity, or ride as components of the works they feed?”
options	string[]	The candidate answers, with their trade-offs.	["Own Facility (can hold permits)", "Component of parent works"]
currentLean	string?	The working position, if any.	“Own Facility”
settlingEvidence	string?	What observation or experiment would settle it — the decision’s exit criteria.	“Whether any NC pump station holds its own NPDES permit”
status	enum (open, resolved, superseded)	Lifecycle.	open
resolution	string?	The answer and its rationale, once resolved.	—

Releases (named Set)

A release is a named, revisable Set with a fixed, well-known name — Set/ontology/release, a singleton like the charter — whose members are the repo’s current contract assertions (SemanticContract, PredicateDeclaration, NamingContract), each about-bound to the Shape version it governs. Write each member with an explicit @vN: Set members accept both forms, and a bare or @HEAD member follows the contract’s later revisions instead of recording the version released. Create it only when those contracts form the first usable release; never create a charter-only placeholder. Each revision of the Set is one release in that repository: one durable identity whose version history is the repository-local release history. A fresh repository initialized directly to today’s reviewed state creates Set/ontology/release@v1; an existing repo continues from its actual current version. Contracts-as-members captures both schema versions and contract versions; downstream consumers pin dependsOn to a specific release version.

Repository-local identity and portable semantic comparison are orthogonal. If tooling computes a deterministic digest of a reviewed release bundle, equal digests may attest that two repositories carry equivalent contract content, but the digest neither replaces either release wref nor synthesizes its history. No portable digest field belongs in the shared component until a demonstrated consumer requires one.

Set/ontology/release is a historical name, kept for compatibility with the warmhub-data/ontology component and the design-warmhub-ontology toolkit, which fetch it by this exact name. Its first segment does not select a Shape: the release declares its Shape in shapes (["Set"]), like any other collection. Because it does not start with ontology/, a glob such as ontology/** does not match it; fetch it by name.

CompetencyEvaluation

Assertion, about a CompetencyQuestion. The claim that a specific release answers a specific question. Binomial and attributed — independent evaluators may disagree, and Veritas consensus over evaluations is meaningful. Naming: ontology/evaluations/{release-version}/{question}.

Evaluation is ex-post, by construction. A release must exist before anything can reference it, and shape versions cannot be staged — so the sequence is always: revise contracts → revise Set/ontology/release (a new release) → evaluate against it. A failing evaluation is not a blocked release; it is a recorded fact about this release and a fix in the next one — releases are cheap. The gate is on adoption, not on release: consumers pin dependsOn to releases whose evaluation record passes the questions they care about.

Field	Type	Description	Example
release	wref	The release evaluated — Set/ontology/release pinned to the version under test. Write it as @vN; a field with the default versioned binding pins a bare wref to the latest version at write time, which is the version under test only if no release followed. Backlinks make “all evaluations of release N” one query.	Set/ontology/release@v3
passed	boolean	Did the release answer the question within its provenance requirements?	true
evaluator	string	The agent or human who ran the evaluation and stands behind it.	evaluate-ontology/1.2 (agent)
evaluatedAsOf	string	ISO timestamp of the evaluation run.	2026-07-01T04:00:00Z
queryExecuted	string	The concrete query or traversal used — the evaluation must be reproducible.	“reverse-about: PerformancePattern Things under water/performance-patterns/** where patternClass=recurring-warm-season-elevation → Facility”
resultDigest	string?	Short digest of the result that satisfied (or failed) the question.	“14 facilities; every pattern traverses to a DMR artifact hash”
notes	string?	Scale caveats, cohort scope, re-run triggers.	“NC cohort only; re-run when a new DMR quarter lands”