Skip to main content

The Service Innovation Lab (the Lab) partnered up with Legal Hackers NZ and Accenture to run the Wellington Better Rules Hack as part of Techweek’18. This weekend event explored the ideas and practice of turning legislation into machine-consumable ‘digital rules’ that can be reused and integrated across domains for the benefit of government, businesses, individuals, and communities. Around 40 people attended the event, which was hosted by Assurity and sponsored by Accenture, Catalyst Cloud, Ensprial Dev Academy, Legal Hackers NZ, and Victoria University of Wellington.

Lawyers, developers, service designers, policy advisors, data specialists and other keen individuals came from Wellington, Auckland, Tasmania, Taranaki and San Francisco. They got to know each other and formed 5 teams that rapidly turned multiple pieces of legislation into digital rules, to create working prototype applications that benefit people.

Participants were able to use open APIs (Application Programme Interfaces) of the digital rules powering the Smartstart financial help tool and the Rates Rebate Alpha (read more about our work on Rates Rebate). Data61 provided participants with a Regulation as a Platform development environment, and the Lab stood up the Aotearoa New Zealand OpenFisca instance.

Like with most hackathons, it was an intense weekend, but all the participants, mentors and helpers enjoyed the experience and learned a lot from each other. It resulted in the delivery of 5 practical demonstrations of the opportunities that legislation as code/digital rules offer, contributed NZ legislation into the Lab’s open source entitlement rules engine (in OpenFisca), and formed the beginnings of a supportive community to for this work. Participants could see how legislation as code is both an operational and strategic asset for government digital transformation.

Participants identified some key opportunities and challenges of legislation as code/digital rules:

Legislation as code enables:

  • digital service delivery that works for people by hiding the complexity of multiple rule sets and giving them greater certainty about their eligibility or obligations
  • greater opportunities for democratic participation in the development and improvement of legislation
  • improving the logic and consistency within and across different rule sets, particularly if implemented as Linked Data using URIs (Uniform Resource Identifiers).

Challenges of turning legislation in to code:

  • You have to first know how government works to be able to find all the rules that apply to a given scenario.
  • The process flow as laid out in the legislation made it difficult to discern the eligibility rules from the calculation rules, and added to the work of making the process flow work for people.
  • Some legislation has terminology and definitions that are not internally consistent, and some terms are not defined leaving interpretation up to the individual.

We’re following up on the success of this hackathon with another one in Tauranga on the weekend of 28-29 July. See the Better Rules Hack website for more information.

Highlights from the Better Rules Hack

Video 1. Better Rules Hackathon Wellington 2018

Video transcript

Welcome everyone and welcome to the first, I guess, Better Rules Hackathon.

This idea started because a whole bunch of people are very interested in legislation as code, as it turns out when we try to integrate services we need to get the rules about , you know entitlements about eligibility and about calculation and xml is not sufficient for that.

We actually need code. So we thought ok well let's do a hackathon. Let's test some of our assumptions. Let's see if we're crazy.

Maybe, you know, this could go in all kinds of different ways. But our belief is that transparent rules that are machine consumable, are critical to maintaining traceability and accountability into the future. So again that's part of our theory.

So I'll just go through some of the rules. We want teams to develop a technical prototype. So to actually demonstrate how it would work in practice. And also a three minute video that talks about how and the why and the what you are seeking to achieve with your actual entry.

So atoms are your inputs and your outputs. And you'll notice that the permission to stop in the loading zone is separate from the fact that whether you have actually stopped in the loading zone or not. This is how we model compliance.

OpenFisca is a free and open source computation engine that makes law computable. It allows us to represent legislation as code over all it's evolutions, throughout any time periods and for any kind of entity.

Why? Obviously if you're talking about a specific term like immigration you want to limit yourself to a small subset of pieces of legislation or act or what not. But with something like what you're talking about, why limit yourself, to let's just do two. Bugger it, do all of them.

So some are really more complex. So like this means this, and then you expand it to that fact. But for others like actually there's a lot of those words saying: principles this, except for these exceptions. And for most people the principles enough.

Okay guys if you all want to converge in the middle, we'll get going with your presentation.


Now with the voting, every team has three votes.


And the team that scored highest- this is your voting- was the Organic Coders.



Better Rules Hack entries

Organic coders

Making the live organ donor process easier for donors.

Project website:

Legislation used as code:

Github repository:

Video 2. Organiccodersv2
Video transcript


Hi. We're the Organic Coders. We've been looking to translate the legislation from the Compensation for Live Organ Donors Act 2016 into code.

