A love letter to the Parliamentary Counsel of the world.

Dear Parliamentary Counsel of the world,

While most of my friends just see that Amorphous Blob they call “the government”, to me you’re that spectacular but quiet group in the corner, nerding out on drafting, maintaining and publishing our laws and other legal instruments. I have to admit: you just keep catching my attention, and I adore your work.

So I’m writing you this letter to express my love for what you do and in the hope of maybe getting to know you and collaborating on some things together. I’ve been spending a lot of time with your creations and I’m placing my hope in appealing to your passion for precision and accuracy. I see you incorporating technology in your work and I know you want to do so pragmatically and thoughtfully, this letter is about a little addition that I hope you can consider. Please excuse my extensively informal language; this is a love letter after all.

The letter comes with a special gift I made you. Currently, it’s a Christmas holiday project to say, “look how cool this would be”. But it also includes a suite of examples to illustrate what it enables.

Please don’t take any part of this letter as criticism - I appreciate you’re super busy, and what I’ve done is only possible because of the care and the foundational work you’ve put in.

I confess I’m also not just writing to you. I hope to get more people talking about how we can empower wider civic engagement with your creations; especially for those who only see that Amorphous Blob. I’m tackling this by finding ways to help people overcome that unassailable learning curve caused by the complexity and size of legal instruments. Public policy has only become more complex over the last 300 years, and that exacerbates the disconnect between the law and our communities.

This is a somewhat personal endeavour. I’m losing friends to this rise in conspiracy theories sweeping through our communities. For them, it appears easier to accept “government” as an Amorphous Blob that only seeks to control them, rather than the ongoing historic struggle of law to create complex systems that try and balance power and well-being. Sovereign citizen style conspiracies show this disconnect, which is fueled by the seemingly impenetrable nature of how our law is developed.

If democratic systems and the rule of law are going to continue to fight inevitable institutional decay, then we need to revitalise these systems in ways that serve our communities, including by redistributing access to those systems. Our legal, political and environmental systems are facing massive stress, and they have to change if we want them to continue moving towards healthy communities and a healthy planet.

So my proposal (which in itself is quite modest) includes a special fully-functional gift, which I’ll use to illustrate the much more significant outcomes the following modest proposal enables.

I would love it very much if you would publish your legislation with granular referencing to incorporate in computer systems.

That’s it. We’ve had referencing for humans built into law for a long time, and you know how useful that is. I’d like this to complement that system and run parallel to it. Let’s take a little tour of this gift I’ve made for you to illustrate what my simple proposition would enable.

Why do computer systems need references? Because computer systems are really good at modelling complex things. We use them to model houses, cities and documents, and we can use it in exactly the same way to help our communities model and navigate our natural language laws. But modelling systems isn’t enough if you can’t also show why they’re reliable. Those systems need to be transparently linked back to the law they’re modelling.

I’ve taken some of your existing outputs (from the European Union and New Zealand) and used them in this gift. I’m working with your respective XML outputs, which I process in such a way as to generate the unique references I’d ultimately love you to produce for us all. To be as human about this as possible, I’ve made them human readable as well. The style isn’t so important, but I hope you like my thinking as to how I ended up with what I have.

Here’s my first example of a computer system reference for law:

This is a pinpoint reference to a list item in the EU’s Digital Services Act. Not only is this reference unique, suitable for computer systems and at the level of specificity we’ll need, it’s also human readable once you’re familiar with the pattern used. For example it wouldn’t take us all very long to learn that “#P2-S30-e-ii” translates to “Part 2, Section 30, (e) (ii)”. It also doesn’t detract from our human way of referencing, in fact as part of my demo I use this approach to automatically generate the traditional document references you’re more familiar with.

Now I totally appreciate this might still be very yawn-worthy at this point. But please keep reading, I think you’ll love where this ends up.

1) Love at first sight or granular URLs

A lot of us working with digital systems want to link to your digital legislative artefacts. By ‘linking to’, I mean linking to specific parts of them (like, really specific). When we’re building tools and modelling interpretations of the natural language rules, being able to directly reference source material at a granular level is hugely important to other humans wanting to scrutinise our work. It ties these exercises in improving access to the law much more closely to your creations in a wholesome and transparent way. Consider this (fake URL) example:

https://www.legislation.govt.nz/…/whole.html#C3-s3-a21-p3-l1-e

URLs structured in this way are easier to understand. This means not only can we refer precisely to particular parts of the law, we can more easily see what the URL is referring to.

2) Open, honest communication always (including via API)

