Platform consequences

The primitives — Shapes, Things, Assertions, Collections, wrefs, writes — are documented in the platform reference. What follows is only what they imply for ontology design.

Everything is a versioned Thing with a Shape; an Assertion is a Thing about another Thing; a Collection is a Thing that groups Things. Three design consequences:

1. Thing vs. Assertion is an epistemic choice. Single canonical state, nobody will ask “who said this?” → Thing. Attribution, multiple perspectives, confidence, or interpretation history → Assertion. Reference data is Things; an analyst’s judgment is an Assertion.
2. Shapes are duck-typed contracts (details): declare fields that carry stable, reusable semantics; leave experiments undeclared; promote a repeated undeclared field into the Shape. Use field constraints — they are part of your semantic contract.
3. Assertions bind their subject’s identity, and the binding is immutable — mis-targeted means retract and re-add, which is what keeps the claim–subject relationship auditable.

Choose the smallest relationship representation

Choose the smallest relationship representation that completely answers the competency question, and stop at the first form that works:

1. Direct shaped wref — the default for a canonical, unqualified relationship owned by a Thing. A field such as Measurement.permitRequirement: wref<PermitRequirement> is already a graph edge rooted in durable target identity, rename-safe, and backlink-indexed. Current committed fields preserve an exact target-version pin; do not claim that they follow future target HEAD revisions. Classify each direct relationship as semantically version-bound or identity-bound. Exact evidence, releases, schemas, and historical inputs are version-bound. Enduring canonical relationships may require the separately proposed Shape-declared identity-binding platform feature; until it ships, record that dependency rather than manufacturing holder revisions. A direct link’s provenance can be reached through the owning Thing and its grounded evidence; do not add an Assertion merely to duplicate that provenance.
2. First-class Thing — use when the relationship has independent identity, lifecycle, attributes, more than two participants, or is itself the domain object: a permit, inspection, funding award, or membership period.
3. Assertion about an Arc or Bond — use only when the relationship itself is an attributed or contestable claim, needs relationship-specific qualifiers or history, or may carry competing assertions. A —predicate→ B is an Assertion of a predicate-defining Shape about Arc(from: A, to: B); symmetric claims such as contested identity resolution use Bond{A, B}.

Real multiplicity may use the semantically appropriate native Set or List; multiplicity alone does not turn a relationship into an asserted edge. For example, a source-supplied singular permit requirement on a measurement is a direct wref, while source-attributed ownership or contested same-identity resolution earns an Arc/Bond Assertion because the link itself is the claim.

When the third form is earned, the rules that keep it sound are:

• An Arc asserts nothing by itself; meaning arrives with the Assertion Shape. One Arc can carry Ownership, Operation, and more — one tuple, many predicates.
• Reverse traversal is role-aware: about-queries with collection resolution accept a role filter (from, to, ends) — “everything where this facility is the object of a relationship” is one query. The forwardLabel/inverseLabel in the predicate declaration tell the reader what each direction means.
• Relationship qualifiers (role, share, valid time, evidence) live on the Assertion, never on an endpoint.
• The Arc’s name is an ontology contract. The platform never converges independent writers who group the same members, so every predicate declares a deterministic subject-naming recipe (PredicateDeclaration.subjectNameRecipe) — otherwise two writers mint two relationship subjects and split the assertion pile.

Names are navigation, event routing, and packaging

See naming as navigation for the platform guidance. Ontology-specific rules on top of it: lead with the dimensions agents narrow by; keep Things of one Shape at predictable depth; never encode cross-Thing relationships in names (ownership changes and the name lies); never choose segments falsified by identity-preserving change; and an optional layer segment (grounding/, identity/, a concrete domain such as water/, or ontology/) earns its place by scoping queries, subscriptions, and tokens. When present, it is always the first segment after the Shape. The component examples Source/{system-slug} and SourceArtifact/{dataset-stream} are conventions that a repository may replace through its NamingContracts, not immutable platform names. A SourceArtifact hash belongs to a Thing version’s data and canonical bytes, never in the logical stream’s enduring name.

Never store a wref in a string field

Wrefs resolve through durable ids and rehydrate to current names on read (wrefs); committed reference fields currently preserve exact target-version pins. A wref in a string is a frozen lookup: no edge, no backlinks, silent staleness. URLs live in their own string fields. Do not confuse rename-safe durable identity rooting with a relationship that follows future target versions; that second semantic requires an explicit identity-binding contract when the platform supports it.

One owning repo per canonical Thing

Everyone else references it by canonical wref — composition never copies or forks upstream facts. This single rule is what makes the public/private and provider/consumer splits work.