Parsing Associated Documents at The National Archives

Legislation rarely travels alone. Alongside an Act or a statutory instrument sit associated documents: explanatory notes, impact assessments, and similar material that helps people make sense of the law. To publish them well, they had to flow through the same structured pipeline as the legislation itself. Getting there meant solving three problems in order: the messy input, the conversion, and the rendering.

The input was inconsistent

The source material came in two shapes. Some documents arrived already structured, with markup I could rely on. Many did not. They were unstructured Word files and PDFs where the meaning lived in visual layout rather than in tags: a heading was just bold text, a list was just indented lines.

The first job was to read both kinds the same way. For the structured documents I could map existing elements directly. For the unstructured ones I had to infer the structure: detect headings, paragraphs, lists, and references from the cues that a human reader uses, and rebuild that hierarchy explicitly.

Converting to Akoma Ntoso

The target was Akoma Ntoso (AKN), the XML standard for legislative documents. The point of converting everything to AKN is that the rest of the pipeline never has to care where a document came from. One representation, one set of rules downstream.

So whatever the source, the output was the same: a consistent AKN tree with the document's real structure expressed in the markup rather than implied by its formatting.

Sourcing reliable metadata and adding semantics

Structure alone is not enough. Each document needs trustworthy metadata: its title, dates, identifiers, and its relationship to the parent legislation it explains. Pulling this from the body of the document is fragile, so I sourced it from authoritative records instead, and reconciled it against the document rather than trusting either blindly.

On top of that I added semantics: marking up references, defined terms, and the links that tie an associated document back to the specific provisions it relates to. That is what turns a converted document into something queryable and navigable rather than just a tidier blob of text.

Rendering with a single XSLT

With every document in AKN, presentation became one problem instead of many. I wrote an XSLT that transforms the AKN into HTML, so all associated documents render through a single, consistent path. Fix the rendering once and every document benefits; add a new document and it inherits the same accessible, predictable output for free.

Takeaway

The win was not any one of these steps but the shape of the whole: collapse varied, unreliable input into one trustworthy structured representation as early as possible, and everything after it gets simpler.