Adding a Law

Adding a new law to the corpus takes six steps, from downloading the legal text to running tests against it.

Step 1: Find the law

Every Dutch national law has a BWB ID (format: BWBR + 7 digits). Find it on wetten.overheid.nl.

For example, the Zorgtoeslagwet is BWBR0018451.

Step 2: Harvest the legal text

Use the harvester to download and convert the law from BWB XML to YAML:

This produces a YAML file with the law’s text but no machine_readable sections. The output path follows the convention: corpus/regulation/nl/{layer}/{slug}/{date}.yaml.

Step 3: Add machine-readable logic

Each article that contains executable logic needs a machine_readable section. This can be done:

• Manually - write the machine_readable YAML by hand following the law format
• Via the pipeline - trigger an enrichment job through the admin dashboard, which uses an LLM to generate candidate interpretations

If using LLM-generated interpretations, always validate the output (step 5).

Step 4: Validate against the schema

The validator rejects files with an unknown or missing $schema version. Make sure the $schema URL uses a tag-based ref (refs/tags/schema-vX.Y.Z) and points to a released schema version.

The tag is what makes that URL a promise rather than a hope: it pins the schema your law validated against, and it cannot move afterwards. A schema version is tagged automatically when it lands on main, and CI blocks a version that has no tag, so the address a law file cites always resolves.

Fix any schema errors before proceeding.

Step 5: Write BDD test scenarios

Derive test scenarios from the Memorie van Toelichting (MvT), the explanatory memorandum that accompanies the law. The MvT contains worked examples of how the legislature intended the law to be applied.

A law’s scenarios live next to the law, in a scenarios/ directory beside the YAML file: corpus/regulation/nl/wet/your_law/scenarios/eligibility.feature. That is bucket A, the law-validation bucket, described in Testing.

The step vocabulary is not free text. bdd/grammar.yaml is the single source of truth, and the bindings are generated from it, so a step that is not in that file does not exist. A minimal scenario:

Laws that need source data (BRP, Belastingdienst, and the like) provide it with a data-table step keyed on the identifier the law looks up:

See corpus/regulation/nl/wet/wet_op_de_zorgtoeslag/scenarios/eligibility.feature for a complete, data-driven example.

Run the tests:

Step 6: Open a pull request

Commit the new law file, any BDD scenarios, and open a PR. CI will run schema validation, BDD tests, and all other checks automatically. Add the deploy:preview label to the PR if reviewers should be able to try the law in a running editor.

End the PR body with a Werkpakket: line, which a required check enforces, and add a Wet: line naming the law’s $id:

See Contributing for what both lines mean and how the slug is checked.

Further reading

• Law Format - how to structure the YAML
• Testing - more on writing and running tests
• Validation Methodology - the execution-first validation approach