Skip to content
RUMLRUML

Open Format for Digital Law

08. Validation

8.1 Overview

This chapter is the catalogue of validation rules for RUML documents. Every rule has a stable id of the form <PREFIX>-<NN>; the sections group the rules by subject, and within a section the rules are sorted by id. Implementations, error messages and test suites SHOULD cite these ids rather than restate the rule text, so that a violation can be identified independently of language or wording.

A parser MUST reject a document that violates a rule of this catalogue. A rule that says “a parser MUST accept …” states what the specification permits (MAY): a parser that rejects such a document violates the rule. Rules of the layer — bind the tool that reads, writes or evaluates a file; they are not properties of the file.

Validation Layers

  • schema: the rule can be checked by validating the document against the RUML JSON Schema alone. This includes the format keywords of the schema, such as date-time, uri and regex; a validator that does not assert formats does not check those parts.
  • semantic: the rule needs logic beyond the schema, such as resolving references, comparing values or checking uniqueness across the document.
  • —: the rule depends on the tool, for example on the capabilities it implements or on how it writes a file, and cannot be decided from the document alone.

A validation tool MUST check every rule of the layers schema and semantic (Rule CAP-28CAP-28 A validation tool MUST check every rule of this catalogue whose layer is schema or semantic.).

Rule Ids

A rule id is never reused. A rule that is withdrawn keeps its row, marked Retired, and its id is not given to another rule.

JSON Schema

The JSON Schema is the normative structural definition of the format. It is maintained as a file and is not restated here:

  • Interactive explorer: RUML JSON Schema
  • Source: schemas/ruml.schema.json (draft 2020-12); RUML-EXT files are validated by schemas/ruml-ext.schema.json
  • Packages: @law-as-code-institute/ruml-schema (npm), ruml-schema (PyPI)

The spec version the schema describes is carried in its x-ruml-spec-version annotation and mirrored by the $specVersion value every conforming file MUST declare.

8.2 Scope

This catalogue covers the RUML document (.ruml) and the obligations of the tools that read, write and evaluate it, including the obligations of a parser that processes RUML-EXT files (CAP-22 to CAP-27). It does not cover:

  • the result file .ruml-result (Chapter 5);
  • the RUML container, its hashes and signatures (Chapter 7);
  • the requirements of Chapter 4.5 on RUML-EXT files other than the parser obligations;
  • the contract of a spec-test runner (Appendix A).

For ruml:draft/ and reverse-domain capabilities, the extension points of Chapter 4.1, this catalogue covers their declaration and use in the document – id, role and required at the root, where and how often an entry may appear, and that a node entry has a payload – but not the content of the payload, which is defined by the parser and evaluator that implement the capability.

8.3 File Format Rules

Rules derived from Chapter 2 and Chapter 3.2.

Rule§LayerRequirement
FMT-012.1, 3.2.3semanticThe file MUST be encoded in UTF-8.
FMT-022.1, 2.2, 3.8semanticThe file MUST be valid JSON (RFC 8259), and its root MUST be an object.
FMT-032.2, 2.6schema$format MUST be "RUML".
FMT-042.2, 2.3schema$specVersion MUST be one of the versions listed in the enum of $specVersion in the schema.
FMT-052.2semantic$format and $specVersion MUST be the first two fields of the root object.
FMT-062.2schemaThe root object MUST have metadata and rulemap; a parser MUST accept it with or without capabilities.
FMT-072.2schemaThe root object MUST NOT have fields other than $format, $specVersion, metadata, capabilities and rulemap.
FMT-082.2, 2.5, 2.6, 3.4.1, 3.5.1schemarulemap.nodes MUST contain an entry with key "1", the root node.
FMT-092.3, 2.6—A parser MUST accept a file whose $specVersion has its own MAJOR version and a MINOR version up to its own, and MUST reject a file with a higher MINOR version or a different MAJOR version.
FMT-102.5, 2.6, 3.5.2schemaEvery UUID MUST be a lowercase UUID version 4 (pattern in 2.5).
FMT-112.5, 3.1, 3.5.3schemaEvery key of rulemap.nodes and every entry of children MUST be a LexID, a string matching ^[1-9][0-9]*$.
FMT-122.5, 2.6semanticA LexID MUST NOT occur more than once as a key of rulemap.nodes.
FMT-132.6, 3.2.3, 3.8schemaEvery field value MUST have the data type 3.2.3 gives it: a Number a JSON number, a Boolean a JSON Boolean, a DateTime an RFC 3339 date-time, an Enum one of the values defined for the field, an Object a JSON object, an Array a JSON array.
FMT-143.2.6schemaA DataPoint, text entry or context entry MUST NOT have an id field; its key is its id.

