-
Notifications
You must be signed in to change notification settings - Fork 19
Home
A guide to writing legislation as code for Aotearoa New Zealand. This wiki is to be considered a quick introduction to OpenFisca Aotearoa, what it's about and how to get started. For technical documentation on the open-source project OpenFisca that OpenFisca Aotearoa is built on, please refer to the Open Fisca Docs.
The goal of the project is foremost an accurate computational representation of Aotearoa's legislation. For programmers this can require losing some "best practice" habits in achieving optimal outcomes with respect to the legislation. This wiki's goal is give clarity and a sense of consistency to contributors contributing to OpenFisca Aotearoa.
The first consideration when approaching this project is that it will never be finished because New Zealand's Parliament is unlikely to stop writing law any time soon. This makes good practice around change tracking essential. It's also envisaged that OpenFisca Aotearoa will be deployed per use, rather than in a centralised manner. This frees the project to grow and adapt. It also distributes the responsibility of accurate/up-to-date deployments and the decision whether to upgrade a deployment with those deploying the instances.
The second consideration is that OpenFisca Aotearoa is more of a platform than a product and it sits on the OpenFisca Core which is the underlying computational engine. As a platform it has a very open folder structure and the organisation of file names and terminology is up to those working on the project.
Naming things is of course considered the hardest thing in programming. With legislation the standardisation of terms and their definitions within individual pieces of law is common practice. Within the Aotearoa legislative environment it's also common to reference other terms "as defined by the [Another Act]". However individual terms are widely used in different ways and even redefined from their natural English meaning for the purpose of an individual act.
Here's a simple example from current Aotearoa legislation:
Within the Student Allowances Regulations 1998 we find the phrase:
does not include a person who is legally married but who does not have a spouse
A dictionary definition of the word spouse is
Someone's spouse is the person they are married to.
This immediately creates a conundrum of how could this statement ever be true. The trick to solving this is that the same act also redefines what the common understanding is of the word "spouse" with the following definition:
spouse, in relation to an applicant, means a person who is legally married to that applicant if— (a) both of them are of or over 24; or (b) one or both of them are younger than 24 and at least 1 of them has a supported child
Technically the act has been drafted to exclude young married childless couples and it's this redefinition of the word spouse that provides an elegant example for us to consider.
Within OpenFisca the only limit to the ontology is that two terms cannot have the same name. Therefore when naming a term it's important to consider how it'll be perceived throughout the entire OpenFisca project. In the above example we would identify a short descriptive tag for the legislative instrument, in this case student_allowances would be quite appropriate shortening of the act's name Student Allowances Regulations 1998. We would then name the term "spouse" by the most appropriate word followed by its context.
student_allowances__has_a_spouse
The naming of things and the structure of the project is an essential and evolving process that will become more clear as more of Aotearoa's legislation is coded.
New Zealand legislation can be referenced on legislation.govt.nz. OpenFisca allows for direct referencing of parameters and variables. When creating a parameter or variable include a reference as you believe most appropriate. The following are some examples of how that can be done with respects to the "age of majority" defined in the Age of Majority Act 1970.
This could be considered the best approach for this particular example, given that the act is quite a small document.
description: Age of majority (in years)
reference: http://www.legislation.govt.nz/act/public/1970/0137/latest/whole.html#DLM396495
values:
1970-12-02:
value: 20.0Options include:
-
A link direct to the appropriate section of the whole act (as in the above example) http://www.legislation.govt.nz/act/public/1970/0137/latest/whole.html#DLM396495
-
A link direct to just the appropriate section (preferred for sections in large pieces of legislation) http://www.legislation.govt.nz/act/public/1970/0137/latest/DLM396495.html
-
A link to the whole piece of legislation (case of last resort) http://www.legislation.govt.nz/act/public/1970/0137/latest/whole.html
When working on computations, early consideration is needed to determine if the calculation should be based on a yearly or monthly period, see the OpenFisca docs on periods. A quick rule of thumb: if you think it's a year period ask yourself: has or would the legislation change within one of these year periods? If the answer is yes - then a month period is likely to be more appropriate.
For a technical understanding of parameters please reference docs.openfisca.org.
When inputting parameters it's a good idea to ignore the basic programmer instincts of removing "duplicate code". In the cases that an Act has been reenacted and the parameter in question didn't change, reiterate the value for each year it's reenacted regardless of its value changing. This gives readers of the code a more complete understanding of the parameter's history.
For a technical understanding of variables please reference docs.openfisca.org.
Variables allow for formulas, when writing for formulas be aware all calculations are vectorial as explained in the docs.
Start every formula with a test and work to build up the test case libraries with unique situations as they come to the fore. The opportunity to add new test cases to OpenFisca Aotearoa adds to the human orientated nature of the project. It allows for an increasingly nuanced response to the various circumstances faced by the people the project is designed to serve. The tests also add real world scenarios that researchers can include in their work when modelling the impacts various proposed scenarios might create.
Programmers may find the process of engaging with legislation as code a little frustrating at first. With lots of repeated values and lots of time spent considering the naming of things it can generate the sense that one is doing a really bad job of programming. The solution to this is to fully embrace the key purpose of the project and continually ask:
how will the legislation be best represented?
We actively welcome contributions, please start with CONTRIBUTING.md