Review Of The OKF Authoring Methodology

Status: reviewed and implemented in OKF Explorer v0.7.0, 12 August 2026.

This review uses the completed HM Land Registry v0.3.0 delivery retrospective and its public Explorer presentation as evidence. It does not reopen, alter or rebuild the Land Registry pack. Its purpose is to improve the reusable OKF authoring method before reviewing okf-uk-living.

Decision In Brief

The previous Foundry method was strong at identity, provenance, deterministic generation, evidence and release assurance. It was not strong enough at three earlier questions:

1. Can a citizen understand every entity and relationship that a view exposes?
2. Does each semantic link answer an evidenced question, and are all eligible external links measured against a declared denominator?
3. Can a small, explicitly exploratory result be shared early enough to find those failures before a release candidate is expensive to change?

The revised method therefore adds a citizen-first Explore OKF stage between domain warm-up and release-candidate construction. It separates stable machine identity from human labels, treats useful link coverage as a governed measure, and makes an exploratory banner and feedback route part of the publication contract.

What The Land Registry Evidence Shows

The public probate graph exposed internal identifiers such as publisher-6b13…, source-3b1…, activity-242… and rights-760… as visible names. Those identifiers are legitimate machine keys. They are poor labels for a person trying to understand who publishes a service, where evidence came from or what a rights statement means.

This is not one isolated drawing problem:

• opaque identifiers appeared in graph nodes, relationship rows and publisher facets;
• readable titles existed for several referenced entities, but were not guaranteed to be available to every lazy-loaded presentation path;
• at least one activity entity had an identifier and time but no useful human name;
• structural and provenance relationships were plentiful, but the public view did not first establish which relationships helped a citizen complete a task; and
• the release process found presentation defects after semantic generation and candidate assurance had already become expensive.

The retrospective records the broader process pattern: governance review, real-consumer tests and release-platform constraints were allowed to arrive after candidate generation. The label failure has the same shape. A builder and schema can agree that an endpoint exists while the real reader still has no usable name for it.

Allocation Of Responsibility

The correction must not be assigned wholly to either a producer or the Explorer.

A producer must not assume that a later UI can invent a label. The Explorer must not assume that a raw identifier is an acceptable label merely because a producer omitted one.

Assessment Of The Current Method

What Should Be Retained

• source-native identifiers remain unchanged and distinct from local routes;
• absolute semantic IRIs and Explorer routes remain separate identities;
• relationship predicates, direction, evidence, authority and derivation stay explicit;
• YAML-LD is the authored semantic boundary and generated JSON-LD/RDF/Explorer forms must remain equivalent;
• standards applicability, source rights, privacy, freshness and completeness denominators remain independent decisions;
• the actual pinned consumer is tested, not merely a resembling schema; and
• one frozen candidate is promoted byte-for-byte after assurance.

What Was Under-Specified

The profile required labels for entity types and relationship types, but did not require a readable label for every graph-reachable entity instance. It did not say whether labels had to be available before full record hydration, which allowed a lazy reader to fall back to identifiers.

The method encouraged stable predicate IRIs and standards reuse, but did not define semantic-link eligibility or coverage. “More relationships” could therefore reward internal processing and provenance edges without proving that public, dereferenceable links helped a recorded citizen task.

The method went from tiny fixture to full deterministic build and release assurance without a named, shareable learning stage. A tiny fixture tested contracts, but it was not framed as a public, route-preserving artefact for owner and user feedback.

What Must Not Become The New Mistake

“Maximise semantic linking” must not mean maximising the raw number of triples. An unjustified owl:sameAs, a relationship inferred from similar wording or ten duplicated provenance projections can make a graph larger and less true.

The target is maximum evidenced, useful link coverage:

For every eligible entity and competency question, publish the strongest justified stable link, state its mapping strength and authority, and count every eligible but unresolved case.

The denominator is therefore essential. A pack should be able to say, for example, that all 12 eligible local-authority entities have an official ONS code/IRI, while two of 18 service concepts still lack an evidenced mapping.

Revised Authoring Principles

1. Separate Identity, Label And Description

Every graph-reachable entity has three different properties:

• a stable IRI or source identifier for machines;
• a concise preferred label for ordinary presentation; and
• an optional description that explains the entity in context.

Changing a label must not change the identifier. An identifier may appear in Inspect or debugging views, but it is not a normal display fallback. Labels use en-GB unless a source or user need requires another language; source labels and editorial display labels remain distinguishable.

