3.3 Metadata Object
3.3 Metadata Object
The metadata object contains all information about the RUML file itself.
3.3.1 Required Fields
| Field | Type | Description |
|---|---|---|
id | UUID | MUST be a unique identification of the RUML file (Rule META-01META-01 metadata MUST have id, version, created, modified and status.) |
version | String | MUST specify the content version (Rule META-01META-01 metadata MUST have id, version, created, modified and status.). Free-form, like a container image tag; SHOULD match [A-Za-z0-9_][A-Za-z0-9._-]{0,127} so it can serve as the version tag of a RUML URI (…/<name>:<version>). Rulemaps SHOULD use Semantic Versioning; files with documentType: "law" SHOULD use the date of the law version (YYYY-MM-DD, with .n for a further version on the same day) |
created | DateTime | MUST specify the creation timestamp (Rule META-01META-01 metadata MUST have id, version, created, modified and status.) |
modified | DateTime | MUST specify the timestamp of the last modification (Rule META-01META-01 metadata MUST have id, version, created, modified and status.). MUST be >= created (Rule META-03META-03 modified MUST NOT be earlier than created.) |
status | Enum | MUST specify the status of the regulation (Rule META-01META-01 metadata MUST have id, version, created, modified and status.). MUST be one of the defined status values (Rule META-02META-02 status MUST be one of the seven values of 3.3.3.) |
3.3.2 Optional Fields
| Field | Type | Description |
|---|---|---|
title | String | MAY contain a human-readable title of the rulemap. |
description | String | MAY contain a short description of the rulemap. |
documentType | Enum | MAY classify the document type. MUST if present be one of the defined values (Rule META-05META-05 documentType MUST be one of the values of 3.3.6.). See Section 3.3.6 for the complete value list. |
authors | Array[Object] | MAY contain a list of authors. MUST if present contain at least one entry (Rule META-06META-06 authors MUST have at least one entry, and every entry MUST have name.). Each object MUST contain a name field (String) (Rule META-06META-06 authors MUST have at least one entry, and every entry MUST have name.). The fields email (String, RFC 5321) and organization (String) are optional. Note: authors[].organization refers to the institutional affiliation of the author — not the publishing organization of the document (see organization). |
organization | String | MAY specify the publishing organization (who is institutionally responsible for the document). Note: Difference from authors[].organization: This field describes responsibility for the document, not an individual’s affiliation. |
jurisdiction | String | MAY specify the jurisdiction. MUST begin with an ISO 3166-1 alpha-2 country code (Rule META-07META-07 jurisdiction MUST begin with an ISO 3166-1 alpha-2 country code; a parser MUST accept hyphen-separated subdivisions after it.). MAY contain hyphen-separated subdivisions (Rule META-07META-07 jurisdiction MUST begin with an ISO 3166-1 alpha-2 country code; a parser MUST accept hyphen-separated subdivisions after it.). Format: "CC" or "CC-XX" or "CC-XX-YY-...". Examples: "DE", "DE-BY", "DE-BY-M", "DE-BY-09162". |
legalDomain | String | MAY specify the legal domain. |
tags | Array[String] | MAY contain categorization/tagging. |
derivedFrom | Object | MAY contain information about the origin. MUST be used for working copies. |
language | String | MAY specify the language. MUST conform to the ISO 639-1 format (e.g., "de", "en") (Rule META-08META-08 language MUST be an ISO 639-1 code.). |
validFrom | DateTime | MAY specify the validity start date. |
validUntil | DateTime | MAY specify the validity end date. If both validFrom and validUntil are set, validUntil MUST be > validFrom (Rule META-09META-09 When both are set, validUntil MUST be later than validFrom.). |
replaces | UUID | MAY reference a replaced version. MAY be used together with replacedBy (Rule META-04META-04 A parser MUST accept each optional field of 3.3.2 and derivedFrom.originalHash, present or absent, including replaces and replacedBy together.). |
replacedBy | UUID | MAY reference a successor version. MAY be used together with replaces (Rule META-04META-04 A parser MUST accept each optional field of 3.3.2 and derivedFrom.originalHash, present or absent, including replaces and replacedBy together.). |
comment | String | MAY contain a free-text comment on the document, e.g. the reason for the status suspended. |
3.3.3 Status Values
The status of a RUML file MUST be one of the following values (Rule META-02META-02 status MUST be one of the seven values of 3.3.3.):
| Status | Description | Requirements |
|---|---|---|
"draft" | Draft | NO additional requirements |
"review" | Under review | SHOULD have authors set |
"approved" | Approved | SHOULD have organization set |
"inForce" | In force | MUST have validFrom set (Rule META-10META-10 Status inForce MUST have validFrom.). SHOULD have jurisdiction set |
"suspended" | Suspended | SHOULD have validUntil or comment set |
"expired" | Expired | MUST have validUntil set (Rule META-11META-11 Status expired MUST have validUntil, and it MUST lie in the past.). validUntil MUST be in the past (Rule META-11META-11 Status expired MUST have validUntil, and it MUST lie in the past.) |
"replaced" | Replaced | MUST have replacedBy set (Rule META-12META-12 Status replaced MUST have replacedBy.) |
Additional rules:
- The status MUST be checked with every content change
- When transitioning status from
"draft"to"inForce", all required fields MUST be validated - A status of
"replaced"MUST NOT be set back to another status
Note: Document status vs. node status
The status values defined here (draft, review, approved, inForce, suspended, expired,
replaced) describe the document status of the RUML file. They are stored in the
metadata.status field and describe the validity state of the entire regulation.
These are to be distinguished from the node status (pending, true, false, undefined,
ignored), which is computed at runtime during evaluation. The node status is NOT stored in the
RUML structure, but exclusively in a separate RUML Result file (.ruml-result). Details see
Chapter 5.
3.3.4 Metadata Object Example
"metadata": { "id": "ec36948d-fbb2-4815-985a-bd5e9375d934", "version": "2024.1.0", "created": "2024-01-15T10:00:00+01:00", "modified": "2024-02-01T14:30:00+01:00", "status": "inForce", "documentType": "law", "authors": [ { "name": "Max Mustermann", "email": "max.mustermann@bmf.bund.de", "organization": "Bundesministerium der Finanzen" } ], "jurisdiction": "DE", "legalDomain": "Steuerrecht", "language": "de", "validFrom": "2024-01-01T00:00:00+01:00", "tags": ["Einkommensteuer", "§32a", "Grundtarif"]}Notes:
-
This example shows a metadata object with status
"inForce"anddocumentType: "law" -
The required field
validFromis set -
The optional fields
jurisdiction,legalDomain, etc. are populated as examples -
Integrity assurance (hashing, signatures) is provided at container level (see Chapter 7)
3.3.5 Working Copies of Documents with Status "inForce"
Basic principle: Documents with status "inForce" SHOULD NOT be modified. Immutability is
ensured through signatures at container level (see Chapter 7). Working
copies MUST be possible.
Rules for working copies:
- When creating a working copy, the following MUST be done:
- A new UUID must be assigned
- The status must be changed to
"draft" - The origin must be documented in the
derivedFromobject
- The
derivedFromobject:
| Field | Type | Description |
|---|---|---|
originalId | UUID | MUST contain the ID of the original document (Rule META-13META-13 derivedFrom MUST have originalId, originalStatus, derivationType and derivedAt.) |
originalHash | String | MAY contain the hash of the original document (Rule META-04META-04 A parser MUST accept each optional field of 3.3.2 and derivedFrom.originalHash, present or absent, including replaces and replacedBy together.). The hash is computed at container level (see Chapter 7). |
originalStatus | Enum | MUST contain the status of the original at the time of copying (Rule META-13META-13 derivedFrom MUST have originalId, originalStatus, derivationType and derivedAt.) |
derivationType | Enum | MUST specify the type: "workingCopy", "amendment", "revision" (Rule META-13META-13 derivedFrom MUST have originalId, originalStatus, derivationType and derivedAt.) |
derivedAt | DateTime | MUST contain the timestamp of the copy creation (Rule META-13META-13 derivedFrom MUST have originalId, originalStatus, derivationType and derivedAt.) |
derivedBy | String | SHOULD specify the creating entity/person |
- Validation for working copies:
- The system MAY verify the integrity of the original via the container hash (see Chapter 7)
- The system MUST ensure that the copy is NOT marked as
"inForce"(Rule META-14META-14 A working copy (derivedFrom.derivationType: "workingCopy") MUST NOT have statusinForce.) - The system SHOULD make the derivation chain traceable
Working copy example:
"metadata": { "id": "d8129e0c-cf2e-4ef9-b7b6-fa8b206d5517", "version": "1.0.1-draft", "created": "2024-01-15T10:00:00+01:00", "modified": "2024-01-15T10:00:00+01:00", "status": "draft", "derivedFrom": { "originalId": "ec36948d-fbb2-4815-985a-bd5e9375d934", "originalHash": "sha3-256:4e03657aea45a94fc7d47c89e3f5a2b7c4d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2", "originalStatus": "inForce", "derivationType": "workingCopy", "derivedAt": "2024-01-15T10:00:00+01:00", "derivedBy": "Bundesministerium der Justiz" }}Note: This structure enables legislators to work with copies of legally binding documents. The integrity and immutability of the originals is ensured through signatures at container level (see Chapter 7).
3.3.6 documentType Values
The optional field documentType classifies the document type of the RUML file. If present, it MUST
be one of the following values (Rule META-05META-05 documentType MUST be one of the values of 3.3.6.):
| Value | Description |
|---|---|
"law" | Formal law (e.g., EStG, BGB, SGB) |
"regulation" | Regulation, statute, or binding rule — public law (e.g., implementing regulation) or private sector (e.g., internal corporate policy with binding character) |
"guideline" | Guide, recommendation, or non-binding directive — e.g., administrative regulation, compliance guideline, best practice document |
"decision" | Decision logic for rule-based notices or judgments — public law (e.g., administrative decision, court ruling) or private sector (e.g., credit decision, compliance review, insurance case) |
"procedure" | Process or procedure description — e.g., administrative procedure, approval process, internal company workflow |
"form" | Structured data collection or application process — e.g., application form, onboarding process, data collection |
"documentGeneration" | Rulemap for rule-based document generation — e.g., notices, contracts, reports, certificates. Evaluation produces one or more documents as output. |
"other" | Other document types that do not match any of the more specific values |
Notes:
- The
documentTypefield is independent of thelegalDomainfield:legalDomaindescribes the subject area (e.g.,"Steuerrecht","Kreditwesen","HR-Compliance"), whiledocumentTypedescribes the form of the document (e.g.,"decision","documentGeneration") - The value
"other"SHOULD NOT be used when one of the more specific values applies - The value list MAY be extended in future versions of the specification
documentTypeis the only classification of a RUML file. Therulemapobject deliberately contains notypefield — document classification is exclusively located in themetadataobject.