OKF Authoring Profile v1

Status: experimental production profile, 29 July 2026.

This profile defines the bounded handoff between domain research and an OKF bundle build. It exists so a builder can reuse domain decisions without receiving an enormous research transcript or silently inventing missing semantics.

The profile URI is:

https://chris-page-gov.github.io/okf-explorer/profile/authoring/v1/

Its machine contract is domain-profile.schema.json. A complete, schema-valid example is domain-profile.template.yaml.

What This Profile Is

An okf-domain-profile.v1 document is a research and control artefact. It freezes:

• purpose, scope, exclusions and any completeness denominator;
• repository classification, bootstrap evidence, initialisation-only commit policy, source/generated boundaries, CI state and clean-work handoff;
• source, semantic, operational and decision authority;
• the collection's document families, representations, formats, languages, extraction constraints and sensitivity findings;
• material research claims with separate claim, workflow, derivation, authority, confidence and evidence fields;
• source access, rights, privacy, freshness and acquisition evidence;
• user roles, tasks, evidence needs and hard failures;
• source-native terminology, entities, identifiers, versions and relationships;
• useful external-link coverage against declared eligible-entity denominators;
• a human-readable presentation contract and compact label index for every graph-reachable entity;
• a snapshot-bound Explore OKF publication state, persistent banner and route-preserving feedback contract;
• the exact standards selected for the domain and how each will be tested;
• the smallest justified OKF/Explorer publication architecture;
• the exact downstream consumers, their executable package/version/commit/lock identity and the producer-to-plane-to-consumer impact graph;
• a two-stage tiny-fixture protocol that validates producer bytes first and then executes the actual locked consumers;
• per-plane digest roots, invalidation triggers and selective-rerun closure;
• backward and forward producer/consumer compatibility expectations;
• the explicit producer/consumer compatibility window and unsupported-input behaviour;
• post-deploy deep links whose bundle identity and restored state must be checked;
• validation, evaluation, unresolved gaps and owner decisions; and
• traceability from intended outcomes to planned artefacts and checks.

It is not the knowledge graph, an ontology, a licence decision, or evidence that the eventual bundle passed its release gates.

Fixed Interoperability Floor

All builds retain the permissive OKF v0.2 core. The Foundry production profile normally adds stable identity, provenance, rights/access, coverage, lifecycle, freshness, traceability, deterministic generation and evaluation, but these additions must not be described as requirements of OKF core.

When semantic publication is justified, use:

• YAML 1.2.2 and the exact dated YAML-LD 1.0 Working Draft selected during warm-up;
• JSON-LD 1.1, its API and framing specifications where applicable;
• RDF 1.1 and RDF Dataset Canonicalization 1.0 for semantic digests;
• pinned, allowlisted contexts;
• JSON Schema 2020-12 for control and projection documents; and
• SHACL for closed-world RDF publication checks.

YAML-LD is a Working Draft, not a W3C Recommendation. A build must record the exact official publication it tested. It must not copy a prompt's old "latest" date.

Standards Applicability

Every candidate standard receives exactly one applicability decision:

Similar field names are not conformance. A standard marked normative must name the exact version, conformance artefact and validator/test suite.

Orthogonal Evidence Axes

Do not overload one status or one score. Record independently:

• source/assertion authority;
• derivation (source-native, normalized, rule-derived, model-assisted, or expert-asserted);
• OKF verification trust;
• research-claim status;
• freshness;
• source availability;
• coverage against a named denominator;
• concept lifecycle; and
• release lifecycle.

Confidence cannot upgrade authority. A numeric confidence value is meaningful only when a calibration method and evidence are declared.

Change And Build Rules

• Hash-lock an approved domain profile and its evidence register.
• For an empty or imported target, run uv run --locked python scripts/okf_repository_bootstrap.py TARGET as a dry run before --apply. Non-empty and dirty targets require --adopt-existing; existing files are preserved and the tool never initializes Git, creates remotes, commits, enables CI, pushes or publishes.
• Pin every release-relevant consumer to an exact release, commit, binary, container or dependency-lock digest in one checksummed consumer lock.
• Maintain an explicit dependency graph from producer and input through each digest plane, consumer and public route. Every edge names its change impact and validation closure.
• A builder consumes that exact profile; it does not rewrite it.
• Only unresolved decisions explicitly marked blocking_for_build: true prevent the smallest viable build.
• A semantic scope or standards change requires a new profile version or a recorded decision override.
• Non-blocking uncertainty becomes a visible gap or constraint, not an invented value.
• Begin every implementation with a two-stage tiny fixture. Stage 1 builds and validates positive, negative, stale, unavailable, conflicting, unsafe and digest-mismatch cases twice. Stage 2 executes every required locked consumer against those exact bytes; schema-only or mocked substitutes do not close the consumer gate.
• Give control, data, search, semantic, presentation and release planes their own applicable digest roots. Rerun only the transitive impacted planes and consumers proven by the graph; a timestamp or an assertion that a change is harmless is not reuse evidence.
• Test compatibility in both directions: new producer output with every supported consumer, and retained supported producer fixtures with the new consumer.
• Freeze and assure one release candidate, then promote identical bytes.
• After deployment, open the exact public overview, record, search/filter and other selected deep links in the actual consumer. Verify bundle identity, snapshot, restored view/state, expected content and applicable plane roots; HTTP 200 alone is insufficient.
• Withhold every public bundle URL until that exact deployed URL passes the browser identity and journey check. Give the check 60 seconds tool-first, report failures immediately, label an unverified link explicitly and limit correction to the dependency-graph closure instead of rebuilding silently.

