OKF 0.2 and YAML-LD semantic authoring

Status: Explorer v0.7.0 and Land Registry v0.3.0 are released immutably and publicly verified. Land Registry retains Explorer v0.6.2 as its governed acceptance dependency; v0.6.3 is the separate post-G9 presentation correction, and v0.7.0 is the independently governed Explore OKF authoring release. The final Land Registry cache-isolated receipt verifies 2,203 records, 14 dataset groupings, 2,203 resources and 22,267 relationships, 12 August 2026.

This document is the common authoring, generation and Reader contract for the okf-* repositories. It explains the two layers that must remain distinct:

1. OKF 0.2 core is the deliberately small, forward-compatible Markdown format. A concept needs parseable YAML frontmatter and a non-empty type; a bundle root can declare okf_version: "0.2".
2. The OKF Bundle Wiki semantic profile v1 is an additive application profile. It supplies stable semantic identity, YAML-LD/JSON-LD, evidence-bearing directed assertions, governed predicates, safe Explorer routes and deterministic runtime projections.

Semantic requirements in this document are profile requirements, not claims about the upstream OKF core specification. The upstream specification allows unknown fields and deliberately defers a general semantic-layer template.

Rollout progress

This is the live dependency-ordered implementation ledger. Current state records what has already happened; next action records work still to do. Local migration present never means committed, released, deployed or publicly verified.

The producer order above is deliberately serial at the publication boundary: each repository gets its own review history, checks, commit, release decision and public verification. Analysis and bounded validation may run in parallel, but one producer's local success is never evidence that another was released.

The one-source model

flowchart LR
  A["Authored Markdown YAML-LD, source registers and domain assertions"] --> B["Pinned-context semantic normalisation"]
  B --> C["Canonical YAML-LD graph"]
  B --> D["Deterministic JSON-LD projection"]
  B --> E["Explorer nodes and relationship rows"]
  E --> F["Small bundle JSON"]
  E --> G["Large-corpus route adjacency"]
  E --> J["Digest-bound rich relationship runtime"]
  C --> H["Explorer safe YAML-LD reader"]
  F --> I["Reader, graph and relationship card"]
  G --> I
  J --> I
  H --> I

YAML-LD or Markdown YAML-LD is the semantic authoring boundary. JSON-LD is an interchange projection. Explorer JSON and adjacency shards are delivery projections. A repository must not maintain all three as independent truths.

Large collections still use manifests, locators and hash-sharded adjacency so the browser can start with a bounded overview. Semantic authority does not require the browser to download an entire RDF graph.

A rich directed relationship

A relationship is not just two routes and a label. It has three identities:

• the source entity IRI;
• the predicate IRI; and
• the target entity IRI.

It also has an assertion identity and evidence about why this repository is entitled to make or project that statement. The canonical authored pattern is a direct triple plus one reified okf:RelationshipAssertion:

---
"@context":
  - https://chris-page-gov.github.io/okf-explorer/profile/bundle-wiki/v1/context.jsonld
  - https://chris-page-gov.github.io/okf-explorer/profile/bundle-wiki/v1/semantic-context.jsonld
  - life: https://example.org/uk-life#
    provided_by:
      "@id": life:providedBy
      "@type": "@id"
"@id": https://example.org/services/register-a-birth
"@type": life:PublicService
route: service/register-a-birth
type: Public service
title: Register a birth
description: Educational service example; follow the current authority for a real case.
generated: {by: process:life-course-build, at: "2026-08-09T00:00:00Z"}
provided_by:
  "@id": https://example.org/organisations/register-office
  "@type": life:PublicBody
  route: organisation/register-office
  type: Public body
  title: Register office
