OpenRegs — Glossary

Definitions of the terms used across the spec, the code and the docs. Terms are grouped by theme; each definition is one to three sentences. Read this alongside OVERVIEW.md.

Legal document standards

Akoma Ntoso

An OASIS XML standard for representing parliamentary, legislative and judicial documents, abbreviated AKN. OpenRegs normalizes every ingested legal text into AKN so that downstream planes see one structure regardless of the publisher’s native format. The vendored schema lives in spec/xsd/.

FRBR

Functional Requirements for Bibliographic Records: a four-level model — Work, Expression, Manifestation, Item — that Akoma Ntoso adopts for identifying legal documents. It is what lets OpenRegs distinguish “Regulation 2024/1” as an abstract act from “Regulation 2024/1 as it read on 2025-06-01, in English, as XML”.

Work

The FRBR level of the abstract legal act itself, independent of any version or wording — for example the fixture regulation at Work IRI /akn/eu/act/reg/2024/1. A Work persists across every amendment made to it.

Expression

The FRBR level of a specific version of a Work: its text in a particular language at a particular point in time. Consolidation produces Expressions; an as-of query resolves a date to the Expression in force on that date.

Manifestation

The FRBR level of a concrete serialization of an Expression — the AKN XML file, the HTML rendering, the PDF. Two Manifestations of the same Expression carry the same legal content in different formats.

eId

The stable element identifier attached to a structural node in an Akoma Ntoso document, such as art_5__para_2. eIds are the addressing scheme for citations and provenance, and they are permanent: an eId is never reused for a different element.

Publishers and source formats

CELEX

The identifier system used by EUR-Lex for EU legal documents, e.g. 32024R0001 for the fixture regulation. The characters encode sector, year, document type and number, which makes CELEX the natural primary key for EU sources.

Formex

The XML format in which the Publications Office of the EU distributes the Official Journal and EUR-Lex content. OpenRegs’ EU adapter parses Formex and maps it to Akoma Ntoso.

CLML

Crown Legislation Markup Language, the XML schema used by legislation.gov.uk for UK statutes and statutory instruments. The UK adapter parses CLML and maps it to Akoma Ntoso.

eCFR

The Electronic Code of Federal Regulations, the continuously updated online edition of the US CFR, published with a point-in-time API and XML downloads. It is the source of consolidated US rule text in OpenRegs.

Federal Register

The daily journal of the US federal government, which publishes proposed and final rules before they are incorporated into the CFR. OpenRegs watches it for amendment events whose effective dates drive US consolidation.

WARC

Web ARChive, the ISO container format for storing HTTP requests and responses verbatim. Every capture the fetcher makes — whatever the source format — is recorded as a WARC 1.1 record, so the snapshot preserves the request line, both sets of headers, the payload and the capture timestamp exactly as they occurred.

Storage and provenance

Content-addressed storage

A store in which an object’s key is a cryptographic digest of its bytes — here, sha256. Identical bytes therefore store once and cannot be silently altered, which is what makes the snapshot store a trustworthy evidence base for replay and audit.

Provenance span

A character-offset range (char_start, char_end) into a specific source text, attached to an atom or other derived record, together with the quoted_text it selects. CI enforces that quoted_text == source_text[char_start:char_end] byte-for-byte, so a derived claim can always be checked against the text it came from.

SLSA provenance

A signed attestation, following the SLSA (Supply-chain Levels for Software Artifacts) framework, describing how an artifact was built: the builder, the source commit and the inputs. OpenRegs attaches SLSA provenance to release artifacts so a consumer can verify not just what they downloaded but how it was produced.

cosign

The Sigstore command-line tool for signing and verifying artifacts and attestations, invoked by OpenRegs as a subprocess. Every release artifact is cosign-signed, and pull and serve verify those signatures before using a release.

Modelling regulation

Obligation atom

A small YAML record capturing one normative statement extracted from a legal text: the actor, the modality (MUST / SHOULD / MAY), the action, any conditions and exceptions, plus a provenance span back to the source. Atoms are proposed by an LLM and merged only after human review; ids such as FIXREG-Art5.2-Ob1 are permanent.

Consolidation

The process of applying an amending act’s instructions to a base act to produce the text as it reads from a given date — the point-in-time or “consolidated” version. Regulators publish base and amending acts separately; consolidation is what makes “what did this say on 2025-01-15?” answerable.

Derogation

A provision that exempts a class of actors or situations from an obligation that would otherwise apply, or relaxes it for them. In the fixture corpus, Article 9 derogates Article 5(2) for small operators, so any correct answer about the register obligation must surface that exception.

Bitemporal (valid time vs transaction time)

A data model carrying two independent time axes. Valid time is when a fact was true in the world — when a rule was in force; transaction time is when OpenRegs recorded it. Both axes are needed to answer what a rule said on a given date and, separately, what OpenRegs believed it said when a past compliance check ran — the second being what an auditor asks about a past decision.

Releases and consumption

Diff manifest

A release artifact listing atom-level changes between two releases: atoms added, removed, or changed, with the substantive/editorial classification and the amending instrument responsible. It is what lets a consumer review only what actually moved between two dates.

controls.yaml

The downstream mapping file in which an organisation declares which of its internal controls satisfy which OpenRegs obligation atoms, by atom id. CI tooling reads it to report coverage and to fail a build when a mapped atom changes or is deprecated.

Retrieval closure

The set of documents and atoms that must be retrieved together for an answer about a given provision to be complete — the provision itself plus its defined terms, internal cross-references, derogations and amendments. Serving computes the retrieval closure rather than returning an isolated article, because an article read without its derogations is misleading.

MCP

The Model Context Protocol, an open standard for exposing tools and data to AI agents over a uniform interface. OpenRegs ships an MCP server alongside its REST API, sharing one codebase, so a copilot can query a pinned release with citations.