8.4 Metadata Rules

Rules derived from Chapter 3.3.

Rule§LayerRequirement
META-013.3.1, 3.8schemametadata MUST have id, version, created, modified and status.
META-023.3.1, 3.3.3schemastatus MUST be one of the seven values of 3.3.3.
META-033.3.1semanticmodified MUST NOT be earlier than created.
META-043.3.2, 3.3.5schemaA parser MUST accept each optional field of 3.3.2 and derivedFrom.originalHash, present or absent, including replaces and replacedBy together.
META-053.3.2, 3.3.6schemadocumentType MUST be one of the values of 3.3.6.
META-063.3.2schemaauthors MUST have at least one entry, and every entry MUST have name.
META-073.3.2semanticjurisdiction MUST begin with an ISO 3166-1 alpha-2 country code; a parser MUST accept hyphen-separated subdivisions after it.
META-083.3.2semanticlanguage MUST be an ISO 639-1 code.
META-093.3.2semanticWhen both are set, validUntil MUST be later than validFrom.
META-103.3.3schemaStatus inForce MUST have validFrom.
META-113.3.3semanticStatus expired MUST have validUntil, and it MUST lie in the past.
META-123.3.3schemaStatus replaced MUST have replacedBy.
META-133.3.5schemaderivedFrom MUST have originalId, originalStatus, derivationType and derivedAt.
META-143.3.5semanticA working copy (derivedFrom.derivationType: "workingCopy") MUST NOT have status inForce.

8.5 Rulemap and Node Rules

Rules derived from Chapters 3.1, 3.4 and 3.5.

Rule§LayerRequirement
NODE-012.2, 3.2.6, 3.5.2schemaA node MUST have id and label.
NODE-023.1, 3.4.1schemarulemap MUST have nodes, an object whose values are node objects.
NODE-033.1, 3.2.6, 3.5.1, 3.5.2schemaA node MUST NOT have fields other than those of 3.5; in particular it MUST NOT store its LexID (lexId), its parent or its type.
NODE-043.1—A tool that writes a file MUST keep the order of every children array.
NODE-053.5.1semanticThe root node "1" MUST NOT appear in any children array.
NODE-063.5.1schemachildren MUST NOT be empty.
NODE-073.5.2a, 3.5.3, 3.6, 3.6.4, 3.6.5schemaA parser MUST accept the optional node fields of 3.5.3, present or absent, except operator on a leaf node: a leaf node MUST NOT have operator unless metadata.status is draft; in a draft, a parser MUST accept any of the eight operators of 3.6 on a leaf node.
NODE-083.5.2, 3.8semanticThe id of a node MUST NOT equal the id of another node or metadata.id.
NODE-093.5.2schemalabel MUST NOT be empty.
NODE-103.5.3, 3.8semanticEvery entry of children MUST be a key of rulemap.nodes.
NODE-113.5.3schemadescription MUST NOT exceed 10,000 characters.
NODE-123.5.2aschemaA node with children MUST have operator.

8.6 Operator Rules

Rules derived from Chapter 3.6.