Hi. We're the Organic Coders team. I'm Nigel. I'm here as a back-end developer and also just general dogsbody-- getting the coffee and all that kind of stuff.

Hi. My name is Alan. I joined the team as a dev ops specialist. So I was responsible for setting up all the back-end servers. And then also I was a front-end developer and helping to design the website and then the front-end calculator.

Hi. My name is Jacob. I brought my development skills to the team. I drove all the way down here from Taranaki. I helped work on the tax calculations and web API.

Hi. My name's Bridget. I flew all the way here from Tasmania. I specialise in legislation, and I helped create the linked data for the code.

So on the first day, we got introduced to our mentors. Luckily, we had Rachel around who did these great drawings of them so that we could remember their faces. In addition to these, we also had Robert come in and help us with operationalizing our linked data into the code. And Matti was a great help with OpenFisca and his knowledge around that. And he helped us work around a couple of issues that we had.

So as a team, we got around the table and discussed what we were going to code for the weekend. It was quite easy. And in the end we chose this act, partly because it does great social good and also pulls two or more acts together. And the social good really comes down to helping save a life by saving time.

So the purpose of the act is to remove the financial burden and deterrent on the donation of organs by the live donors. In New Zealand, there's about 300 people every year who decide to donate an organ. And this can be increased if we make it easier or more financially viable for people to donate organs.

So what does the act actually cover? Well, it covers live organ donors for up to 100% of their loss of earnings in the period while they are recuperating having donated an organ. This cover applies for up to 12 weeks from the time the operation occurs. To apply, the donors fill in a form and send it to the Ministry of Health, who then take up to 10 days to process the form and estimate the loss of earnings that the person will have. We thought we could improve this by developing an application that would automatically give them a good estimate of what their loss of earnings might be.

So that we knew that we were building something that actually would help actual people, we decided we would go and talk to some people who had donated an organ and find out from them what the experience was like. We got to talk to Richie, who had donated an organ a couple of years ago. We also had a look at the Ministry of Health website, and that showed us through what they thought was the user journey. Together, with Richie and the Ministry of Health user journey, we have created a journey that reflects the actual experience of Richie and how he came to donate an organ to his dad.

So first of all, he was moved to donate an organ because his loved one had become ill and needed a new kidney. He then did a bit of investigative work that wasn't just looking at the website or calling. It was talking to professionals, talking to his dad, talking to his loved ones. Then it was making the call to the Ministry of Health. Then came the donation, the recovery, and the return to work.

Richie's story is inspiring. Five years ago, he learned his father had kidney problems and that his kidneys were failing. For him it was a simple decision. Both he and his dad were quite healthy otherwise, and so he felt that donating a kidney was the best thing he could do for his dad.

Once they'd made that decision together, he contacted the New Zealand kidney association to learn about the process. He really wanted to talk to other people about what it meant for them to donate, about the success rate of living with only one kidney, how did the whole process actually work, and would it change his current lifestyle. We asked him what he thought the compensation would have meant to him, had he been able to access it. He said that it's one of the barriers. It's an intensely stressful situation, and the compensation will really help.


So I want to take you through the technical aspects of our implementation. First, for infrastructure, we set up a basic two-tier infrastructure on Catalyst Cloud. For a back-end or an API server, we used OpenFisca, and we set that up here. And then for the front-end, we used WordPress as another server setup here.

We used the OpenFisca API, and we customised it to encode different aspects of the Compensation for Live Organ Donors Act of 2016, as well as pieces of the KiwiSaver Act and the ACC Act. So we basically put those customizations in this Python file here. And so different aspects of the rules as it pertains to your weekly compensation are encoded here. And then the rules for the KiwiSaver component of it are encoded here.

Part of the special stuff about legislation as code is that we're taking an opportunity to encode it as linked data by defining the terms that are in legislation and then resolving them as linked data by assigning the terms of a unique identifier. As part of our project, we recognise the act of coding the legislation was also creating a data model of sorts. So we took time to define the terms and reuse existing international vocabularies and standards where we could.

Where we found something that had not been defined, we assigned a unique identifier to it, which, if we take this piece of code here-- for example, earnings, period, and weeks-- we could see the unique identifier points to this reference URL, which goes here and actually gives us the unique identifier. This allows others to connect to this term, giving us an automatic understanding of what's common across a piece of legislation. So for our front-end website, we used WordPress. And so the front-end website basically takes donors through the potential journey that they'll have, some of the considerations that they need to take as a live organ donor, and then eligibility requirements that they need to meet.

