DICOM Rule Group JSON Guide

This guide explains how to construct valid DICOM Rule Group JSON file for SliceVault. It explains the complete rule group structure, how rules work, how operands and VR modifiers behave, and how to build nested logic - beginning with a simple working example and progressing toward more advanced, multi‑level rule sets.

1. JSON Structure Overview

Before constructing individual rules, it is important to understand the overall layout of the file. The SliceVault DICOM Rule format is a relational, flat structure, not a deeply nested JSON tree. The file is a single Array containing a flat list of Rule Groups. Complex logic (nesting) is achieved by referencing IDs, similar to a database relationship, rather than nesting objects inside one another.

The Hierarchy

The structure consists of three conceptual levels:

  1. The Root List: A flat array [ ... ] containing every Rule Group defined in the file.
  2. The Rule Group: A container { ... } with a unique ID and a logic gate (ALL or ANY) that determines how its internal rules are combined.
  3. The Rules: An internal list [ ... ] of specific comparisons (e.g., “Tag X equals Value Y”) or references to other groups.

Schema Visualization

While the logic may be nested (Group 1 uses Group 2), the JSON remains flat:

[
  // -------------------------------------------------------
  // GROUP 1: The Parent (Main Entry Point)
  // Logic: Checks specific rules AND results of Group 2
  // -------------------------------------------------------
  {
    "ID": 1,
    "MatchCondition": "ALL",
    "ScanTypeDicomRules": [
      { "MatchOperation": "EXACTLY", ... }, // Rule A
      { "MatchOperation": "EXISTS", "MatchRuleGroupID": 2 } // Reference to Group 2
    ]
  },
  // -------------------------------------------------------
  // GROUP 2: The Child (Sub-Logic)
  // Logic: Defined separately, referenced by ID above
  // -------------------------------------------------------
  {
    "ID": 2,
    "MatchCondition": "ANY",
    "ScanTypeDicomRules": [
       { "MatchOperation": "CONTAINS", ... }, // Rule B
       { "MatchOperation": "CONTAINS", ... }  // Rule C
    ]
  }
]

2. Minimal, Valid JSON Example

To understand how rule groups work, it is best to begin with a complete example you can import directly into SliceVault:

[
  {
    "ID": 1,
    "MatchCondition": "ALL",
    "ScanTypeDicomRules": [
      {
        "MatchOperation": "EXACTLY",
        "MatchDicomTagLHS": "00080060",
        "MatchValueRHS": "MR"
      }
    ],
    "ScanTypeDicomRuleGroupLocalizations": [
      {
        "Language": "en",
        "Name": "Simple Example",
        "Description": "Matches MR Modality"
      }
    ]
  }
]

This is all SliceVault needs for a working rule group.

Important Note About Downloaded JSON

When downloading rule groups from SliceVault, you may see additional fields such as:

  • $id
  • $ref
  • ScanType
  • ScanTypeDicomRuleGroup1
  • Internal IDs not present in uploaded JSON

These fields belong to SliceVault’s internal serializer format. They are not necessary when uploading JSON, and should not be included when constructing rule groups manually. This guide describes only the minimal, simplified JSON format required for input.

3. Understanding Rule Groups

A Rule Group is the core building block used to classify and validate DICOM series. Each rule group evaluates to true or false based on:

  • Its internal rules
  • Its nested rule groups
  • Its MatchCondition

A rule group contains:

{
  "ID": <number>,
  "MatchCondition": "ALL" | "ANY",
  "ScanTypeDicomRules": [ ... ],
  "ScanTypeDicomRuleGroupLocalizations": [ ... ]
}

3.1 ID

Each rule group must have a unique ID.
Other rule groups may reference it using MatchRuleGroupID.

3.2 MatchCondition

Controls how a rule group combines its rules:

  • ALL → every rule must pass
  • ANY → at least one rule must pass

3.3 Localizations

Defines how the group appears in the user interface.

Example:

{
  "Language": "en", // Required, must always be "en"
  "Name": "Timing Rules",
  "Description": "Validates TR range" // Optional
}