Rule§LayerRequirement
OP-013.5.2aschemaoperator MUST be one of the eight values of 3.6.
OP-023.6.4, 4.1, 4.3, 4.14semanticOutside a draft, a node with operator: "DELEGATED" MUST have children. A node with operator: "DELEGATED" and children MUST have exactly one entry of a capability with the combiner role; for a ruml:draft/ or reverse-domain capability, the role is the one declared at the root. In a draft, a parser MUST accept that operator on a leaf node without a combiner (NODE-07).
OP-033.6.4—An evaluator MUST NOT short-circuit a node with operator: "DELEGATED"; it evaluates every child before the combiner runs.
OP-043.6.4, 4.14semanticThe node-level payload of a combiner MUST have a non-empty prose description.
OP-053.6.4, 4.14semanticA parser MUST accept a combiner that uses non-deterministic input, including a ruml:expression that calls $random, $now, $millis or $eval.
OP-063.6.4semanticA parser MUST accept any capability declared at the root with the combiner role, including a reverse-domain one, as the combiner of a DELEGATED node.
OP-073.6.5schemaoperator: "undefined" MUST NOT occur unless metadata.status is draft; in a draft, a parser MUST accept it.

8.7 Capability Rules

Rules derived from Chapter 4, including the parser obligations for RUML-EXT files (4.5). For those, the schema is schemas/ruml-ext.schema.json.

Rule§LayerRequirement
CAP-011.4, 4.1, 4.2semanticA parser MUST reject a file that declares a capability with required: true that the parser does not implement, and MUST NOT process such a file partially.
CAP-024.1, 4.2semanticA parser MUST accept a file that declares a capability it does not implement with required: false or without required, and MUST ignore the payload and the node-level entries of that capability.
CAP-034.1, 4.2, 4.4schemaThe root entry of a ruml:draft/ or reverse-domain capability MUST declare role.
CAP-044.1, 4.4semanticA parser that implements a ruml:draft/ or reverse-domain capability MUST reject the file if the declared role differs from the role it implements.
CAP-054.1schemaThe root entry of an official ruml: capability MUST NOT declare role.
CAP-064.1, 4.3semanticOn one node, a capability with the data role MUST NOT have more than one entry; a parser MUST accept several entries of a capability with the decision or reaction role.
CAP-074.1, 4.3, 4.8, 4.16semanticAn entry of a capability with the decision role MUST NOT appear on a node with children.
CAP-083.6.4, 4.1, 4.14semanticAn entry of a capability with the combiner role MUST NOT appear on a node whose operator is not DELEGATED.
CAP-094.2schemaEvery entry of the root capabilities MUST have id; a parser MUST accept required and payload in it.
CAP-104.2semanticAn id MUST NOT occur more than once in the root capabilities.
CAP-114.2, 4.14schemaThe root entry of ruml:expression MUST have required: true.
CAP-124.2semanticThe data of a root entry’s payload MUST be an object keyed by id; a parser MUST accept a payload with data, config or both where the capability provides for them.
CAP-134.2—A parser that implements a capability MUST validate its payload.data and payload.config against that capability’s specification.
CAP-144.2schemaWhen the root capabilities is absent or empty, a node MUST NOT have capabilities.
CAP-153.5.3, 4.2, 4.3, 4.8, 4.9, 4.15semanticThe id of every entry of a node’s capabilities MUST be declared in the root capabilities.
CAP-164.3, 4.14schemaA parser MUST accept capabilities on any node, and entries of capabilities with the data or reaction role on any node, in any order, also beside the combiner of a DELEGATED node.
CAP-173.5.3, 4.3schemaEvery entry of a node’s capabilities MUST have id and payload, and payload MUST be an object.
CAP-184.3, 4.13schemaruml:protocol MUST NOT appear in a node’s capabilities, neither inline nor in a RUML-EXT file.
CAP-194.3schemaA parser MUST accept decisionMode on a node with children and MUST ignore it there.
CAP-204.3—A tool that writes a file MUST NOT reorder the entries of a node’s capabilities.
CAP-214.4schemaA capability id MUST be a ruml: id defined by this specification version, a ruml:draft/<name> id or a <reverse-domain>/<name> id; it MUST consist of lowercase letters, digits, _, - and the delimiters, and MUST NOT exceed 128 characters.
CAP-224.5schemaThe $format of a RUML-EXT file MUST be "RUML-EXT"; a parser MUST check it before it processes the file further.
CAP-234.5schemaThe root of a RUML-EXT file MUST NOT contain metadata or rulemap.
CAP-242.6, 4.5semanticBefore a merge, the $base.id of a RUML-EXT file MUST equal the metadata.id of the base file, and its $base.hash the hash of the base file’s canonical form; otherwise the parser MUST abort the merge. Each RUML-EXT file is checked on its own.
CAP-254.5—A parser MUST NOT skip the $base comparison, not even in a development environment or on an explicit user override.
CAP-262.6, 4.5semanticEvery node UUID in the nodes of a RUML-EXT file MUST be the id of a node of the base file.
CAP-274.5semanticThe same capability MUST NOT be defined for the same node both inline and in a RUML-EXT file, nor in two RUML-EXT files of the same base file; a parser MUST accept several RUML-EXT files for one base file.
CAP-284.6—A validation tool MUST check every rule of this catalogue whose layer is schema or semantic.
CAP-294.8semanticA node’s ruml:query payload MUST have expression, a valid JSONata expression; a parser MUST accept description in it.
CAP-304.9schemaA node’s ruml:ai-query payload MUST have model; a parser MUST accept prompt, description, inputs and config in it.
CAP-314.9schemaA parser MUST accept context, dataPoints and texts in the inputs of a ruml:ai-query payload; an object entry of context MUST have id, and a parser MUST accept role (reference or subject) in it.
CAP-324.9schemaA parser MUST accept deterministic (a Boolean), effort (low, medium or high) and temperature (a number from 0 to 1) in the config of a node’s ruml:ai-query payload, and systemPrompt in the config of its root payload.
CAP-334.9schemaA parser MUST accept a leaf node that has both ruml:query and ruml:ai-query.
CAP-344.10schemaA parser MUST accept ruml:actions on any node, also as its only capability.
CAP-354.10schemaA node’s ruml:actions payload MUST have at least one of onTrue, onFalse and onUndefined; an action MUST have operation and ref, and a parser MUST accept description in the payload, config in an action and any string as operation.
CAP-364.13schemaA parser MUST accept config.level with the value standard or verbose in the root payload of ruml:protocol.
CAP-374.14schemaruml:expression MUST NOT appear in a RUML-EXT file.
CAP-384.14semanticA node’s ruml:expression payload MUST have a non-empty expression, a valid JSONata expression.