Recommended display priority:

1. reviewed source-native preferred label;
2. reviewed domain-profile preferred label;
3. deterministic, explicitly labelled editorial display label;
4. a visible Missing label defect with the identifier available in Inspect.

The fourth outcome is deliberately conspicuous. Silently rendering a hash would hide a quality failure.

2. Make Labels Available At The Same Granularity As Links

Every relationship endpoint in a shard carries, or can resolve through a compact snapshot-bound index to:

• route and absolute IRI;
• preferred label and language;
• entity type label;
• label authority/derivation; and
• the same snapshot and integrity root as the relationship.

The reader must not need to download an entire publisher, source, rights or activity corpus merely to name a visible node. The build fails when a graph-reachable route has no label-index entry.

3. Start From Citizen Competency Questions

Before adding a relationship, name the question it answers. For example:

• Which public body provides this service?
• Which life event may lead someone to need it?
• What place does it cover?
• What eligibility rule or legal basis applies?
• Which official dataset supplies this fact?
• What can a person do next?

System provenance remains important, but it should be a separately selectable evidence layer rather than the main citizen story.

4. Use A Linkability Ladder

Each eligible entity is assessed against the following ladder:

Higher is not always possible. An unresolved Level 3 entity is safer than a false Level 4 identity assertion.

5. Reuse Vocabulary Terms And Other People's IRIs Carefully

Follow W3C Data on the Web Best Practices: use stable URIs, reuse standard vocabularies and other publishers' identifiers where appropriate, assess coverage and provide human as well as machine presentations.

Use SKOS mappings for concepts: exactMatch, closeMatch, broadMatch, narrowMatch or relatedMatch as evidence permits. owl:sameAs is reserved for identity of individuals and must never be inferred from a matching label or URL.

For citizen-facing public services, assess the current Core Public Service Vocabulary Application Profile as a projection. Editorial life stages are navigation concepts, not public services merely because they link to one.

6. Measure Coverage By Entity Class And Link Purpose

Record for each link set:

• eligible entity rule, exact candidate-ID inventory, frozen source snapshot, canonical inventory digest and evidence;
• linked-candidate, link-assertion, unresolved, excluded and conflicting counts;
• target namespace and authority;
• relationship or mapping predicate;
• minimum evidence;
• public dereference successes and failures;
• task/competency references; and
• observed date, freshness policy and calculated freshness status.

Treat those four candidate outcomes as an identity-bound partition: their exact ID sets are disjoint and their union must equal the eligible inventory. The inventory itself is derived by the declared deterministic eligibility rule, bound to the frozen input snapshot and evidence, and protected by a canonical sorted-list digest; approved profiles fail when any of those bindings is unknown. Calculate achieved coverage as linked divided by eligible minus evidenced exclusions, and retain every category beside the percentage. Do not allow exclusions to inflate the score anonymously: each exclusion result must cite a named rule and evidence, list the stable unique identifiers of the exact excluded candidates, equal its declared count and remain disjoint from every other exclusion result. Every excluded ID must belong to the denominator's exact unique candidate-ID list, whose length must equal the eligible count. Count link assertions separately when a candidate has more than one. Record stable assertion IDs, require the assertion ledger to cover every linked candidate and bind exactly one success-or-failure dereference result to each assertion. Reconcile all counts from these identity-bearing ledgers, bind the observation to evidence and calculate freshness against the profile's declared clock. The v1 contract fails closed when an approved profile's result is stale. Never publish one unexplained “semantic completeness” score.

The validator's completeness claim stops at the declared inventory. It proves that the frozen candidate IDs, digest, four outcomes, assertion ledger and evidence reconcile; it cannot prove that the author's eligibility rule found every entity that should exist in the domain. Approval therefore includes a recorded owner or domain-review judgement that compares the deterministic rule with the frozen source snapshot and its support-checked, digest-bound evidence.

Make the predicate agree with the mapping strength: use the corresponding SKOS predicate for each SKOS mapping, and use owl:sameAs only for identity backed by independently verified, digest-bound assertion evidence. A domain relationship cannot use an identity or SKOS mapping predicate. Validate every assertion target against its governed HTTP namespace using URI origin and path/hash semantics without decoding an encoded slash into a false child path, reject duplicate candidate-target assertions, and bind all semantic ledger evidence at approval grade. Canonically hash the complete coverage result, retaining ledger order, and require one approval-grade receipt to carry both that exact digest and observed_at. Derive dereference success or failure from the machine-readable terminal result rather than human prose.