4. Rules

A rule is a single logical comparison using:

  • a MatchOperation
  • a Left-Hand Side (LHS) operand
  • a Right-Hand Side (RHS) operand

Rules appear inside ScanTypeDicomRules:

{
  "MatchOperation": "CONTAINS",
  "MatchDicomTagLHS": "0008103E",
  "MatchValueRHS": "T1"
}

Nested Rule Groups

Nested rule groups allow complex decision trees such as:

(MR AND T1) OR (MR AND T2)

To reference another group:

{
  "MatchOperation": "EXISTS",
  "MatchRuleGroupID": 2
}

This tells SliceVault: Evaluate Rule Group 2 and return its result.

Nested groups can be arbitrarily deep.

How rules are evaluated

SliceVault resolves a rule in these steps:

  1. Resolve LHS into a value
  2. Resolve RHS into a value
  3. Convert values into the expected format (string, numeric, VR-modified, etc.)
  4. Apply the match operation
  5. Produce true/false

5. Operand Types (LHS & RHS)

A rule always compares one LHS operand to one RHS operand. SliceVault determines the meaning of a rule based on which fields you provide.

There are two operand fields on each side (MatchDicomTagLHS / MatchValueLHS and MatchDicomTagRHS / MatchValueRHS). Different rule types use different fields - see the sections below for when each applies.

5.1 LHS Operand Types

5.1.1 DICOM Tags 

"MatchDicomTagLHS": "00080060"

Indexed Multi-Value Tags

Some DICOM fields contain multiple values like (0020,0037): 0\1\0\0\-1.

You can access specific positions:

"MatchDicomTagLHS": "00200037@0" // return first index value (0)
"MatchDicomTagLHS": "00200037@1" // return second index value (1)

Indexing starts at 0.

5.1.2 Derived Internal Tags

SliceVault provides computed values such as:

Tag Name Description
Weight The patient/phantom weight (if provided by metadata).
TotalDose Total injected radiopharmaceutical dose recorded in the metadata.
HalfLife Half-life of the radiopharmaceutical used.
TimeDifference Seconds between Injection Time and Acquisition Start Time. Computed as: (StartTime – InjectionTime) in seconds.
VoxelsX Number of voxels in the X dimension.
VoxelsY Number of voxels in the Y dimension.
VoxelsZ Number of voxels in the Z dimension.
TimeFrames Number of time frames in a dynamic acquisition.
VoxelSizeX Physical voxel size in millimeters along the X axis.
VoxelSizeY Physical voxel size in millimeters along the Y axis.
VoxelSizeZ Physical voxel size (slice thickness or spacing) in millimeters along the Z axis.
MinPixelValue Minimum pixel value observed in the series.
MaxPixelValue Maximum pixel value observed in the series.

Example:

"MatchDicomTagLHS": "VoxelSizeZ"

5.1.3 Form Fields

Useful when comparing a DICOM tag to user‑entered metadata.

"MatchDicomTagLHS": "{FIELD:100}"

Form fields do not automatically match DICOM VR formats.

Example:

  • User enters "09:30"
  • DICOM time is "093000"

To convert:

"MatchDicomTagLHS": "{FIELD:500}{VR:TM}"

Available Modifiers

  • {VR:DA} - Date (YYYYMMDD)
  • {VR:TM} - Time (HHMMSS)
  • {VR:DT} - DateTime (YYYYMMDDHHMMSS.FFFFFF&ZZXX)

If VR is mismatched, comparison fails.

5.1.4 Variables

Special placeholders:

{SITE}
{VISIT}

Example:

"MatchValueLHS": "{SITE}"

5.2 RHS Operand Types

5.2.1 DICOM Tags 

"MatchDicomTagRHS": "0008103E"

Tags with indexing 

"MatchDicomTagRHS": "00200032@0"

5.2.2 Literal values 

"MatchValueRHS": "MR"

5.2.3 Numeric values 

"MatchValueRHS": "3.5"

6. Offsets

Offsets allow tolerance‑based comparisons - commonly for time.