8.8 DataPoint Rules

Rules derived from Chapter 4.7.

Rule§LayerRequirement
DP-014.7schemaA DataPoint MUST have name, type and binding, and type MUST be one of the data types of 4.7.1.
DP-021.2, 4.7, 4.7.4schemaThe key of a DataPoint, the id of a set and the keys of a set’s fields MUST match the pattern [a-z_][a-z0-9_]*.
DP-034.7schemaA parser MUST accept description, validation and sensitive on any DataPoint, unit for number and percentage, format for location, identifier and address, and cardinality for object.
DP-044.7, 4.7.3schemaA DataPoint MUST NOT have unit, format, options, set or cardinality, nor a validation rule, that 4.7 and 4.7.3 do not provide for its type.
DP-054.7, 4.7.1schemaA DataPoint with type: "currency" MUST have unit.
DP-064.7, 4.7.1schemaA DataPoint with type: "enum" MUST have a non-empty options, and every option MUST have value.
DP-074.7schemaA DataPoint with type: "object" MUST have set.
DP-084.7, 4.7.3schemacardinality.min MUST be an integer of at least 0 and cardinality.max an integer of at least 1; minLength and maxLength MUST be integers from 0 to 253 − 1.
DP-094.7.2schemaA parser MUST accept hint, placeholder and defaultValue in an input binding; description, sourceType and fallback in an external binding; and description in a computed binding.
DP-104.7.2schemaAn external binding MUST have ref.
DP-114.7.2semanticA computed binding MUST have expression, a valid JSONata expression; a parser MUST accept one that reads other DataPoints, including computed ones.
DP-124.7.2semanticThe references between computed DataPoints MUST NOT form a cycle, directly or transitively.
DP-134.7.3schemavalidation.pattern MUST be a valid ECMA-262 regular expression.
DP-144.7.3schemavalidation.min and validation.max MUST have the type 4.7.3 gives for the data type.
DP-154.7.4schemaAn entry of sets MUST have name and fields; a parser MUST accept description in it and a DataPoint of type: "object" among its fields.
DP-164.7.4semanticThe set of a DataPoint MUST be the id of an entry of sets.
DP-174.7.4semanticA set MUST NOT reference itself, directly or transitively.
DP-184.8, 4.9, 4.14semanticEvery DataPoint id that the expression of a ruml:query or of a ruml:expression reads, and every id in inputs.dataPoints of a ruml:ai-query, MUST be a key of the data of ruml:datapoints.