Consumer Contract

consumer_contract remains optional. A profile that otherwise satisfies the current v1 schema may omit it; new or materially revised Foundry profiles should populate it from the public template. It contains:

• inventory, lock and exact consumer executable_identity;
• dependency_graph;
• fixture_protocol.producer_stage and consumer_stage;
• independently rooted planes;
• a compatibility-window decision and two-direction compatibility cases; and
• post_deploy_deep_links.

An approved profile that uses this contract must have a real consumer-lock SHA-256. The semantic validator also checks lock/inventory equivalence, consumer and plane references, required-consumer execution, both compatibility directions and deep-link coverage.

Required Explore OKF Controls

Every conforming okf-domain-profile.v1 document includes semantic_linking, presentation_contract and exploratory_publication. They are required at the research handoff so a build cannot postpone citizen readability, evidenced external linking or honest exploratory status until release review:

• semantic_linking measures justified external links against eligible entity denominators rather than rewarding raw triple count;
• presentation_contract prevents stable identifiers from leaking into citizen-facing labels and requires a compact label index at relationship projection granularity; and
• exploratory_publication defines a visibly incomplete, immutable learning snapshot that can receive route-preserving feedback before candidate freeze.

Each semantic link set names one eligible-entity denominator and carries an evidence-backed coverage result. The denominator binds its deterministic eligibility rule and canonical, sorted candidate-ID digest to the frozen input snapshot and evidence register; approved profiles cannot use an unknown input or candidate digest. The eligible candidates are partitioned by exact IDs into mutually exclusive linked, unresolved, excluded and conflicting outcomes. Their union must equal the denominator exactly. Achieved coverage is the linked count divided by the eligible count minus evidenced exclusions (or 100 per cent when that effective denominator is empty), rounded to two decimal places. Every exclusion result names its declared rule, lists the stable unique identifiers of the exact candidates removed and cites evidence; its count must equal that list, every ID must occur in the denominator's exact candidate list, and a candidate cannot occur in two exclusion results. The denominator's eligible count must itself equal its unique candidate-ID list. The profile separately counts linked candidates and link assertions, because one candidate can have several justified links. An identity-bearing assertion ledger must cover every linked candidate and no other outcome. Every assertion has one identity-bound dereference result; assertion, attempt, success and failure counts are derived from those ledgers rather than trusted as free aggregates.

This is deliberately a declared-inventory guarantee, not an open-world proof. The validator proves that the author-declared candidate IDs, snapshot, digest, outcomes, assertions and evidence reconcile. It cannot discover an entity that the eligibility rule wrongly omitted. Before approval, a domain reviewer or owner must therefore assess the rule against the frozen source snapshot and record support-checked, digest-bound evidence for that boundary.

Mapping strength and predicate are one governed decision. SKOS mapping relations require their corresponding SKOS predicate; identity requires owl:sameAs plus independently verified, digest-bound assertion evidence; and a domain relationship cannot conceal an identity or SKOS mapping predicate. Each target must belong to the declared HTTP namespace under URI-aware origin and path/hash rules; percent-encoded path delimiters cannot be used to manufacture namespace membership. Duplicate candidate-target assertions are rejected rather than counted twice.

The result records its observation time, structured maximum-age policy, freshness status and evidence references. Freshness is calculated deterministically against the profile's prepared_at clock, rather than the validator's wall clock. The v1 freshness policy is fail-closed: an approved profile cannot rely on a stale result. Every semantic ledger reference in an approved profile must resolve to support-checked or independently verified, digest-bound evidence. coverage_result_sha256 commits the complete result as canonical UTF-8 JSON while retaining ledger array order. One approval-grade evidence item must carry that exact digest and the result's exact observation time; separate or unrelated witnesses do not satisfy approval. Dereference outcomes are derived from a machine-readable terminal kind and HTTP status, not from descriptive text. An approved profile must also meet every declared minimum coverage percentage. These controls prevent an unexplained aggregate “semantic completeness” score from concealing unresolved or stale link work.

Explorer v0.7.0 implements these behaviours through the strict Explore OKF profile. The actual pinned consumer must still pass the profile's endpoint-label and exploratory-banner journeys before a particular public snapshot claims Explore OKF conformance; declaring the profile fields alone is not evidence of a successful journey.

The Explorer package exposes the generic actual-consumer command:

pnpm --dir apps/okf-explorer acceptance:bundle -- \
  --bundle-root /path/to/bundle \
  --journeys /path/to/journeys.json \
  --output /path/to/external-runtime-acceptance.json

The receipt binds the Explorer source commit and dirty state, dependency lock, runner, deterministic build manifest, bundle tree and descriptor identity to the journey manifest, requests, console/page errors, restored URL state and terminal outcome.

The copy-ready prompts and complete workflow are in the OKF Foundry prompt kit.