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. Classify each direct relationship as semantically version-bound or identity-bound, and declare it on the field with binding. A wref field with no binding is versioned: the write pins the target’s current version. A field declared "binding": "identity" follows the target as it is revised. Exact evidence, releases, schemas, and historical inputs are version-bound. Enduring canonical relationships are identity-bound; declare them so rather than revising the holder to advance a pin. 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 the first segment of the name, followed by a segment for the kind of record, as in identity/facilities/.... Names are unique across the repository, so give each kind of record its own segment rather than relying on the Shape to tell names apart. A name’s first segment never selects a Shape: each Thing declares its Shapes in shapes, and queries, subscriptions, and tokens filter on Shape separately from name. The grounding examples sources/{system-slug} and artifacts/{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); whether a reference field pins a version or follows the target is set by the field’s binding. 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; the second needs a field declared "binding": "identity".

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.