8.9 Text Reference Rules

Rules derived from Chapter 4.12.

Rule§LayerRequirement
TXT-014.12schemaThe payload of a node’s ruml:text-reference entry MUST have refs with at least one anchor. An anchor MUST have id and type (represents or refers-to) and MUST NOT have fields other than these and element (a lowercase UUID), which a parser MUST accept; a node MUST NOT have more than one represents anchor, and the same anchor MUST NOT appear twice.
TXT-024.12schemaA text key MUST match the pattern [a-z_][a-z0-9_]*.
TXT-034.12—A text key MUST NOT change once anchors may point at it, and the GUID of an element MUST NOT change; a tool that imports a new version of a text MUST carry the GUID of every element it matches forward.
TXT-044.12schemaA text entry MUST have title and timestamp, and status unless it has content.
TXT-054.12semanticIn a text entry, timestamp and validFrom MUST be RFC 3339 date-times, url a URI and language an ISO 639-1 code.
TXT-064.12schemaA parser MUST accept a text entry with any of the optional fields type, text, content, version, validFrom, validUntil, language and isReferenced.
TXT-074.12schemaA text entry MUST NOT have both text and content; an embedded entry with status inForce MUST have a non-empty text or a content.
TXT-084.12schemaA text entry with content MUST have digest, sha3-256: followed by 64 lowercase hexadecimal digits.
TXT-094.12semanticdigest MUST equal the SHA3-256 hash of the UTF-8 bytes of the RFC 8785 form of content.
TXT-104.12schemaA text entry with type url, container or external MUST have url, containerPath or ref respectively.
TXT-114.12schemaThe containerPath of a text entry MUST start with .texts/.
TXT-124.12semanticWhen a text entry has both, validUntil MUST be later than validFrom.
TXT-134.12semanticIn a text entry with content, status, validFrom, validUntil, language and version MUST agree with the metadata of the text itself.
TXT-144.12semanticIn content, a content array MUST NOT contain two adjacent strings.
TXT-154.12schemaThe root of content MUST have type, attrs and content, and MUST declare the namespace of its dialect as its default namespace (attrs.xmlns).
TXT-164.12semanticIn content, every element with an eId MUST have a GUID, a lowercase UUID, unique within the entry; an element other than the root MUST NOT declare xmlns; every namespace prefix MUST be declared by an xmlns:<prefix> attribute on the element or an ancestor; and an element MUST NOT have xsi:schemaLocation.
TXT-174.12—A tool that writes RUML Text MUST keep the elements and attributes of every namespace, including those it does not understand, and MUST NOT add sentence markers that the source does not contain.
TXT-184.12semanticConverted to XML, content MUST be valid against the schemas of the dialect its root namespace names; a fragment MUST be valid where it stands in a complete document.
TXT-194.9, 4.12semanticEvery id of an anchor in the refs of a node’s ruml:text-reference entry, and every id in inputs.texts of a ruml:ai-query, MUST be a key of the data of ruml:text-reference.
TXT-204.12semanticThe element of an anchor MUST be the GUID of an element in the content of the entry its id names; an anchor into an entry without content MUST NOT have element.

