How to code rules and legislation
Rules As Code (RaC) is the process of taking legislation, regulations and policies and turning them into machine-readable code. Read more about RaC in our insight, What is Rules As Code?
A RaC project should have three main streams:
- Rules analysis and mapping
- Rules coding using OpenFisca
- The customer experience (an application that calls the rules, e.g. a website)
Rules analysis and mapping
Analysing and mapping the rules can be done in a variety of ways, both in terms of the tools used (e.g. Miro vs diagrams) and the process itself.
Ultimately, the path you choose will be dictated by the rules content and by personal preference. In our most recent RaC project, we found it useful to break the analysis and mapping into five stages:
- Initial analysis of the rules (high level)
- Mapping by a user flow/journey model
- Mapping by eligibility logic
- Writing test cases
- Writing rules statements
However, these steps can also happen simultaneously. For example, you can write the rules statements during the mapping process, and test cases can also be written as you go, gradually increasing the number of test cases.
In the GovZero project we’re currently working on, these steps were done as one mapping process, which also included calculation logic (to work out people’s entitlements for social security benefits).
Other optional methodology includes creating concept models and decision models.
In this section, we’ll talk about all of these options so you can make an informed choice for your RaC project.
Initial analysis of the rules
In this first pass, you analyse the rules and extract key takeaways (key rules) in logical groupings. The groupings will be determined by the rules you’re coding. For example, if you’re coding social security entitlements, a logical grouping would be by entitlement.
This process should be done by an RaC expert/RaC business analyst. Subject matter experts can be involved during this process as either active participants (helping to analyse the rules) or consultants (to ensure the rules have been correctly captured).
Below is a screenshot from a recent Miro board we did capturing rules by age. In this Miro ‘frame’ we pulled out all the relevant information from a set of written rules, rewriting them in plain English and using different coloured Notes to capture different elements.
Note: The content is intentionally blurred for client confidentiality.
In contrast, below is a screenshot from the Miro board we’re using as part of the GovZero RaC project.
In this case we’re looking at the New Zealand Social Security Act. An extract of the Act is on the left, and on the right we’ve completed the rules mapping process. Our analysis included mapping the logic.
Mapping a high level model (user journey/flow)
If you’re stepping out the mapping process, after the initial capture of the rules in plain English you can map a user journey/flow through the rules. During this stage you're capturing the entities (persons, groups, etc.), legislative requirements, eligibility logic and calculation logic. As you go, you can also write down the questions the end user will need to be asked — these questions become quite obvious during the mapping process.
Again, this mapping should be done by an RaC business analyst working with subject matter experts.
Below is a screenshot showing a user journey mapping with the related logic. This follows a user based on age, showing their user journey using a series of questions, including yes/no questions (which output true/false values), questions that output dates and questions that output a number value.
Note: The content is intentionally blurred for client confidentiality.
Mapping a logic/decision model
The final mapping stage is the logic/decision model. This model needs to:
- Match machine-consumable legislation
- Identify user variables and parameters
- Capture obligations
- Capture definitions
- Create the calculation logic (if applicable)
This can be done as one larger step (see the GovZero screenshot above) or as the final step in the mapping process.
Below is an example of eligibility logic in Miro. In this model, rather than mapping users within a specific age range through their journey, we start off with what needs to be true for a person to be eligible.
Note: The content is intentionally blurred for client confidentiality.
Variables and definitions
During the rules analysis and mapping process, as well as pulling out eligibility criteria, you’re also notating definitions, if necessary.
Global variables and definitions can be coded once across multiple legislation or parts of legislation. For example, some global variables from the GovZero RaC project include:
- Definition of restricted work capacity
- Residency requirement
- Definition of single
- Definition of assets for the assets test
Global variables and definitions can be set up in a dedicated section of Miro and then copied and pasted into the relevant areas of the Miro board.
Calculation logic
The rules analysis also looks at calculation logic and payment rates (if applicable). To track the different payment types for the GovZero project, we used a spreadsheet. As you can see from the screenshot below, the supported living payment is quite complex, with many variables determining the rate, plus the application of two different income tests.
Concept models
Some RaC working groups like to create concept models during the rules analysis and mapping process. Concept models pull out the concepts and variables identified in the legislation/rules analysis and turn them into a diagram.
The concept model below is a simplified version of Australia’s Dad and Partner . It takes into account some of the eligibility parameters to provide an indicative view of a concept model.
Decision models
Decision models/logic can also be mapped in a diagram. Decision models cover the key questions for eligibility. Below is a partial representation of the decision model for the Dad and Partner Pay.
Test cases for test-driven development
Most RaC projects use test-driven development, drawing on written test cases. Test cases call out the input variables and the expected result. These test cases are then run during the OpenFisca coding to ensure the rules engine is returning the expected results. If a test case fails, then the rules will be adjusted to ensure that all rules are properly captured.
Ideally, the test cases should cover all permutations of variables, focusing on threshold edge cases and crossing boundaries.
Below is an example of what test cases might look like on a Miro board.
Note: The content is intentionally blurred for client confidentiality.
Rules statements
The final stage before coding is creating rules statements. Rules statements are a simple set of rules in plain English. These should be verified by subject matter experts.
Below is an example of rules statements for Australia’s Dad and Partner .
A claimant is eligible for Dad and Partner payment if all of the following are true:
The claimant is an Australian citizen or permanent resident living in Australia.
The claimant will be caring for the child on every day during the benefit period.
The claimant is the biological father, partner of birth mother, adoptive parent, partner of adoptive parent or caring for a child born from surrogacy.
The claimant has worked 10 of the 13 months before the date their Dad and Partner Pay period starts.
The claimant has worked a minimum of 330 hours, around 1 day a week, in that 10-month period.
The claimant has earned $150,000 or less in the 2019-20 financial year OR 151,350 or less in the 2020-21 financial year
The claimant will NOT be working during the benefit period.
The claimant will NOT be on paid leave during the benefit period
The claimant will NOT be receiving Jobkeeper during the benefit period.
The claimant will NOT be receiving the COVID-19 Disaster Payment during the benefit period.
Rules coding using OpenFisca
The process to codify rules follows four main steps:
- Create test scenarios
- Create entities
- Create parameters
- Create variables
- Input
- Output (formulas)
The screenshot below shows an example of setting up the test scenarios in OpenFisca/code.
The next step is to create entities in OpenFisca, e.g. a ‘Person’. The screenshot below shows the entity creation in OpenFisca.
Next is to create the required parameters. A parameter is a property of the rule that changes over time. For example, a parameter might be min_age_of_eligibility. And the variable attributes are:
- Description
- Metadata
- Reference
- Unit
- Values
Finally, the variables are set up. Variables are properties of a person or an entity (e.g. a family). They cover:
- Inputs
- Outputs (formulas)
The customer experience
The final step (although this should be done at the same time as (or even before) the coding process) is to set up a frontend or application that calls the rules from OpenFisca. This could be a website, chatbot, voice app, or phone app.
Looking at web interfaces, currently RaC projects around the world are using different frontend technologies and content management systems to build a website interface. For example, existing projects have used:
The user interface (UI) should start with user analysis and testing. Once initial analysis is complete, a service designer/user interface designer can create wireframes that model different potential UIs and pathways within the site. A second round of testing will help iterate the designs to ensure the final product is user-centric.
Our OpenFisca insight provides more information on current RaC projects, but you can also view some different web interfaces using the website links below: