The self-describing ontology
The outputs of the design process are not documents about the ontology — they are part of the ontology, written into the repo under the ontology/ namespace using a conventional suite of Shapes. Shapes are Things, so contracts are Assertions about the Shapes they govern, version-bound to the exact schema revision. The result is a self-documenting repo: an agent can read the charter, the questions, every type’s identity test, every predicate’s direction and naming recipe, the adversarial cases, and the evaluation record — all by query, no out-of-band documents.
| Shape | Kind | About | Role (stage that produces it) |
|---|---|---|---|
OntologyCharter | Thing | — | mission, non-goals, binding commitments, dependencies (Stage 0) |
CompetencyQuestion | Thing | — | a question the ontology must answer (Stage 1) |
SemanticContract | Assertion | a Shape | definition, identity test, counterexamples (Stage 2) |
PredicateDeclaration | Assertion | a predicate Shape | direction, member patterns, subject-name recipe, cardinality, anti-inferences (Stage 3) |
NamingContract | Assertion | a Shape | name template, segment semantics, globs, identity-stability test (Stage 4) |
GoldenCase | Thing | — | adversarial case pointing at live exemplar wrefs (Stage 5) |
OntologyDecision | Thing | — | consequential open/resolved choice with alternatives and reopening evidence (all stages) |
release Set | Collection | — | the versioned set of contract assertions = one ontology release (Stage 9/10) |
CompetencyEvaluation | Assertion | a CompetencyQuestion | a specific release answers this question — carries release: wref, the query, and the result digest (Stage 9/10) |
Full field-level specifications are in the Ontology Shape reference. Conventions:
- Instances live under
ontology/<kind>/...names, one kind segment per Shape:ontology/questions/...,ontology/contracts/...,ontology/predicates/...,ontology/naming-contracts/...,ontology/golden-cases/...,ontology/decisions/..., andontology/evaluations/.... The name does not give an instance its Shape; each instance declares its Shape inshapes, for example"shapes": ["CompetencyQuestion"]onontology/questions/water/001. See naming as navigation. - Two instances keep fixed historical names instead: the charter,
OntologyCharter/ontology/charter, and the release Set,Set/ontology/release. External tools fetch them by these exact names (see the Ontology Shape reference). Their first segment does not select a Shape either, andontology/**does not match them, so read them by name. - The ontology description is repo-scoped. The
ontology/namespace and the two fixed names describe only the ontology within its repo: the charter charters this repo; contracts are asserted only about Shapes this repo owns; releases pin this repo’s contracts. A repo’s steward cannot bind other repos, and must not try. - Cross-repo relationships are dependency declarations, not membership. An ontology that composes over upstream repos records them in
OntologyCharter.dependsOn— ideally pinned to the upstream ontology’s release Set, like a lockfile. Contracts about upstream Shapes belong to the upstream steward; what a consumer owns is its dependency, its bridges, and its own derived contracts. - Multi-owner arrangements need no special case: a “hub” is simply another repo whose ontology is a composition ontology — its charter declares dependencies on the member ontologies, described repo-scoped like everything else.
The ten stages produce these instances directly — the worked example fills them in as it goes.