8.10 Context Rules

Rules derived from Chapter 4.11.

Rule§LayerRequirement
CTX-014.11schemaA context entry MUST have title, category and timestamp.
CTX-024.11schemacategory MUST be one of the categories of 4.11.1.
CTX-034.11, 4.11.2schemaIn a context entry, timestamp MUST be an RFC 3339 date-time, accessDate an RFC 3339 date and url a URI.
CTX-044.11schemaA context key MUST match the pattern [a-z_][a-z0-9_]*.
CTX-054.11schemaThe same context id MUST NOT appear more than once in the refs of a node’s ruml:context entry.
CTX-064.11schemaA parser MUST accept a context entry with any of the optional fields type, subject, metadata, content, source, hash and accessDate, the last two with any type.
CTX-074.11, 4.11.2schemaA context entry with type url, container or external MUST have url, containerPath or ref respectively.
CTX-084.11schemahash MUST be sha3-256, sha256 or blake3, then :, then 64 lowercase hexadecimal digits.
CTX-094.11.2schemaThe containerPath of a context entry MUST start with .context/.
CTX-104.9, 4.11semanticEvery id in the refs of a node’s ruml:context entry, and every context id in inputs.context of a ruml:ai-query, MUST be a key of the data of ruml:context.

8.11 Modular Node Rules

Rules derived from Chapter 6.

Rule§LayerRequirement
MOD-013.5.3, 6.2, 6.4semanticA node whose LexID appears more than once in the children arrays of the rulemap (a self-reference counts) MUST have modular: true.
MOD-026.4semanticA parser MUST accept a modular node that lists its own LexID in its children (recursion).
MOD-036.4—A processor MUST warn about a recursive node whose operator is AND, NOT_AND, OR or NOT_OR; the warning alone does not make the file invalid.
MOD-046.4semanticA self-reference MUST NOT be the first entry of children.
MOD-056.4semanticA recursive node MUST have at least one child that is not a self-reference.
MOD-066.5semanticA parser MUST accept a modular node among the children of another modular node, also when it is referenced elsewhere.

8.12 Tree Reference Rules

Rules derived from Chapters 4.15 and 4.16.

Rule§LayerRequirement
TREE-014.15, 4.16schemaThe root entries of ruml:tree-reference and ruml:tree-include MUST NOT have a payload. A node’s ruml:tree-reference payload MUST contain represents, refersTo (with at least one entry) or both, and represents and every refersTo entry MUST have exactly uri; a node’s ruml:tree-include payload MUST contain uri. Both payloads MUST NOT contain other fields.
TREE-024.15, 4.16schemaEvery uri of a tree reference or inclusion MUST be a node anchor <ruml-version-uri>#node/<id>; a same-document anchor (#node/…) is not one.
TREE-034.15schemaThe same uri MUST NOT appear twice in refersTo.
TREE-044.15, 4.16semanticThe target node of a node anchor MUST exist in the referenced version.
TREE-054.15semanticA parser MUST accept ruml:tree-reference entries that form cycles across files.
TREE-064.15, 4.16semanticA node anchor MUST name an immutable RUML version; a file that is exported or exchanged MUST NOT contain an anchor without a version. All node anchors of a file into the same other RUML file MUST use the same version of it.
TREE-074.15schemaA parser MUST accept a node that has ruml:text-reference anchors besides a ruml:tree-reference entry.
TREE-084.16schemaA node with ruml:tree-include MUST NOT have represents in its ruml:tree-reference.
TREE-094.16semanticInclusions MUST NOT form a cycle across files, directly or through further files.