assertions:
  - "@id": https://example.org/assertions/register-a-birth-provided-by
    "@type": [rdf:Statement, okf:RelationshipAssertion]
    source: https://example.org/services/register-a-birth
    predicate: life:providedBy
    target: https://example.org/organisations/register-office
    kind: provided by
    label: is provided by
    inverse_label: provides
    assertion_status: normalized
    assertion_scope: real-world
    authority:
      class: derived
      label: Deterministic projection of the reviewed service register
      source: https://example.org/source/service-register
    derivation: https://example.org/rules/provider-field-v1
    observed_at: "2026-08-09T00:00:00Z"
    evidence:
      - "@id": https://example.org/evidence/register-a-birth-provider
        type: source-metadata
        url: https://example.org/source/service-register
        source_field: provider
        source_value_sha256: aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
        retrieved_at: "2026-08-09T00:00:00Z"
    rights:
      source: https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/
      assertion: source-derived-metadata
---

The direct triple makes the graph useful to ordinary RDF tooling. The assertion node carries provenance, authority, freshness, review and rights. The build fails when only one side exists, when two assertions reify the same triple in one assertion plane, or when the IRI-to-route registry cannot map an internal endpoint safely.

Identity and routes

Semantic identity and browser navigation are intentionally separate:

Never manufacture an absolute semantic IRI by pretending an Explorer route is already global. Never guess a local route from an external IRI in the browser. The generator owns the integrity-bound IRI-to-route registry.

Status, scope and authority

These axes are independent:

For real-world assertions, official maps to official authority; normalized and inferred map to derived authority; and model-derived maps to model-assisted authority. A synthetic fixture always has synthetic authority. Editorial examples belong in a separately labelled synthetic fixture or narrative plane; they must not be smuggled into a real-world assertion by inventing another authority level.

Confidence, strength and count are also different. Confidence estimates an assertion; strength is a domain-defined magnitude; count is multiplicity. None of them changes authority.

Authority, evidence/resource and rights source links are canonical, credential-free HTTP(S) URLs. Producers percent-encode query values and reject literal whitespace, quotes, invalid escapes, credentials and non-web schemes; the Reader never turns an unsafe provenance string into a clickable link.

What the generator must produce

For a governed semantic bundle the normal build order is:

1. parse UTF-8 YAML 1.2 without executable tags, duplicate keys, cyclic aliases, non-string mapping keys or non-finite numbers;
2. resolve only the pinned, reviewed local context set;
3. validate OKF 0.2 concept metadata and profile requirements separately;
4. expand/normalise semantic identity and reconcile direct triples with assertion nodes;
5. validate evidence, authority/status compatibility and predicate policy;
6. build the IRI-to-route and predicate registries;
7. emit deterministic YAML-LD and JSON-LD from the same normalised graph;
8. compile okf-relationship-assertion.v2 rows with local routes and retained IRIs;
9. produce small-bundle JSON or large-corpus adjacency, search and locator artefacts; and
10. bind the release snapshot, counts and output digests before publication.

The schema gate covers the complete generated assertion population before a producer writes a conformant receipt. The family-wide reconciler samples shards as a fast regression check; it deliberately does not replace exhaustive producer validation.

Claiming the canonical Bundle Wiki v1 URI also claims the complete v0.6.0 profile byte identity. The 16 regular files are governed as an opaque unit by v1.vendor-lock.json, which binds annotated tag v0.6.0 and tag object d256a74419c2593c2bf2f3f5749c606fad5daf9d, release commit 4bb7b92a64b7ba69bde9b1e86786217338cd166d, Git tree d26ae9a818041ff74c469e653ec714632ddbfc2a, sorted file sizes and SHA-256 digests, and their aggregate identity. Repositories must not retain that URI while publishing a partial or customised mirror. The reconciler can install the exact mirror explicitly with --sync-profile; it refuses divergent or extra files unless --replace-profile is also supplied and never follows a destination symlink.

The reusable implementation is in scripts/okf_semantic.py. The profile schemas are under profiles/bundle-wiki/v1/. Repository builders may use domain-specific generators, but their okf.semantic.json contract must make the same boundaries and commands discoverable.

What the Reader understands

The Reader supports five bounded delivery paths:

