Our work ›

An IDE-like tool for legislative drafting

Visualiser tool - how legislative drafters can use it

For the first half of 2025 we secured funding from the Jersey Legal Information Board to work with the Centre for Digital Law at Singapore Management University on several ideas to see what their L4 computer language (a “domain specific language” or DSL for law) can do with our project. SMU have finished their research, and L4 is now being taken forward by Legalese.

Farmer example as a draft and in L4 visualiser Farmer example as a draft and in L4 visualiser

  • See our slides for CALC Belfast 2025, this demonstration video and interactive example and instructions for how a legislative drafter can put a draft provision into the interactive, free, web-based (no downloading needed) visualiser that our Singapore colleagues built for us.
  • The slides and video show how a legislative drafter can produce an if-then version of a draft provision, which can be automatically converted into L4 to produce a flowchart-like logical map that a reader can interact with to guide them through the legislation. This limited use of L4 is a way in which legislative drafters, with no technical knowledge (just the grammar, logic and paragraphing that they use every day), can produce working code that they and their policy officers could use to check drafts. That helps drafters to picture the potential benefits of using a fuller system - elsewhere on the same site you can see examples of L4 being used more fully, including for Jersey’s Charities Law.
  • For more on this see our slides for RaC Guild Sept 2025 (or here), our slides for LVI2025 Sydney & our Substack post (& earlier report).

Tool for definitions - pop-ups and links from defined expressions

In separate but related work, we are developing a tool to enable drafters in Jersey to add mark-up to generate pop-ups from defined terms, to show the text of the definition with a link back to wherever the definition provision sits. For background, see our presentation video and newsletter item.

This is an initial spin-off from the idea of creating a unique identifier for each paragraph of text in legislation, which is computer-readable but also makes sense to human readers (see below).

  • Jersey’s Legislative Drafting Office, like many others in the Commonwealth, still uses Word (rather than XML, used by larger offices). So our innovator and Word-wrangler, Kate Hannah, has been developing a Word version of the IDs with a Word tool to enable legislative drafters to use the IDs to mark up each definition and defined term, so that the definition pops up when you move the mouse over it, with a link to the definition provision. The drafters are now testing a beta version that tool and demonstrating the results to policy officials, with good feedback and hopes for a full roll-out if possible.
  • The tool enables drafters to apply apply the pop-ups and links for definitions from within the same piece of legislation (we have noticed that Kenya’s planned new site will do this).
  • But the drafters also use this tool to reveal the definitions in the Interpretation Law (or equivalent Interpretation Act in other Commonwealth jurisdictions).
  • They also use it to reveal the definitions that flow down into subsidiary legislation from the legislation under which the subsidiary is made, under Art 10 Interpretation Law (most Commonwealth jurisdictions have an equivalent).
  • Many readers of a piece of legislation would otherwise be left completely unaware of either of these additional sources of definitions.
  • The pop-ups and links then feed automatically from the Word drafts into the html and pdfs for our web pages, so we are hoping the tool will pass its testing and be able to be rolled out for both legislative propositions for debate in the Assembly and enacted legislation on JLIB.

A screenshot of pop-ups and links for defined terms

Manual v automatic

An important feature of this is that legislative drafters are applying the definition markup to each new instance of the defined term while they are drafting the legislation, rather than having an automatic system apply it afterwards. We believe this additional effort should pay for itself.

  • Several of the Legal Information Institutes in other countries (the equivalent of JLIB, but publishing unofficial versions of legislation) have used automated tools to go back over a country’s entire existing statute book and apply pop-ups and links from defined terms to their corresponding definitions. This is clearly of some benefit in an unofficial version of the legislation, if it comes with a large health warning.
  • The main problem is that an automated system picks up many false positives – words in the text that match the defined term but that a human reader would realise are not really instances of that term. If this is being done across the whole statute book it is not going to be practical to have a human expert then check every marked up word to see if the markup should be removed.
  • Similarly, there may be a problem of false negatives in that definitions are usually meant to cover grammatical variations of the defined term, such as “registration” and “register” (Jersey has that rule in Article 2(c) of our Interpretation Law). That means the automated system has to use a highly sophisticated search which catches the additional forms of the word without worsening the false positive problem.
  • Even if technical solutions can be found for both those issues, there is still an underlying legal problem that cannot be fixed automatically. That is that in older legislation, still on the statute books, there will be mistakes where the defined term has been inadvertently used in a different sense. That reflects the fact that, in the days of handwriting on paper before Word search and systematic checking, drafters could not be sure they had used defined terms correctly even in a fresh draft. That was why definition provisions used to start with “In this Law, unless the context otherwise requires”, because that also served as an escape route for mistakes. In recent years Jersey’s Legislative Drafting Office has stopped using that wording because it is now reasonable to expect the drafter, helped by the checkers, to make sure defined terms are used properly in a new draft. The problem is that in the older legislation only a court could decide whether a questioned expression does attract the defined meaning – an automated system certainly cannot do that, and even a modern expert cannot claim certainty (usurping the court’s function). A modern drafter will be using this tool to help ensure those sorts of mistakes do not occur in today’s drafts.