I’ve been working with local government district plans. We were building an application to help people navigate and comprehend a specific District Plan in particular. To build that application, we needed a District Plan with “API endpoints”. These specific addresses let us instruct our computers to get the relevant natural language rules specific to each component of our interpretive work. Through an API, you can pull the text of the law itself from one database to another, to incorporate in digital systems.

All we wanted were some beautiful URLs to pull unmodified text directly from an authoritative source. We were hoping for something like https://districtplan.council.govt.nz/api/C3/s3/a21/p3/l1/e (not a real link), which would return a machine-readable type of predictable result that gave us enough information to reproduce it.

We also needed it to let us a specify the precise level of granularity, i.e.

Chapter 3, Section 3, Article 21: 
https://districtplan.council.govt.nz/api/C3/s3/a21

or

Chapter 3, Section 3, Article 21, Paragraph 3, Line 1, List item (e)
https://districtplan.council.govt.nz/api/C3/s3/a21/p3/l1/e

At this point, you can probably see how we’ve used the predictability of our computer system references as a filtering system that’s both URL- and human-friendly.

3) Accepting you just as you are; a wholesome way to collaborate.

To create this gift, I worked with some of your existing XML outputs. I’ve currently worked with two different formats: the EU Formex legislation format and the New Zealand Government XML format. One of the examples I processed was the New Zealand Natural and Built Environments Bill because (a) it is quite big and I wanted to stress test things and (b) it’s a really important Bill. It directly affects the goal of healthy communities and ecosystems, and will have a big impact on people who seldom engage with the law.

I’ll admit I was rather surprised when my code started to reveal structural and content issues with the bill as it stands. At first, I assumed my code had bugs but then I realised something much cooler was happening inadvertently. The level of scrutiny my code required had created a new way to support your own publishing workflows. As a result of “law as data”, we can perform automated structural error checking.

For your perusal, here is a list of issues with the NBA Bill as it’s currently published that the code automatically identified. This isn’t meant to embarass you - that’s really not my intention, and I understand Bills generally are a working draft of sorts, so I trust that this can be considered as constructive feedback. Certainly, working openly on these sorts of problems fits the goals I outlined at the beginning of my letter.

• #P1-S1-s5-l1-c-ii : The sub list repeats the roman numeral “ii” 3 times
• #P1-S2-s7-d69 : The sub list for the definition ‘deposit’ isn’t a child of the definition element - it renders correctly on legislation.govt.nz but contributes to the next issue
• #P1-S2-s7-d81 : The sub list for the definition of ‘dwellinghouse’ isn’t a child of the definition element. This results in the list starting at © because of the issue above
• #P4-S2-s107-p2 : Paragraph number (2) is used twice
• #P10-S7-s692-p1 : Paragraph number (1) is used twice

These are admittedly very small structural issues, but I know the levels of perfection you aim for would welcome a way to identify these issues quickly. I’ve included this even though it wasn’t a planned outcome, but I sense it’s indicative of other solutions that will inadvertently turn up from this type of approach.

4) If love languages existed, ours would be data.

Let’s have a quick recap.

• We have unique references suitable for computer systems. These are predictable and decipherable by humans, rather than GUIDs or simple numbers.
• These computer system references allow us to create unique URLs so we can find and reference our legislation on the internet at a granular level.
• We’ve enabled API endpoints with their own predictable URLs based on the computer system references. Now, our computer systems can retrieve the natural language text at the granularity required.
• We’ve discovered our code can perform automated structural analysis to improve our outputs with very little effort.

These features are enabled by a dataset I generate while creating the new computer system references. The dataset itself is a single table or excel sheet. I might go into the technical details some other time, but for now, just for you, I’ve built an example of the sorts of things this can enable. Have a look at the “Test commentary” that overlays the Digital Services Act section of our gift. I’ll describe it below under the title “Content Overlays for comments and annotations”.

5) Grab a coffee, let’s talk this through

Through this gift, I’m hoping to show you what we could do if we had computer system referencing. It’s also a test to see if I can take your XML outputs, generate the granular blocks of content with their unique references, and in a manner that allows me to then reconstruct the original legislation. This reproduction of the legislation is more a technical proof rather than my goal. It does however allow me to then demonstrate what we can then do with these computer system references. At the moment, I don’t have a good understanding of the constraints you face when publishing enacted instruments digitally (something to chat about over coffee?).

Here are the various things to look out for.

The legislation

The demonstration has a number of legal instruments recreated from your XML source. These human-readable recreations show that my underlying data model can be used to reproduce a view of the legislation as one would expect to read it.

I’ve checked, and yes, this data model works with alternative languages too, so I’ve included the Dansk version of the DSA as a “yes we can do that too” flex.

The blocks