Offsets apply to RHS only:

LHS <operation> (RHS + offset)

Example 

{
  "MatchOperation": "LE",
  "MatchDicomTagLHS": "{FIELD:1000}{VR:TM}",
  "MatchDicomTagRHS": "00080032",
  "MatchValueRHS": "900"
}

In this exeample, the injection time (from form field 1000) is allowed to be up to 15 minutes (900 seconds) earlier than the Acquisition Time in the DICOM tag (0008,0032).

Offsets support:

  • Positive values "900"
  • Negative values "-300"

No parentheses or chained expressions allowed.

7. Match Operations

Tag Existence

  • EXISTS (tag must be present)
  • NEXISTS (tag must not be present)

Text (case insensitive)

  • EXACTLY (equals)
  • NEXACTLY (not equal)
  • CONTAINS (contains substring)
  • NCONTAINS (does not contain substring)
  • BEGINS (begins with substring)
  • NBEGINS (does not begin with substring)
  • ENDS (ends with substring)
  • NENDS (does not end with substring)
  • MATCHES (regular expression match)

Numeric

  • EQ (equal to)
  • NEQ (not equal to)
  • LT (less than)
  • LE (less than or equal to)
  • GT (greater than)
  • GE (greater than or equal to)

8. Full Multi‑Level Example

This is a realistic, deeply nested rule group set:

  • Parent group (ANY)
  • T1 validation group (ALL)
  • Timing sub‑group under T1
  • T2 validation group (ALL)
[
  {
    "ID": 1,
    "MatchCondition": "ANY",
    "ScanTypeDicomRules": [
      { "MatchOperation": "EXISTS", "MatchRuleGroupID": 2 },
      { "MatchOperation": "EXISTS", "MatchRuleGroupID": 3 }
    ],
    "ScanTypeDicomRuleGroupLocalizations": [
      { "Language": "en", "Name": "Parent Group", "Description": "Matches Group 2 OR Group 3" }
    ]
  },
  {
    "ID": 2,
    "MatchCondition": "ALL",
    "ScanTypeDicomRules": [
      { "MatchOperation": "EXACTLY", "MatchDicomTagLHS": "00080060", "MatchValueRHS": "MR" },
      { "MatchOperation": "CONTAINS", "MatchDicomTagLHS": "0008103E", "MatchValueRHS": "T1" },
      { "MatchOperation": "EXISTS", "MatchRuleGroupID": 4 }
    ],
    "ScanTypeDicomRuleGroupLocalizations": [
      { "Language": "en", "Name": "T1 Group", "Description": "Validates T1-weighted MRI" }
    ]
  },
  {
    "ID": 4,
    "MatchCondition": "ALL",
    "ScanTypeDicomRules": [
      { "MatchOperation": "GE", "MatchDicomTagLHS": "00180080", "MatchValueRHS": "2000" },
      { "MatchOperation": "LE", "MatchDicomTagLHS": "00180080", "MatchValueRHS": "2600" }
    ],
    "ScanTypeDicomRuleGroupLocalizations": [
      { "Language": "en", "Name": "T1 Timing Check", "Description": "TR must be between 2000 and 2600 ms" }
    ]
  },
  {
    "ID": 3,
    "MatchCondition": "ALL",
    "ScanTypeDicomRules": [
      { "MatchOperation": "EXACTLY", "MatchDicomTagLHS": "00080060", "MatchValueRHS": "MR" },
      { "MatchOperation": "CONTAINS", "MatchDicomTagLHS": "0008103E", "MatchValueRHS": "T2" },
      { "MatchOperation": "GE", "MatchDicomTagLHS": "00180081", "MatchValueRHS": "80" },
      { "MatchOperation": "LE", "MatchDicomTagLHS": "00180081", "MatchValueRHS": "120" }
    ],
    "ScanTypeDicomRuleGroupLocalizations": [
      { "Language": "en", "Name": "T2 Group", "Description": "Validates T2-weighted MRI" }
    ]
  }
]

Copyright © 2025 by SliceVault