It is, of course, more work to mark up each instance of a defined term manually, and the benefit is more restricted if it cannot be done for the whole existing statute book, but -

  • The testing being carried out by the Legislative Drafting Office on the tool is to see whether this manual markup is practical when done as part of the drafting process. So far the results seem positive, in that the effort is repaid by keeping the drafter alert to the definitions as they go along and helping reviewers to spot errors. The testing also identifies ways in which the tool might be refined to make the manual process as easy as possible.
  • If the tool can sensibly be rolled out into full use, so that the links appear in the published legislation, it will be on an incremental basis, in that it the links will only appear in new legislation (or older legislation that is re-enacted for the purpose). But that is very similar to our approach to “Rules as Code”, which we believe only gives its full benefits when applied during the drafting (and where Jersey might be a good fit for the incremental approach).

Wider idea of an “IDE” for legislative drafters

We have an interactive mock-up of some of the functions of an imaginary tool for legislative drafters - please try it out (and see the explanations in our newsletter).

A screenshot of the mock-up of a drafting tool

It is a work in progress and we will add separate videos to illustrate further functions -

  • We have notes on our OSF site about the idea of expanding the defined terms hyperlinks to cover undefined repeated terms (which should have the same meaning).
  • We also have a PowerPoint showing how the tool in the mock-up might look if it handled those repeated undefined terms,
  • Another PowerPoint shows how it might look if it handled marking up “must” and “must not” provisions to higlight their elements and link to the consequence of a breach.

We want to show legislative drafters how a possible tool could work to help them create, mark up and check the logical structures in their drafts while they are drafting.

  • We aim to do that by producing illustrative mock-ups, plus a basic specification as a starting point for any interested developers.
  • We want legislative drafters to imagine an equivalent for them of the “Integrated Development Environments” that help programmers to code (ideally with a tool sitting inside our Word templates or XML editors). We want to avoid legislative drafters imagining we mean they have to draft their text first and then go back over it to mark it up.
  • In the longer term we would like to see developers create these drafting tools, starting with our basic spec. But for now we are just illustrating what a tool could look like, to set the ball rolling.

A screenshot of a Python IDE offering help to a coder

  • Programmers already have these tools to help them when they are writing code. Jersey’s Legislative Drafting Office has a “coding club”, where we have seen the benefit of tools in an online Python IDE, Editor, Compiler, Interpreter which (for instance) knows what you have already defined. Grimmelmann explains how lawyers could benefit from equivalents of an Integrated Development Environment and Jupyter Notebooks.
  • Oracle Intelligent Adviser is an existing commercial tool (from before generative AI) that shows it is already possible to help draft & check computer-readable business rules, and it was originally designed with legislation in mind.
  • We want to build on Schwartz & others (2023) “Design Principles for Integrated Legislation Drafting Environment”, who were the first to spell out what this could mean for legislative drafting. We want to adapt their approach for the Commonwealth style of drafting.
  • In the EU there is the LEOS editing tool. They are looking at adding functions to help EU drafters and to allow them to mark up more elements in their Akoma Ntoso system (potentially using LegalRuleML) - see “Drafting legislation in the era of AI and digitisation” and “Overview of smart functionalities in drafting legislation in LEOS”. The UK’s LawMaker drafting system is XML-based, also using Akoma Ntoso, and has also been looking at LegalRuleML.
  • Just before this project started, we met Oswald Maskens who demonstrated a model he had made, gave us a talk on his ideas about leveraging tools for software engineering in legal corpus management, and showed us VS Code as an example of what an IDE could offer for legislative drafters.
  • In February 2023, Hamish Fraser sent a Love letter to Parliamentary Counsel of the World (& some sequels, including “Happy Valentine’s Day, Nerds 💌”). The idea is that every paragraph of text should have its own unique ID which captures the structure (of sections & sub-sections, etc.) in a human-readable way. Once you do that, unexpected possibilities open up. Hamish worked in Syncopate to make DocRef with nested, understandable & manageable IDs like –
    • “P2-S10-s65-l1-a-ii” for reg 65(a)(ii) in Subpart 10 of Part 2
    • which in Jersey, where we have Articles instead of sections (& we have not gone for IDs for Parts, as they are not part of the numbering of actual provisions), gives IDs like - “art_18_p_2_sp_b_cl_iii” – for Art 18(2)(b)(iii)
    • see above for how we are building on this to give pop-ups for defined terms.

What would the imaginary full IDE-like tool do?

  • The tool would help the drafter to be rigorous in creating (and marking up for computer readability) -
    • if-and-or-not structures,
    • defined terms (see the mock-up) and repeated undefined terms (which should have the same meaning each time),
    • provisions that use “must”, “must not” or “may”,
    • other key elements such as offences and vires (powers to make subsidiary legislation),
    • any standard adaptable provisions arising from “Common Legislative Solutions”.
  • The idea would be to use drop-down lists of suggestions (& other help) to enable drafters to write consistently while the tool automatically marks up the text correctly (and possibly gives useful error messages when it detects an inconsistency).

