Introducing CLEAN - Markdown for Akoma Ntoso
The Problem
I made a number of changes to Blawx that makes it possible to organize your code according to the pieces of the legislation. This is the first of a number of improvements that are all designed to let you use Blawx to do a structurally-isomorphic encoding of the legislation.
The problem was that the initial version did not provide any good way to edit the Akoma Ntoso source code for the legislation. Ideally, there would be an open-source WYSIWYG editor for Akoma Ntoso that was easy to use, and could be integrated with Blawx. Unfortunately, the only options I could find that were WYSIWYG were neither open-source NOR easy to use.
The next best thing would be to use an open-source tool that would allow us to easily generate Akoma Ntoso encodings from plain text in the way that Markdown is a tool to allow you to easily generate HTML from plain text.
Unfortunately, the only open source tool I could find for doing this was slaw, which while excellent, does not expect the text to be formatted in the style that is usually used in Canada. I might have just added Canadian legislation as a format, but it is written in a language and with a library that I don’t have any familiarity with, and it also seems to generate Akoma Ntoso documents in a style that the Blawx system is not expecting. Valid, but with extra pieces, and non-standard element types.
So unfortunately, the simplest thing that could possibly work became writing a new language, and building a tool to parse it and generate Akoma Ntoso from it. Enter “CLEAN.”
CLEAN - Canadian Legal Enactments in Akoma Ntoso
Clean is a combination of a parser for the CLEAN “language”, written using the PyParsing Python library, and some simple functions that generate Akoma Ntoso from a valid CLEAN file.
The point is to use an intuitive text format, like Markdown, for people familiar with the style of legislative drafting used in Canada, that is capable of generate a small but useful subset of Akoma Ntoso, and which can be easily integrated with Blawx.
How it Works
If you create a file called rps.clean that reads like this:
Rock Paper Scissors Act
Players
1. A game of rock paper scissors has two players.
2. There are three signs:
(1) Rock,
(2) Paper, and
(3) Scissors.
Defeating Relationships
3. The signs have the following relationships:
(1) Rock beats Scissors,
(2) Scissors beats Paper, and
(3) Paper beats Rock.
Winner
4. The winner of a game is the player who throws a sign that beats the sign of the other player.
… and if you run this command …
python3 clean.py tests/rps.clean
… you get the following output …
<?xml version="1.0" encoding="UTF-8"?>
<akomaNtoso xmlns="http://docs.oasis-open.org/legaldocml/ns/akn/3.0">
<act>
<preface>
<p class="title">
<shortTitle>Rock Paper Scissors Act Players</shortTitle>
</p>
</preface>
<body>
<section eId="sec_1">
<num>1</num>
<content>
<p>A game of rock paper scissors has two players.</p>
</content>
</section>
<section eId="sec_2">
<num>2</num>
<intro>
<p>There are three signs:</p>
</intro>
<subSection eId="sec_2__subsec_1">
<num>1</num>
<content>
<p>Rock,</p>
</content>
</subSection>
<subSection eId="sec_2__subsec_2">
<num>2</num>
<content>
<p>Paper, and</p>
</content>
</subSection>
<subSection eId="sec_2__subsec_3">
<num>3</num>
<content>
<p>Scissors. Defeating Relationships</p>
</content>
</subSection>
</section>
<section eId="sec_3">
<num>3</num>
<intro>
<p>The signs have the following relationships:</p>
</intro>
<subSection eId="sec_3__subsec_1">
<num>1</num>
<content>
<p>Rock beats Scissors,</p>
</content>
</subSection>
<subSection eId="sec_3__subsec_2">
<num>2</num>
<content>
<p>Scissors beats Paper, and</p>
</content>
</subSection>
<subSection eId="sec_3__subsec_3">
<num>3</num>
<content>
<p>Paper beats Rock. Winner</p>
</content>
</subSection>
</section>
<section eId="sec_4">
<num>4</num>
<content>
<p>The winner of a game is the player who throws a sign that beats the sign of the other player.</p>
</content>
</section>
</body>
</act>
</akomaNtoso>
If you plug that into Blawx, you get an interface for your code that looks like this:
There are still some bugs. Headers are getting included in the text of the previous section, but you can see where I’m aiming with it.
Plans
I’m working on cleaning up the codebase and adding some tests, after which I’ll publish it under the MIT license, so anyone who wants to can play with it.
Once the bugs are squished, I will be working to integrate it with Blawx so that you can input and edit your legislative text inside Blawx using the CLEAN language. Blawx will still be using Akoma Ntoso in the background, and eventually it will also be a format for import and export.
I will also be working to expand the capabilities of CLEAN, as there are a bunch of important features still missing, like sandwich sections, multi-line text, paragraphs directly under sections, and a few more.
Once that’s done, the immediate priorities for Blawx development move to taking full advantage of the presence of the legal document structure by re-implementing defeasibility features, and finding a way to link the text of the statutes to the explanations generated by the tool.
I’ve been working with people at the Canada School of Public Service who are collaborating with people in a number of different Canadian federal departments, and that context has made it a lot easier to figure out what to do next for Blawx… whatever makes it more useful as a tool for those projects.