• generated small-bundle JSON;
• a large-corpus relationship plane split into bounded chunks whose declared total remains below the whole-plane hard cap;
• large-corpus JSON descriptors plus route-scoped adjacency;
• a digest-bound large-corpus rich relationship runtime with active/default planes, gzip chunks and a SHA-256 route locator whose per-plane assertion-ID commitments prove the selected route was hydrated completely; and
• an explicit YAML-LD/JSON-LD @graph containing route-bearing entity nodes and reified RelationshipAssertion nodes.

Relationship adjacency and rich-runtime locators are valid targeted entry points independently of a record locator. The Reader chooses them before any whole-plane relationship fallback, including for aggregate/topic routes that are not dataset records.

For a direct YAML-LD graph, the Reader parses the representation safely but does not fetch remote contexts, run OWL inference or guess RDF meaning. Each internal entity therefore needs an explicit route, and each relationship needs the complete governed assertion fields: stable identity, explicit source/predicate/target IRIs, kind, preferred/inverse labels, status, scope, authority, derivation, observation time, evidence and rights. A missing, duplicate, unsafe or inconsistent identity/route/assertion makes the explicit graph fail closed. The build remains responsible for semantic expansion, direct-triple reconciliation and exhaustive producer validation.

The rich runtime is intentionally not an instruction to download an arbitrary hub. If a route's committed incident set would exceed the aggregate chunk or row ceiling—or its selected chunks exceed the 64 MiB compressed fan-out budget—the Reader reports the exact fan-out and fails before fetching relationship shards. Rich chunks decode sequentially under the 64 MiB per-resource cap, discard undeclared row properties, limit evidence/support arrays and enforce 32 Ki UTF-16 text units per retained row plus 32 Mi text units per hydration/cache. The assertion population remains represented in the digest-bound semantic/runtime planes; high-degree aggregate topics require a separate paginated or analytical query surface rather than an unbounded graph render.

The graph keeps arrow direction. The relationship card exposes source, relationship and target separately and preserves assertion ID, predicate, inverse label, semantic IRIs, status, scope, authority, derivation, supporting assertions, confidence, observation/freshness, evidence and rights. Reverse navigation uses the inverse label only for presentation; it does not create a second asserted triple.

Repository-local contract

Every okf-* repository has one okf.semantic.json, validated by repository-contract.schema.json. It records:

• the root OKF 0.2 index and repository role;
• authoritative semantic inputs and generated outputs;
• current semantic migration state and limitations;
• assertion, identity, predicate and context policy;
• exact build and check commands; and
• the Reader delivery path and preserved fields.

Run the cross-repository audit with:

uv run --locked python scripts/reconcile_okf_repositories.py

Use --strict when selecting a release candidate. The default mode separates hard contract/core errors from explicit migration warnings so legacy local predicate names or descriptor-only YAML-LD remain visible rather than being silently treated as complete.

The reviewed okf-uk-living producer must also declare the complete rich relationship runtime: its manifest, bounded gzip plane chunks, SHA-256 route locator and buckets, and the four executable Draft 2020-12 runtime schemas. The reconciler validates every row against the pinned local schemas, rejects remote or recursive schema references, and checks both route-scoped and whole-plane loading against the Reader's aggregate row, chunk, compressed-byte and retained-text ceilings. When a reviewed producer is checked from a renamed worktree, bind its external identity explicitly without granting write access:

uv run --locked python scripts/reconcile_okf_repositories.py \
  --repo /path/to/renamed-worktree \
  --preset okf-uk-living \
  --strict

--preset is audit-only. The reconciler rejects it for installation or profile sync, and rejects any disagreement between the explicit preset, repository contract and physical repository identity.

Selective CPSV-AP 3.2.0 adoption

The Core Public Service Vocabulary Application Profile (CPSV-AP) 3.2.0 is the shared application profile for records that genuinely describe a public service, its competent authority, channel, cost, evidence or other input, output, requirement, rule, legal resource, location, life or business event, or dependency on another service. Version 3.2.0 is a SEMIC Recommendation, published on 6 May 2024; the maintained SEMIC repository identifies it as the current version at this policy date.