Some examples of what the tool could do (as descriptions, but better seen in demos)

We are using the interactive mock-up (and supplementary static mock-ups) to demonstrate what we mean, given it is far easier to get the ideas across to the rest of the legislative drafting community that way. But we will also see if we can produce a basic specification that a developer could use as starting material, and we need to explain what we mean in text as well as through demos, so here is an attempt.

One way for legislative drafters to think about it is just as doing something more than what (we hope) your current system already does for you.

  • You might be in one of the bigger drafting offices that have already moved over to writing in an XML editor (like LawMaker in UK offices).
  • But if your office is still using Word (like Jersey), you probably have Word styles and templates (and maybe macros) that already help you to format your next paragraph/sub-paragraph/etc and number it correctly instead of you having to do that manually.
  • In the XML systems the editor is (behind the scenes) adding metadata that identifies the provision as a paragraph with that number so that a computer can read the metadata.
  • This tool would just be adding more metadata behind the scenes (or perhaps generating a twin version) to identify the logical elements as well as the structural elements.

Much of this would be by intelligent auto-complete suggestions -

So imagine you have defined “alcohol” (which the tool helped you with) and then further on you type “al” -

  • the tool offers to auto-complete that with a drop-down set of choices including “alcohol” as defined,
  • if you pick that word, the tool marks up that instance of “alcohol” as a use of the defined term
  • see the way this works in the “Edit me” sections of the interactive mock-up.

Then imagine you type the first couple of letters from another word, like “contravene”, that is defined in your country’s Interpretation Act/Law -

  • as with “alcohol”, the tool offers to auto-complete “contravene”, this time as defined in the Interpretation Act/Law (again see the mock-up),
  • if you accept, the tool marks up “contravene” as a use of the defined term from the Interpretation Act/Law (so far the mock-up does not reflect this)
  • the same goes for words defined in legislation under which subsidiary legislation is being made, where the subsidiarly legislation inherits those definitions).

Or imagine you type the first couple of letters from a word you haven’t defined but you have used already, maybe “sheep” -

  • the tool offers “sheep” as one of the auto-complete options, but on the basis that will mark it up to reflect that it should have the same meaning as every other use of “sheep” in that draft,
  • the tool also catches grammatical variations of the same word, and it raises a question when you use a synonym of a previously used word (“do you intend this to have a different meaning from its synonym X which you have already used?”),
  • but the tool is set up to ignore logical words like “and” or trivial words for this purpose.

Or imagine you are drafting a provision to create a new offence, using standard wording -

  • so you pick a drop-down option for that, or you type “co”,
  • the tool offers to auto-complete “commits an offence and is liable to” (the standard wording now in Jersey),
  • if you accept, the tool marks that up as an instance of offence-creation.

Or imagine you type “the Minster m” -

  • the tool offers to auto-complete that as “the Minster may” or alternatively as “the Minster may by Order”
  • if you pick the one for an Order, the tool automatically marks up those words as creating vires for a subsidiary,
  • it will also specify that the power is to make an Order,
  • and in Jersey it would specify which Minister has the power, on the footing that when you typed “the M” it suggested “the Minister” as the term you had already defined as “the Minister for X”.

Or imagine you want do something that is covered by Common Legislative Solutions, or you look like you are doing it, and you pick a menu or the tool pops up an offer to use the Jersey standard wording for that kind of provision, as well as marking it up.

Not just auto-complete - prompts help with “if” and “must” and other structures

The tool would not use the sort of auto-complete in Word that irritates drafters by guessing what word you are going to use next. Instead, when you do something it recognises, it would offer a drop-down list, and allow you to you click on one of the choices (or ignore them). Nor is the tool just a glorified handler of a precedent bank.

The tool would also help with constructing “if” provisions, by marking the conditions, the and/or between them, and the effects, and so on -

  • you press enter to start a new paragraph (your system already automatically formats that as a paragraph and numbers it properly, and, if it is an XML system, already identifies that numbered para with metadata),
  • the tool pops up an offer to help you in case you are making an if-then provision (which most provisions are),
  • if you click “yes” then it helps you clarify in your own mind what the conditions and effects are and how the and/or/not elements work, as well as marking them up for you.

Also, when you type “must” (or pick it from a menu) -

  • the tool prompts you to check that you have a clear enough link to the consequences (in another provision, or implied) if the “must” is breached,
  • it asks if you are applying the “must” to a person (and asks if you are sure you want to use “must” if it isn’t a person),
  • if it thinks you have used passive voice after the “must”, it asks you to check whether you really want to.

And so on - the tool does not need to dictate drafting rules, unless they are compulsory in your office.

The aim of the interactive mock-up is to make this clearer by allowing you to see an example working. We are also producing videos (and static screenshots) of mock-ups to illustrate other particular aspects of what the tool would be doing.

This page is being updated. See our sub-project “What might an IDE-like drafting tool look like?” on OSF for more.