The part where OpenFisca comes into play is in the compensation calculator. So if you're a live organ donor, you're entitled to a compensation period for the work you'd be off while you recover. So we do the calculation so that you could actually see how much you would be entitled to.

So the calculator is pretty basic here. You could just say, I earned $52,000 over the last 52 weeks. I was not self-employed. I did not receive any ACC. But I did contribute to KiwiSaver at 8%.

And then we can click here, and this will actually go call the OpenFisca API to actually apply the rules of the legislation as code and return a value that lets us know that our estimated total weekly compensation would be $1,000 for up to 12 weeks. And our total weekly KiwiSaver contribution would be $80 for 12 weeks. And that is our solution.


Version control for legislation by making it work like open source software where people can track law changes and suggest improvements.

Project website:

Legislation used as code:

Github repository:

Video 3. EnActivity: Better Rules hack
Video transcript


Programmers have really good tools for working with complicated text documents. We think that it should be just as easy for people to work with legislation in New Zealand. New Zealand [NO AUDIO] are available through That's a website. It's great for humans to read.

The website also has the law in XML. We want to transform that to a form that's familiar for programmers and also easier for everyone.

We think the law can work like open source software. If we're successful, anyone can track changes as the law evolves. Even better, citizens can propose amendments to make the law work better for them.

So we've developed a web scraper to download all of the XML legislation documents from the website. Now, from there, we will transform those XML documents via Python scripts into AsciiDoc documents, which are then uploaded to GitHub for easy differentials.

We chose AsciiDoc for two reasons. The first is that it is a simple, easy to use, human readable format that makes comparing versions easy. Second is that GitHub has built-in support for format, offering both raw and fresh displays.

To start with, we used the conventional techniques of using an XML-style sheet to convert that big complex XML into a format of plain text. However, we quickly realised that this is not a simple activity, considering the complexities of that XML. We also realised that the Parliamentary office's IT team would be better equipped to handle this, since they are already converting those XMLs into PDF formats.

We successfully completed a prototype. It scrapes XML from, transforms the XML to AsciiDoc files, and uploads to GitHub in such a way that creates comparable versions. We've demonstrated successful functionality using a piece of legislation from 1993. But our code is already capable of working on all the legislation provided in XML format, all the way back in 1858.

We're lucky in New Zealand that our institutions are very interested in opening access to the law. We hope that by showing what else is possible, we're inspiring further steps in that direction.


Start a business

A question-and-answer chatbot-style system that guides prospective business owners through the processes to register their business and be otherwise compliant.

Project website:

Legislation used as code:

Github repository:

Also read Dave Moskovitz's blog post about his experience in this team

Video 4.
Video transcript

Hi. My name is Ross Patel from the StartaBusiness team at the Better Rules Hackathon in Wellington, New Zealand. And I'd like to tell you about the work we have done over the weekend and the great solution we have put together to help people start their own business.

Starting your own business in New Zealand is easy. But it requires compliance with a number of different laws and regulations which are held and regulated by a number of different central government agencies, as well as local government.

There is no one stop shop to take someone through the steps they need to go through to start their own business and be legally compliant.

For our solution, we focused on two user scenarios. I'd like to introduce you to Materroa. She is 27, single, and a chef that would like to open her first food truck business with her sister, selling vegan Maori food. She wants to understand and make sure that she is compliant with the rules around opening her food truck. And she is frustrated that she doesn't know where to start and where to find the relevant legal information.

Our second user scenario wanted to become a sole trader consultant and begin his own consultancy business. I'd now like to take you through our solution that will help these two people.

The main idea behind our solution is to lead people through a series of questions in a friendly chatbox-style interface and provide them with the info they need to give to government agencies to be compliant with the law and also to provide the links to the various online forms that they need to fill in.

On the results page at the end, the platform provides an action plan with steps for the user to become 100% compliant. In the future, this could be displayed in a Trello board style or chiclet style.

At the heart, our solution falls in the question-answer paradigm with conditional flow. Some questions are asked and some advice is given based on the answers to the previous questions.

We implemented our solution using the open-source conditional for JavaScript framework. The solution is coded almost entirely in HTML. The conditional form framework abstracts the heavy lifting to the extent that all of the code can be encapsulated in tags.

One of the hard parts about both RaaP and OpenFisca is the user interface. It would be relatively straightforward and a good idea to use the conditional form front-end for future back ends built in RaaP OpenFisca or other systems. This platform demonstrates how legislation, as digital rules, can allow apps like to easily draw required rules from the different places they sit on the internet.