Adoption is selective because the repositories contain datasets, APIs, legislation, statistical products, research concepts and editorial journeys as well as public services. Reusing a CPSV-AP class or predicate does not turn the whole bundle into a CPSV-AP catalogue. It does not imply endorsement, certification or legal authority by the European Union, SEMIC, the UK Government or the source organisation. The implementation ledger below records delivery state; this matrix records the required design and must not be read as a claim that every mapping is already released.

Normative mapping boundaries

1. Apply cpsv:PublicService only when source evidence supports the resource as a public service. Keep the service, dataset, distribution, API, guidance, legal resource, statistical product and organisation as separate identified resources even when one record links them.
2. Generate only predicates whose source fields and mapping rules are declared in the producer's versioned predicate registry. Life and business events, competent authority, service dependency, eligibility, channel, requirement, evidence, output, cost and spatial availability must not be inferred from titles, Markdown links, page position or shared vocabulary.
3. Preserve the OKF relationship contract for every material CPSV-AP edge: stable assertion identity, direct/reified parity, local routes, absolute subject/predicate/object IRIs, labels, status, scope, authority, derivation, observation time, evidence and rights. A CPSV-AP term never weakens those provenance requirements.
4. Keep domain primacy explicit in the semantic model and predicate registry: DCAT 3 and DCAT-AP for data catalogues, datasets, distributions and data services; the ELI ontology for legislation; and the applicable SDMX standard and statistical model for official statistics. CPSV-AP links these resources to public services where evidence warrants it; it does not replace their native semantics.
5. Treat a competent-authority statement as a specific, evidence-bearing service relationship. It does not assert ownership of data, statutory jurisdiction, legal priority, endorsement, current operational availability or responsibility beyond the mapped source statement.
6. Resolve CPSV-AP only through reviewed local assets during a deterministic build. Each producer that emits CPSV-AP terms must pin the exact release, upstream tag and immutable commit/tree identity where available, file path, media type, byte size, SHA-256 digest, retrieval date, licence and official release URL. Pin the JSON-LD context, RDF vocabulary and any SHACL shapes actually used; do not fetch a mutable remote context at build or Reader time.
7. Record CPSV-AP 3.2.0 as the source vocabulary for each adopted class or predicate. A later release requires an explicit mapping review, regenerated artefacts and receipts, and producer/Reader regression tests; a namespace that happens to remain stable is not a version lock.

Validation and claims

The following evidence proves different things and must be reported separately:

• exhaustive validation against the shared JSON Schema proves that the generated OKF relationship rows satisfy the pinned relationship contract;
• direct/reified/runtime parity and digest receipts prove that the declared projections contain the same identified assertions;
• producer mapping checks prove the declared CPSV-AP subset was generated from the stated source fields and rules;
• running the official version-pinned CPSV-AP 3.2.0 SHACL shapes against the exact candidate graph can support a technical CPSV-AP conformance statement for that graph and validation scope; and
• factual, legal, policy, organisational and operational assurance still depends on source authority and specialist review.

A locally vendored context or vocabulary does not prove CPSV-AP conformance. Passing an OKF schema or a producer-specific subset of shapes must be labelled as subset validation, not full CPSV-AP conformance. Even an official SHACL report covers only the constraints encoded by the pinned shapes and the graph that was tested; it is not OWL inference, proof of factual truth, legal review, service availability, EU certification or endorsement. The candidate receipt must identify the graph digest, shape digest, validator and result counts so a Reader can distinguish an executed check from a proposed roadmap item.

CPSV-AP delivery tracking

The applicability matrix is now part of the shared authoring contract. Delivery still proceeds independently in dependency order:

Local implementation and release ledger

Completed locally means the authored controls, generators, generated working-tree artefacts and stated deterministic checks implement the migration. It does not mean the changes are committed, tagged, released, deployed or verified at a public URL. Those are deliberately separate columns and gates.

Standards status

The current YAML-LD 1.0 document is a W3C Working Draft, not a Recommendation. The profile uses its YAML-to-JSON-LD data-model approach while pinning the processor inputs needed for deterministic static publication. YAML comments, mapping order and anchor names never carry semantic meaning.