F.2 DICOM JSON Model
Prev | F DICOM JSON Model | Next

## F.2 DICOM JSON Model

The DICOM JSON Model follows the Native DICOM Model for XML very closely, so that systems can take advantage of both formats without much retooling. The Media Type for DICOM JSON is application/json. The default character repertoire shall be UTF-8 / ISO_IR 192.

### F.2.1 Multiple Results Structure

Multiple results returned in JSON are organized as a single top-level array of JSON objects. This differs from the Native DICOM Model, which returns multiple results as a multi-part collection of singular XML documents.

#### F.2.1.1 Examples

##### F.2.1.1.1 Native DICOM Model

    <?xml version="1.0" encoding="UTF-8" xml:space="preserve" ?>
    <NativeDicomModel>
      <DicomAttribute tag="0020000D" vr="UI" keyword="StudyInstanceUID">
        <Value number="1">1.2.392.200036.9116.2.2.2.1762893313.1029997326.945873</Value>
      </DicomAttribute>
    </NativeDicomModel>
    …
    <?xml version="1.0" encoding="UTF-8" xml:space="preserve" ?>
    <NativeDicomModel>
      <DicomAttribute tag="0020000D" vr="UI" keyword="StudyInstanceUID">
        <Value number="1">1.2.444.200036.9116.2.2.2.1762893313.1029997326.945876</Value>
      </DicomAttribute>
    </NativeDicomModel>

##### F.2.1.1.2 DICOM JSON Model

    [
      {
         "0020000D": {
          "vr": "UI",
          "Value": [ "1.2.392.200036.9116.2.2.2.1762893313.1029997326.945873" ]
        }
      }
      {
        "0020000D" : {
          "vr": "UI",
          "Value": [ "1.2.392.200036.9116.2.2.2.2162893313.1029997326.945876" ]
        }
      }
    ]

### F.2.2 DICOM JSON Model Object Structure

The DICOM JSON Model object is a representation of a DICOM Data Set.

The internal structure of the DICOM JSON Model object is a sequence of objects representing attributes within the DICOM Data Set.

Attribute objects within a DICOM JSON Model object must be ordered by their property name in ascending order.

Group Length (gggg,0000) attributes shall not be included in a DICOM JSON Model object.

The name of each attribute object is:

- The eight character uppercase hexadecimal representation of a DICOM Tag

Each attribute object contains the following named child objects:

- vr: A string encoding the DICOM Value Representation. The mapping between DICOM Value Representations and JSON Value Representations is described in Section F.2.3.

- At most one of:

  - Value: An array containing one of:

    - The Value Field elements of a DICOM attribute with a VR other than PN, SQ, OB, OD, OF, OW, or UN (described in Section F.2.4)

      The encoding of empty Value Field elements is described in Section F.2.5

    - The Value Field elements of a DICOM attribute with a VR of PN. The non-empty name components of each element are encoded as a JSON strings with the following names:

      - Alphabetic

      - Ideographic

      - Phonetic

    - JSON DICOM Model objects corresponding to the sequence items of an attribute with a VR of SQ

      Empty sequence items are represented by empty objects

  - BulkDataURI: A string encoding the WADO-RS URL of a bulk data item describing the Value Field of an enclosing Attribute with a VR of FL, FD, IS, LT, OB, OD, OF, OW, SL, SS, ST, UL, UN, US, or UT (described in Section F.2.6)

  - InlineBinary: A base64 string encoding the Value Field of an enclosing Attribute with a VR of OB, OD, OF, OW, or UN (described in Section F.2.7)

### Note

1. For Private Data Elements, the group and element numbers will follow the rules specified in Section 7.8.1 in PS3.5

2. The person name representation is more closely aligned with the DICOM Data Element representation than the DICOM PS3.19 XML representation.

### F.2.3 DICOM JSON Value Representation

The value representation (VR) is included in each DICOM JSON Model attribute object and named "vr". For example:

    "vr": "CS"

All DICOM Value Representations are mapped to specified JSON Data Types (see Table F.2.3-1). The JSON encodings shall conform to the Definition, Character Repertoire (if applicable) and Length of Value specified for that Value Representation (see Section 6.2 “Value Representation (VR)” in PS3.5 ) with the following exceptions:

- Attributes with a Value Representation of AT shall be restricted to eight character uppercase hexadecimal representation of a DICOM Tag

Table F.2.3-1. DICOM VR to JSON Data Type Mapping

VR Name | Type | JSON Data Type
--- | --- | ---
AE | Application Entity | String
AS | Age String | String
AT | Attribute Tag | String
CS | Code String | String
DA | Date | String
DS | Decimal | Number
DT | Date Time | String
FL | Floating Point Single | Number
FD | Floating Point Double | Number
IS | Integer String | Number
LO | Long String | String
LT | Long Text | String
OB | Other Byte String | Base64 encoded string
OD | Other Double String | Base64 encoded string
OF | Other Float String | Base64 encoded string
OW | Other Word String | Base64 encoded string
PN | Person Name | Object containing Person Name component groups as strings (see Section F.2.2)
SH | Short String | String
SL | Signed Long | Number
SQ | Sequence | Array containing DICOM JSON Objects
SS | Signed Short | Number
ST | Short Text | String
TM | Time | String
UI | UID | String
UL | Unsigned Long | Number
UN | Unknown | Base64 encoded string
UR | URI | String
US | Unsigned Short | Number
UT | Unlimited Text | String

Although data, such as dates, are represented in the DICOM JSON model as strings, it is expected that they will be treated in the same manner as the original attribute as defined by Chapter 6 in PS3.6 .

### F.2.4 DICOM JSON Value Multiplicity

The value or values of a given DICOM attribute are given in the "Value" array. The value multiplicity (VM) is not contained in the DICOM JSON object.

For example:

    "Value": [ "bar", "foo" ]

or:

    "Value": [ "bar" ]

### F.2.5 DICOM JSON Model Null Values

If an attribute is present in DICOM but empty (i.e., Value Length is 0), it shall be preserved in the DICOM JSON attribute object containing no "Value", "BulkDataURI" or "InlineBinary".

If a multi-valued attribute has one or more empty values these are represented as "null" array elements. For example:

    "Value": [ "bar", null, "foo" ]

If a sequence contains empty items these are represented as empty JSON object in the array.

    "Value": [ { … }, { }, { … } ]

### F.2.6 BulkDataURI

If an attribute contains a "BulkDataURI" , this contains the URI of a bulk data element as defined in Table A.1.5-2 in PS3.19 .

### F.2.7 InlineBinary

If an attribute contains an "InlineBinary", this contains the base64 encoding of the enclosing attribute's Value Field.

There is a single InlineBinary value representing the entire Value Field, and not one per Value in the case where the Value Multiplicity is greater than one. E.g., a LUT with 4096 16 bit entries that may be encoded in DICOM with a Value Representation of OW, with a VL of 8192 and a VM of 1, or a US VR with a VL of 8192 and a VM of 4096 would both be represented as a single InlineBinary string.

All rules (e.g., byte ordering and swapping) in DICOM PS3.5 apply.

### Note

Implementers should in particular pay attention the PS3.5 rules regarding the value representations of OD, OF and OW.

Prev | Up | Next
F DICOM JSON Model | Home | F.3 Transformation with other DICOM Formats