Skip to content
RUMLRUML

Open Format for Digital Law

2.2 File Structure Overview

2.2 File Structure Overview

Root Object Structure

Every RUML file MUST have a JSON object as its root element (Rule FMT-02FMT-02 The file MUST be valid JSON (RFC 8259), and its root MUST be an object.):

{
"$format": "RUML",
"$specVersion": "1.0",
"capabilities": [/* ... */],
"metadata": {/* ... */},
"rulemap": {/* ... */}
}

Format Identification

  • The $format field MUST have one of the following values:
    • "RUML" — regular content file (this specification)
    • "RUML-Result" — separate evaluation result file (see Chapter 5.1)
    • "RUML-EXT" — capability extension overlay (sidecar file); has a different root structure without metadata and rulemap (see Chapter 4.5)
  • The $specVersion field MUST specify the format version (2.3)
  • These fields MUST be the first two fields in the root object (Rule FMT-05FMT-05 $format and $specVersion MUST be the first two fields of the root object.)
  • For "RUML-Result", a rumlReference object MUST additionally be present (see Chapter 5.1)

Required Fields in the Root Object

FieldTypeDescription
$formatStringMUST be "RUML" (Rule FMT-03FMT-03 $format MUST be "RUML".)
$specVersionStringMUST specify the format version (2.3) (Rule FMT-04FMT-04 $specVersion MUST be one of the versions listed in the enum of $specVersion in the schema.)
metadataObjectMUST contain the metadata defined in Chapter 3.3 (Rule FMT-06FMT-06 The root object MUST have metadata and rulemap; a parser MUST accept it with or without capabilities.)
rulemapObjectMUST contain the rulemap structure defined in Chapter 3.4 (Rule FMT-06FMT-06 The root object MUST have metadata and rulemap; a parser MUST accept it with or without capabilities.)

Optional Fields in the Root Object

FieldTypeDescription
capabilitiesArrayMAY declare the capabilities this file uses, as a list of entries; their order is not significant. Each entry carries its own data in its payload (see Chapter 4) (Rule FMT-06FMT-06 The root object MUST have metadata and rulemap; a parser MUST accept it with or without capabilities.)

The root object MUST NOT have fields other than these (Rule FMT-07FMT-07 The root object MUST NOT have fields other than $format, $specVersion, metadata, capabilities and rulemap.).

Minimal Valid File

{
"$format": "RUML",
"$specVersion": "1.0",
"metadata": {
"id": "ec36948d-fbb2-4815-985a-bd5e9375d934",
"version": "1.0.0",
"created": "2024-01-01T00:00:00Z",
"modified": "2024-01-01T00:00:00Z",
"status": "draft"
},
"rulemap": {
"nodes": {
"1": {
"id": "0eb360a6-626a-406d-89a1-9f434ced141b",
"label": "Root"
}
}
}
}

Notes:

  • The nodes object is the only required field in the rulemap
  • The root node MUST have the key "1" in the nodes object (LexID 1) (Rule FMT-08FMT-08 rulemap.nodes MUST contain an entry with key "1", the root node.)
  • Every node MUST have an id (UUID v4) (Rule NODE-01NODE-01 A node MUST have id and label.)
  • Integrity assurance (hash, signature) is provided at container level (see Chapter 7)

RUML Result Format

The RUML Result Format is used for separate storage of evaluation results:

  • File extension: .ruml-result
  • Format identification: $format MUST have the value "RUML-Result"
  • Structure: See Chapter 5.1

The RUML Result Format enables the separation of rule structure and evaluation results. This is particularly suitable for mass procedures, case file systems, and long-term archiving.

{
"$format": "RUML-Result",
"$specVersion": "1.0",
"rumlReference": {
"id": "ec36948d-fbb2-4815-985a-bd5e9375d934",
"hash": "sha3-256:4e03657aea45a94fc7d47c89e3f5a2b7c4d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2"
},
"evaluation": {/* ... */}
}

Conformance tests