We had a really strong team with a great mix of skills who gelled and worked together very well over the weekend. Everyone contributed and learned a lot from the experience.

We had Caleb from the Dragonfly, our main developer. Maia, a recent EDA grad who worked on JavaScript and project management. Kay, an independent contractor who gathered the source info and formed the questions. Dave, a professional company director, developer, and cheerleader. And myself, giving UX and UI input.

We thank you very much. Cheers.

Best Start

Mobile responsive website that help parents to calculate how much money they might get per week, per child under the new Best Start tax credit.

Legislation used as code:

Github repository:

Video 5. Best Start: Better Rules hack
Video transcript


With my second child on the way, I need to make a plan for my family's financial future. Will we be able to make ends meet if I choose to stay at home with my kids, or will I need to put them into care so I can go back to work, either full time or part time? This useful tool on the Best Start website helps me to work out how much support I might be able to get from the government over the first three years of each of my kids' lives. It's reassuring to know that with that kind of support, I could stay at home with my kids a bit longer.

The Best Start tax credit is a new set of social policy tax legislation, enacted by the Family's Package Act, 2017, and becomes effective on the 1st July, 2018. The new act amends the income tax and tax administration acts to allow for the new tax credit to be delivered through the existing working for families social policy.

This demonstration is simulating a customer interacting with a front end interface in order to calculate their entitlement to the Best Start tax credit. The interface requests family income and child birth information from the user, and then sends this information to OpenFisca to compute their Best Start entitlement. Utilising OpenFisca allows for us to easily scale in the future other social policy credits, alongside other statistical information, and simulate further entitlements customers could expect. In this example, you can see that the customer has entered one child and is eligible for the full Best Start tax credit entitlement.

We analysed existing interfaces and realised that current implementations do not provide a point in time calculation of what the customer could actually expect. We translated the computable law into to OpenFisca parameters and variables, working on a consistent ontology, harnessing its engine to compute and deliver easily consumable JSON objects backed by a frontend interface. This interface, an OpenFisca instance, has been pushed out to the cloud, and is easily accessible, released under an open source GPL licence. Feel free to come and take a look at some of our code files.


1st Homework

To make it easier for prospective home-buyers to determine whether they are eligible for Government assistance, particularly for the KiwiSaver HomeStart grant, and given changing Loan to Value Ratio restrictions imposed by the Reserve Bank.

Legislation used as code:

Github repository:

Video 6. 1st Homework: Better Rules hack
Video transcript

Hi, I'm Judy.

-- what is your background? And how does it relate to the project?

I'm an ex-lawyer, who have had first-home buyers as clients. And one of the hardest things that they have to do is to figure out whether they have enough money to buy a house. And the government has a Kiwi Saver HomeStart grant assistance for first-home buyers. But it's not very clear whether someone is eligible.

It's not a lot of money. It should be really simple. So we're creating an app to calculate whether someone is eligible for a HomeStart grant.

-- Excellent.

-- Hi, what's your name?

Hi, my name is Hayden. I am a student of software development. And I really am interested in this project, because of the implications it can have for young people, such as myself, wanting to buy homes for the first time. It can be quite a confusing process. So for myself, I know that having a questionnaire that doesn't bother me with reading through huge paragraphs of law and trying to translate it myself-- having the Open Fisca software able to do that for me in the background-- super helpful.

-- Hi, who are you?

Hi, my name is Brian.

-- Yeah.

So I have been doing Perl, Android, and iOS development. In this project, my role is to focus on the front end development (using React).

-- OK.

-- What do you like about this project?

What I like in the project is that our coding can help people to understand the legal context better. This is what I like.

Thank you.

-- Hi there. What is your name?


-- What have you found challenging about compiling documentation for a hackathon setting?

Well, you keep getting the people who have the knowledge about that particular part of the project to check that my understanding of the project as correct and that what I've written is readable.

So what we've created is a KiwiSaver Eligibility Calculator. This is calculating whether you're entitled to a HomeStart grant. You can see that there are error messages if you click the wrong answer. And that means you won't be eligible. Sometimes, there are exemptions, as you can see. And there are boxes where you can fill in. And it'll calculate whether you are eligible. You can learn about your eligibility in this way.

If you'd like to stay across the work coming out of the Service Innovation Lab, please join our mailing list.

Utility links and page information

Was this page helpful?
Thanks, do you want to tell us more?

Do not enter personal information. All fields are optional.