If you run your mouse over the reproduced legislation, you’ll notice that it highlights individual blocks of text. These illustrate how the legislation has been broken down and structured. Each of those blocks have a unique computer system reference. If you click on any of them, it displays the reference at the bottom middle of the browser window in a button. The “Quick link” you can click on to load that URL in your web browser which you can copy and share. It will take you straight back to that block.

The search

The search function in this tool is currently rudimentary, but it works in two ways. You can do a straight keyword search, which collapses the view of the legislative text to hide all content blocks that don’t contain the search term. You can use this view with the detail window (explained next) to explore documents in a uniquely functional way. The search bar also works if you use a # symbol and then enter a reference, you can create partial views, for instance #P1 would collapse everything but “Part 1” and #P1-S1 would collapse everything but “Subpart 1” of “Part 1”. At this stage, you need the full ID (eg, #c2-a4-p1-b would work, but #a4-p1-b wouldn’t). For now, you can discover the unique reference for each block by clicking on any block.

The table of contents

When legislation is written on paper, a table of contents is essential. At present, this demonstration doesn’t have a table of contents, but it’s an easy next step which would be fun to explore. This is important because, at least in New Zealand law, the table of contents (along with notes and other indications) is considered part of the legislation. There’s some interesting future explorations to be had here.

The detail

Once you’ve clicked on a block, clicking on the reference button (bottom centre of the window) loads the details window (you can also press z on your keyboard). You’ll find a visual breakdown of the reference at the top of the detail window. This includes some selectors (“radio buttons”) which allow you to view the block with varying amounts of context - at the level of a section, an article, a paragraph, or a whole chapter or part, for example.

Citation

For the researchers and lawyers among us, there is an in-built automatic citation generator which sits in the detail view. It’s very cute, and it works for both EU and NZ law based on the appropriate style guides. There are plenty of improvements to be made here and I’d love your feedback on this. (I mentioned my admiration for your attention to detail, and I’ve done my best to emulate that in the citation-generator - check out the citations to definitions in New Zealand legal instruments.)

API (Application Programming Interface)

The detail view also includes an API section. This section includes a URL, which is automatically generated. That URL is a functional API endpoint that computer systems can use to access the text of the law in friendly formats suitable for use in digital applications.

Source

The source box gives you a link back to the legislation itself (your work that started all this). In the case of NZ legal instruments, it will at times also include the existing unique ids used in legislation.govt.nz. This makes for a much quicker way of obtaining those direct links many of us are often trying to source.

Dark mode

I won’t presume you hate it, and you know I love it. Legislation needs it, so let’s make it happen.

6) You and me, dreaming of a better world

I started this letter by saying that I think we can do so much more to make the law accessible and understandable to people, and that this was important for maintaining trust and confidence in our institutions and the rule of law. The next point is just one very simple example of a project focused on making law more accessible. I’ve been working on many such projects that would all benefit in unique ways from having this same granular referencing suitable for computer systems. But beyond what I’ve described above, the key thing is what can be done when interacting with law in different ways. Two examples are:

• Transparent and consistent ways of linking digital applications back to their legal source material, enabling better scrutiny of the reliability of legal apps.
• Comments, annotations, and overlays for legal materials to inform law reform processes, build legal knowledge, and make legal materials easier to navigate.

Content Overlays for comments and annotations

This “mashup” type feature is available on the recreated EU Digital Services Act. This is indicative of the sort of application which might be comments, tags, links, submissions etc, that want to be linked to specific parts of the legislation. Here I’m loading in tags live from a dataset in Airtable, where our friends at Brainbox have done some thematic tagging. When you click the “Test commentary” checkbox just above the search bar, it makes a call to AirTable and pulls in the annotations and then overlays them over the legislation. You can then click on these as a filtering option. With an authoritative computer-system-reference published for an act, the public cooperation, annotation and mashup possibilities across endless software solutions as illustrated by this feature would be endless.

With love, your gift

I kinda just built it all here as part of my blog site. A startup, a custom domain and slick branding just wouldn’t have been as romantic, and would have sent all the wrong messages. At the following link you will find a landing page with a list of legal instruments that are each a demonstration in their own right. There’s a few fun Easter eggs in there as well, so please enjoy.

https://hamish.dev/experiments/ll/

If you’re curious, feel free to throw some pebbles at my window and consider this a small pebble bouncing off yours. Some casual yet engaging conversation sounds marvellous right now, and I’d love to hear how you found this letter.

Yours truly

Hamish Fraser

P.S. Invitation to get involved

If it stands up to scrutiny, I would like to properly open source this model under the New Zealand based Syncopate Lab. The Lab is interested in talking with organisations who would like to support us in continuing work like this, that includes creating space for scrutiny and collaboration.