RFC-044: One Regulation in YAML Is a Rulework

Context

The thing a jurist establishes and the engine executes had no name of its own. The repository used at least seven words for it. In Dutch: specificatie, wetsbestand, YAML-bestand and plain wet. In English: “law file”, “law YAML” and “specification”.

Each of them fails somewhere.

Specificatie carries two meanings on the roadmap. One is the specification of the language, the other is the machine-executable interpretation of one law. The werkpakket specificaties-i-documentatie-op-orde recorded which word belongs where as an open point.

Wet and “law” are wrong for part of the corpus. Of the 37 files under corpus/regulation, five are a ministerial regulation or a municipal ordinance, and so are six of the 81 in the demo corpus. The schema has thirteen regulatory layers, and most of them are not a wet.

Bestand, “file” and “document” name how the thing is stored. What a jurist signs off on is its content, and a regulation that changes gets a second file while it stays the same regulation.

Decision

A regelwerk is one regulation as it is recorded in the law format: its legal text, with the machine-executable interpretation beside it. It is identified by its $id.

A regelwerk has versions. Each version is one YAML file, named after the date its text took effect. A regulation that was amended once has one regelwerk with two versions. Several regelwerken together are a stelsel van regelwerken.

A regelwerk is written in the law format as a whole: its metadata, its division into articles, the legal text and the interpretation. The legal text is in it as a verbatim quotation. The format carries that text and gives it no meaning; only the machine-executable interpretation means something to an engine.

A regelwerk can be incomplete. The harvester writes one that holds only the legal text, and enrichment adds the interpretation.

What a regelwerk is not:

• The schema, the format or the language. A regelwerk is written in the law format and conforms to the schema. The word never becomes a prefix for any of them.
• The legal source. Wet, regeling and wettekst keep naming what the legislature laid down: “this comes straight from the wet” stays as it is. The regelwerk is the project’s record of that source.
• The corpus. That is the collection.

Code identifiers do not change. law_id, ArticleBasedLaw, the API routes, the law_entries table, the WASM API and the canonical Gherkin steps keep law. The word is vocabulary for prose and for user interfaces.

This RFC does not name the language.

Why

Benefits

• The double meaning of specificatie is gone. The word now means the specification of the language and nothing else.
• The name fits every regulatory layer, so an ordinance is no longer called a wet in the editor.
• It names the content. A regelwerk stays the same regelwerk when it gets a new version, or when it moves from files into a registry.
• It matches what the editor and the demo already list: one row per $id.
• Regelwerk is an existing Dutch word for a coherent body of rules, and read literally it says rules that work: they run, and what they compute takes effect in a decision. Whether the regelwerk itself has legal status is an open question; the werkpakket “Juridische status van een regelwerk” is about that.

Tradeoffs

• “Rulework” is a coinage. English nouns ending in “-work” are often uncountable (paperwork, casework), so “a rulework” may make a native speaker pause, and the plural can be misread as a plant, like waterworks. A native speaker has not reviewed it yet.
• RuleWorks is also the name of an older production-rule language, a descendant of OPS5. The fields are close enough that a search will find both.
• Regelwurk is a calque that no Frisian translator has seen. It is on the list for the Frisian reviser.
• The demo’s addresses now carry both coinages (/regelwerken, /en/ruleworks, /fy/regelwurken). An address is the hardest place to change a word later; the former paths redirect, and a later rename would add another set.
• Prose and code use different words for the same thing: “rulework” in a sentence, law in an identifier. Renaming the identifiers would touch the schema, more than 25 API routes, a database table and the WASM API, for no gain a user would notice.
• Accepted RFCs, RFCs by other authors and the published paper keep the older words. A reader who moves between those and the current docs meets both; the glossary row for rulework names the older ones.

Alternatives Considered

One file is one regelwerk

• The first version of this RFC defined a regelwerk as one version: one YAML file.
• Rejected in review. The editor and the demo list, add, enrich and favorite by $id, so the word would have counted the wrong unit on nearly every screen, and a second word would have been needed for the regulation across its versions.

Compounds on bestand or document

• Rechtsbestand, regelingbestand, regeldocument, and the wetsbestand a few RFCs already used.
• Rejected: they name the storage, and the last one also says wet.

Specificatie

• The word the roadmap used.
• Rejected: it already means the specification of the language.

Regelschrift, regeleditie

• Regelschrift for the language with regeleditie for one instance.
• Rejected: regelschrift does not say whether it is the schema or an instance.

Regelset

• A set of rules.
• Rejected: a set is unordered, and it does not say what the set is of. The English “ruleset” falls with it.

Regelalgoritme, rechtsalgoritme

• Proposed because “rule-based algorithm” is a term in use for systems like this one.
• Rejected: “algorithm” frames a published interpretation of a law as a technical artifact, which is the framing the project argues against.

Regelboekje, regelconfiguratie, regelnode

• Rejected as too informal, too technical, or a metaphor in place of a description.

Lezing

• A reading of the law, which is accurate: a regelwerk is an interpretation.
• Rejected as the main term: on its own it is ambiguous, and it says nothing about being executable.

English: the existing term unchanged

• The docs said “law file”.
• Rejected: it keeps both “law” and “file”.

English: regelwerk untranslated

• Dutch domain terms usually stay Dutch in English prose.
• Rejected: this word is used in nearly every paragraph, and an English reader needs to be able to read it aloud.

English: encoding, executable specification

• The published paper uses both.
• Rejected: “encoding” names the act, and “specification” brings the double meaning back.

Implementation Notes

• The glossary, the roadmap and the agent instructions use the word.
• The editor, the demo, the docs and the landing page use the word regelwerk. Screens a citizen reads in the demo (the portal, the loading text, the explanation of an outcome) keep wet and regeling: regelwerk is a word for the people who make and review them. The proofs of concept and their MCP tools still say regelgevingsdocument, the Dutch harvester screens still say wet, and the task skills under .claude/skills/law-* still say “law YAML”.
• What a regelwerk for a bill is called, before there is a date of entry into force, is not settled here.
• The section on the top-level keys in /reference/schema is headed “The rulework”. Its anchor did not change, so existing links hold.
• Werkpakket titles changed; their slugs did not. A slug is a reference that other pages and merged pull requests carry.
• The demo moved its tab from /wetten to /regelwerken, /en/ruleworks and /fy/regelwurken. The old paths redirect.
• The prose linter next to the docs-writing skill rejects the two older compounds on bestand and “file” in the docs pages, the roadmap and the landing copy, and rejects a compound of regelwerk with schema, format or language in everything it scans: the docs content, the RFCs, the roadmap and the landing copy. Components, the README and UI strings are outside its reach. It does not check RFCs for the older words, because an RFC is a dated document, and it cannot tell the two meanings of “specification” apart.