7. Test Readability As A Contract

The two-stage fixture and full-corpus acceptance must check:

• no visible default label matches configured opaque-ID patterns;
• every endpoint is named in Graph, Links, Facets, Type, Timeline, Resources, Map and Narrative wherever it appears;
• labels remain meaningful at ordinary viewport sizes and zoom levels;
• relationship labels read naturally in both directions;
• semantic and metadata projections do not create unexplained duplicate edges;
• the identifier, IRI, evidence and derivation remain available through inspection; and
• a novice can answer the selected citizen questions without interpreting internal repository vocabulary.

Counts alone do not pass this gate.

The Explore OKF Stage

Explore OKF is an intermediate learning publication. It is not an OKF release status and does not imply that the source, model, completeness or service has been approved.

domain warm-up → tiny fixture → Explore OKF → reviewed candidate → assured RC → publication

Entry Criteria

• a bounded source snapshot or synthetic fixture is identified;
• rights, privacy and security permit the selected material to be shared;
• the actual Explorer loads the selected functionality;
• preliminary entity, label and link registers validate;
• known gaps and unreviewed mappings are explicit; and
• a stable feedback route is available.

Required Banner

Every Explorer view displays a banner such as:

Exploratory — This is an incomplete research view, not an authoritative service or released data product. Content and links may change. Check the cited official source before making a decision. Give feedback.

The banner follows the usability intent of the GOV.UK phase banner but does not claim that the independent OKF project is a government service. It remains visible on every view, preserves the current route in the feedback link and is exposed in the machine descriptor.

If a producer publishes a companion human landing page for the same exploratory snapshot, that producer must show the equivalent warning there as well. Explorer v0.7.0 enforces the banner inside Explorer; it cannot inject UI into independently hosted producer pages.

Machine Contract

The exploratory descriptor records:

• publication_state: exploratory;
• snapshot ID, generated time and applicable plane roots;
• owner/publisher and authority status;
• banner label, message and feedback URL;
• explicit limitations and incomplete denominators;
• indexing decision, normally noindex until owner review;
• permitted and prohibited claims; and
• the rule for promotion to a fresh candidate.

Shared exploratory snapshots are immutable enough to discuss: a link must keep identifying the bytes and state that a reviewer saw. A new iteration receives a new snapshot identity. It may reuse unaffected planes through the dependency graph, but it does not overwrite the evidence for an earlier review.

Exit Criteria

Exploration ends when the owner either:

• approves a versioned domain-profile change and authorises a fresh candidate;
• requests another bounded exploration iteration; or
• closes the experiment with findings and no publication.

Exploratory bytes are never silently relabelled as a release candidate.

Acceptance Before okf-uk-living

Before the okf-uk-living review begins, the methodology should demonstrate:

1. a tiny cross-source citizen journey with no opaque visible labels;
2. link coverage denominators for people-facing services, organisations, places and concepts;
3. evidence-backed CPSV-AP and SKOS projections without false identity;
4. a compact label index that works under lazy loading;
5. an exploratory descriptor and route-preserving feedback banner;
6. actual-Explorer tests across all relevant views; and
7. a review decision that can change the model without starting a release rebuild.

The recommended data and pilot are in Open data for the Explore OKF pilot.

Implemented Boundary

The review now has matching producer and consumer contracts. The normative Explore OKF profile defines the compact endpoint-label index and exploratory-publication descriptor; the Python tooling builds and validates both against the bundle snapshot and integrity envelope.

OKF Explorer v0.7.0 consumes those contracts. Graph, Links, Facets and other route-based labels use the governed compact index without hydrating the full record, display Missing label instead of leaking an opaque generated identifier, and retain the route, IRI, type and label authority in Inspect. Every view also retains a validated exploratory banner and route-preserving feedback link. A malformed, unsupported or mismatched exploratory contract is shown as an explicit warning and is forced to noindex; it is never silently treated as a conforming exploratory publication.

This implementation closes issue #94 and issue #95. It does not make an existing producer conform automatically: each producer must emit the two snapshot-bound documents, pass actual-consumer journeys and preserve the exploratory limitations in its public descriptor.