UK Legislation OKF

This is the architecture and data-model volume of the UK Legislation documentation spine. For task guidance use Getting started; for worked interfaces use the illustrated manual.

Public viewer

Open the UK Legislation OKF Explorer.

The canonical bundle descriptor is https://chris-page-gov.github.io/okf-uk-legislation/okf-explorer.json; the independently versioned source repository is https://github.com/chris-page-gov/okf-uk-legislation. It is an overview-first, chunked catalogue designed for browser navigation and agent progressive discovery. The checked-in work index is complete against the official Atom year facets at generation time; document subdivisions are complete on demand because the Explorer reads the selected work's authoritative CLML rather than freezing hundreds of millions of provision nodes into Git.

Work and search-result chunks use deterministic gzip files. The Explorer streams and decompresses only the requested chunks in the browser; manifests, facets, ontology pages and search shards remain directly inspectable. This keeps the complete publication within practical GitHub/Pages limits without dropping records.

The semantic publication is intentionally small. The root legislation publication has YAML-LD and JSON-LD semantic overview documents; the Whole-Law federation additionally publishes a Turtle projection. The 365,786-work operational corpus and its relationship assertions remain chunked JSON rather than being duplicated into one monolithic RDF file. Those JSON assertions are still machine-readable semantic data: they retain stable routes, predicates, authority, derivation and evidence, and an agent can traverse them through the published search and adjacency manifests.

The currently published artifacts are inconsistent: the operational Explorer descriptor identifies release 0.3.0, while the root YAML-LD and JSON-LD representations still identify bundle version 0.2.0. For this demonstration, agents should treat 0.3.0 as the operational release and identify the semantic representations as stale and not release-aligned; they must not silently combine the conflicting metadata. The root publication does not currently expose a Turtle document.

What “complete” means

The generator first reads the /all/data.feed facets, then retrieves every year with results-count=10000 and checks that each response count exactly equals the official year-facet count. It separately retrieves /draft/data.feed. Work IDs are deduplicated by the official /id/{type}/{year}/{number} identifier. The corpus validator requires at least 300,000 unique works and representative primary, secondary, devolved and EU-origin type codes.

For each selected work, the browser obtains the official application/xml manifestation and walks every recognized CLML structural element:

• preliminaries, Body and EUBody;
• Group, Part, Chapter, Division, Title, Section and Subsection containers;
• Pblock, PsubBlock, P1group-P3group and P1-P7 nested provisions;
• Schedules, Schedule, Appendix, Annex, Attachments and explanatory/signed sections.

Each node retains the CLML element name and ID, receives a normalized human type such as Section, Article, Regulation, Rule or Paragraph where the ID supports it, records number/title/text/extent/status, retains its parent/depth and links to the official selected passage. This is progressive completeness: discovery metadata is local; authoritative text is fetched only for the work being researched.

Ontology decision

No single vocabulary covers identity, versions, manifestations, subdivisions and legal effects well enough. The pack uses a layered model:

ELI is the primary semantic spine. Schema.org is a compatibility layer, not a replacement for ELI or CLML. CLML is authoritative for UK subdivision shape. The official ELI-to-Schema.org mapping informs the crosswalk.

Normalized categories, types and topics

Official type codes are retained. They are also grouped into primary, secondary, draft, eu-origin and other, with separate jurisdiction and document-type facets. This preserves Church Measures, local/private Acts, old Parliament material, ministerial directions and other uncommon families rather than forcing them into a misleading primary/secondary binary.

Topics are a deterministic title-only discovery aid across constitutional, civil, criminal, employment, tax, company, land, environment, health, education, family, immigration, welfare, transport, data, consumer, local-government, election, defence, equality, intellectual-property, professional-regulation and EU themes. They are explicitly labelled non-authoritative. An agent must never treat a topic assignment as a legal proposition.

