YAML-LD Relationship Assertion Mapping

Status: implementation guide.

This document records how the evidence-bearing semantic assertion model in the canonical YAML-LD layer should project into the current Explorer relationship runtime without changing the meaning of the underlying assertion.

The semantic source is the bundle-wiki semantic assertion contract in profiles/bundle-wiki/v1/semantic-assertion.schema.json with term bindings from profiles/bundle-wiki/v1/semantic-context.jsonld. The current Explorer runtime row contract is okf-relationship-assertion.v2 and the in-app TypeScript shape is OkfRelationship.

Design Rules

The YAML-LD semantic assertion is the authoritative source.
okf-relationship-assertion.v2 is a generated runtime projection, not a competing hand-authored truth source.
A governed relationship should exist twice in the semantic layer: one direct triple and one evidence-bearing assertion record.
The projection must preserve authority, derivation, evidence, rights, freshness and review state without collapsing them into one label.
Confidence must never upgrade a model-derived assertion into official or derived.
Context resolution stays pinned and local. The browser must not rely on arbitrary remote context retrieval.

Field Mapping

Semantic assertion field	Runtime projection	Rule
`@id`	`id`	Preserve the assertion IRI verbatim as the stable relationship identifier.
`@type`	passthrough extension field	Keep the semantic type on the runtime object when present; there is no dedicated `OkfRelationship` field for it.
`source`	`source`, `source_iri`	Resolve the semantic IRI through the integrity-bound IRI-to-route registry. Set `source` to the safe local route and `source_iri` to the absolute IRI. An endpoint without a governed route remains semantic-only until the producer authors one; the runtime must not guess or substitute an absolute URL as a local route.
`target`	`target`, `target_iri`	Apply the same rule as `source`.
`predicate`	`predicate`	Preserve the canonical predicate identifier as the runtime `predicate` string.
`kind`	`kind`	Carry the primary human-readable label used by current cards and graph legends.
`label`	`label`	Preserve when distinct from `kind`; otherwise repeat the governed `kind` value because the shared runtime contract requires both fields.
`inverse_label`	`inverse_label`	Preserve for reverse-direction presentation.
`assertion_status`	`assertion_status`	Preserve unchanged.
`assertion_scope`	`assertion_scope`	Preserve unchanged.
`authority.class`	`authority.class`	Preserve unchanged and validate against `assertion_status` and `assertion_scope`.
`authority.label`	`authority.label`	Preserve unchanged.
`authority.source`	`authority.source`	Preserve the canonical credential-free HTTP(S) source URL; reject browser-repaired or unsafe forms.
`derivation`	`derivation`	Preserve the semantic derivation identifier as a string.
`derivation_activity`	`derivation_activity`	Preserve unchanged.
`rule`	`rule`	Preserve unchanged.
`supporting_assertions`	`supporting_assertions`	Preserve as the set of upstream assertion identifiers that support an inferred assertion.
`confidence_score`	`confidence_score`	Preserve as the machine-comparable score. Do not mirror it into `confidence` unless a compatibility surface requires a display alias.
`strength`	`strength`	Preserve unchanged.
`count`	`count`	Preserve unchanged.
`observed_at`	`observed_at`	Preserve unchanged.
`stale_after`	`stale_after`	Preserve unchanged.
`review_status`	`review_status`	Preserve unchanged.
`evidence[]`	`evidence[]`	Preserve structured evidence rows rather than flattening them to URLs when the source declares hashes, locators, or field provenance; validate `url` and optional `resource` as canonical HTTP(S).
`rights.source`	`rights.source`	Preserve the canonical credential-free HTTP(S) source URL.
`rights.assertion`	`rights.assertion`	Preserve unchanged.

Projection Algorithm

Expand or normalize the authored YAML-LD against the pinned local context set and convert all IRI-valued fields to absolute strings.
Emit the direct semantic triple from source, predicate and target.
Emit one runtime relationship row carrying the same identifiers plus the evidence-bearing assertion metadata.
Resolve internal navigation through the integrity-bound IRI-to-route registry rather than guessing routes from external identifiers.
Validate every semantic assertion against the pinned local shared Draft 2020-12 schema, then validate the runtime row against the same status, scope and authority rules as okf-relationship-assertion.v2.
Compile relationship summaries only after complete-population row-level validation succeeds.

Status And Authority Compatibility Rules

The generated runtime row must keep the existing invariant:

official plus real-world implies authority.class = official.
normalized plus real-world implies authority.class = derived.
inferred plus real-world implies authority.class = derived.
model-derived plus real-world implies authority.class = model-assisted.
synthetic-fixture implies authority.class = synthetic.

Additional requirements remain unchanged:

inferred requires rule, supporting_assertions, confidence_score and derivation_activity.
model-derived requires confidence_score, derivation_activity and review_status.

Federation Special Case

Federation inline relationships are a control-plane summary, not a general RDF instance graph. Their source and target fields must continue to reference declared child IDs because the federation loader validates them against the child list.

When a federation also wants stable global identity:

keep source and target as child IDs;
place the global identifiers in source_iri and target_iri;
keep the canonical governed predicate in predicate;
keep authority, derivation, freshness, evidence and rights unchanged.

This preserves the current overview loader contract while allowing the federation to participate in the semantic layer.

Small And Large Bundle Guidance

For small bundles and large-corpus relationship rows:

prefer canonical IRIs in predicate;
preserve kind or label for human display;
preserve source_iri and target_iri even when a route is also known;
keep structured evidence objects whenever the source declares reversible provenance, hashes, or locators.

Non-Goals

This mapping does not:

require a full browser reasoner;
replace route-scoped JSON adjacency for very large corpora;
permit arbitrary remote contexts in the browser;
treat presentation-only grouping as a semantic assertion.