Skip to content
RUMLRUML

Open Format for Digital Law

3.3 Metadata Object

3.3 Metadata Object

The metadata object contains all information about the RUML file itself.

3.3.1 Required Fields

FieldTypeDescription
idUUIDMUST be a unique identification of the RUML file (Rule META-01META-01 metadata MUST have id, version, created, modified and status.)
versionStringMUST 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)
createdDateTimeMUST specify the creation timestamp (Rule META-01META-01 metadata MUST have id, version, created, modified and status.)
modifiedDateTimeMUST 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.)
statusEnumMUST 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

FieldTypeDescription
titleStringMAY contain a human-readable title of the rulemap.
descriptionStringMAY contain a short description of the rulemap.
documentTypeEnumMAY 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.
authorsArray[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).
organizationStringMAY 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.
jurisdictionStringMAY 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".
legalDomainStringMAY specify the legal domain.
tagsArray[String]MAY contain categorization/tagging.
derivedFromObjectMAY contain information about the origin. MUST be used for working copies.
languageStringMAY 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.).
validFromDateTimeMAY specify the validity start date.
validUntilDateTimeMAY 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.).
replacesUUIDMAY 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.).
replacedByUUIDMAY 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.).
commentStringMAY 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.):

StatusDescriptionRequirements
"draft"DraftNO additional requirements
"review"Under reviewSHOULD have authors set
"approved"ApprovedSHOULD have organization set
"inForce"In forceMUST have validFrom set (Rule META-10META-10 Status inForce MUST have validFrom.). SHOULD have jurisdiction set
"suspended"SuspendedSHOULD have validUntil or comment set
"expired"ExpiredMUST 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"ReplacedMUST 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" and documentType: "law"

  • The required field validFrom is 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:

  1. 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 derivedFrom object
  1. The derivedFrom object:
FieldTypeDescription
originalIdUUIDMUST contain the ID of the original document (Rule META-13META-13 derivedFrom MUST have originalId, originalStatus, derivationType and derivedAt.)
originalHashStringMAY 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).
originalStatusEnumMUST contain the status of the original at the time of copying (Rule META-13META-13 derivedFrom MUST have originalId, originalStatus, derivationType and derivedAt.)
derivationTypeEnumMUST specify the type: "workingCopy", "amendment", "revision" (Rule META-13META-13 derivedFrom MUST have originalId, originalStatus, derivationType and derivedAt.)
derivedAtDateTimeMUST contain the timestamp of the copy creation (Rule META-13META-13 derivedFrom MUST have originalId, originalStatus, derivationType and derivedAt.)
derivedByStringSHOULD specify the creating entity/person
  1. 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 status inForce.)
  • 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.):

ValueDescription
"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 documentType field is independent of the legalDomain field: legalDomain describes the subject area (e.g., "Steuerrecht", "Kreditwesen", "HR-Compliance"), while documentType describes 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
  • documentType is the only classification of a RUML file. The rulemap object deliberately contains no type field — document classification is exclusively located in the metadata object.

Conformance tests