The complete work catalogue now emits provenance-bearing classified as, has document type and conservative mentions entity relationships. A governed model-assisted rule file proposes only high-precision literal title matches; accepted rules are applied deterministically to every work and remain labelled derived and non-official. Route-scoped FNV-1a adjacency shards let the Explorer load the selected work's relationships without hydrating the corpus-wide edge table. The model runner records prompt version, model, review state, token usage and cost. Its first direct API attempt was rejected for project quota before output, so the current accepted rules were supplied by the Codex session and the recorded API cost is $0.00.

Facet values are navigation indexes, not automatically relationship nodes. For example, Scotland has an exact snapshot-bound posting of 13,270 works, but the label means “territorial publication context inferred from the official type code”; it is not provision-level legal extent or applicability. Explorer therefore shows a bounded membership preview and derived membership graph for that card. Selecting a legal work then loads the work's route-scoped adjacency.

The current route resolver combines the core adjacency with governed model-assisted enrichment available for the selected work. Official-effects assertions are present in the release-wide effect datapack and reconciliation evidence, but are not yet indexed by both source and target work route. This is a declared publication limitation; the selected-work card must not be described as the complete combined 906,754-assertion graph.

Official access methods

Every record carries the URLs available from its Atom entry and documents the wider interfaces:

• website and stable identifier URIs;
• Atom search/browse feeds, including official full-text search;
• CLML/XML, Akoma Ntoso XML, HTML/XHTML, PDF and RDF manifestations where supplied;
• content negotiation and linked-data URIs;
• table-of-contents and publication-log feeds;
• changes made and changes received feeds for legal effects;
• point-in-time/version and extent controls exposed by legislation.gov.uk;
• bulk and SPARQL surfaces documented by the Legislation Research service.

At the 2026-07-10 generation checkpoint, the advertised Research bulk downloads and SPARQL endpoint returned HTTP 401 with a “By Invitation Only” authentication challenge to an anonymous client, even though their documentation describes public access. The pack records this unresolved live-access conflict and uses the working public Atom/CLML interfaces. It does not silently claim that the restricted surfaces were harvested.

The builder identifies itself, caches every response, retries transient server errors and starts requests conservatively under the official fair-use guidance. Source response hashes, byte counts and cache status are written into provenance metadata.

Agent workflow for counsel-grade answers

1. Read the descriptor, overview, counts and notices; do not hydrate the whole corpus.
2. Narrow by category, type, year, jurisdiction, legal status and topic.
3. Search locally for titles and let the Explorer add official remote full-text matches.
4. Select the work and load its official CLML subdivision tree.
5. Identify the exact Part/section/article/regulation/schedule nodes and open their official passage links.
6. Check the displayed version, commencement, extent and changes made/received before drawing a conclusion.
7. Build an answer as discrete propositions. For each proposition record source title, direct passage URL, supporting passage, version and retrieval date.
8. Separate statutory text, inference, missing facts and any need for case law or other authority. This pack is legislation-complete, not a case-law database and not legal advice.

An answer that cites only an Act landing page is not provenance-complete. A direct passage link and supporting passage are required for every material proposition.

Evaluation

evaluation/legislation/questions.json contains 100 questions across 25 authorities and four common research modes: rule extraction, application, temporal/currency analysis and counsel-style synthesis. The 100-point rubric weights substantive correctness, authoritative sourcing, proposition provenance, pinpoint passages, temporal/jurisdictional context, completeness/uncertainty and clarity.

Automated checks cover evidence structure and observable source properties. Expert review supplies the legal judgment that an automated keyword score cannot. Missing official citations, missing proposition ledgers, uncited propositions or failure to cite the expected passage cap an answer below 50.

Rebuild and validate

uv run --locked python scripts/build_legislation_okf.py --refresh
uv run --locked python scripts/check_legislation_okf.py
uv run --locked python scripts/build_legislation_evaluation.py
cd apps/okf-explorer && pnpm test && pnpm check && pnpm build
cd ../.. && uv run --locked python scripts/build_site.py

The source cache under tmp/legislation-okf-source/ is intentionally untracked. The generated legislation/ pack is checked in so Pages deployment and review do not depend on live upstream availability.