DICOM PS3.18 2017d - Web Services

6 Data Communication Requirements

DICOM Web Services use the HTTP and HTTPS protocols as its transport medium. Web Services supports versions 1.0, 1.1 and 2 of the protocol. If an origin server supports version 2, it shall also support version 1.1. If an origin server supports version 1.1, it shall also support version 1.0.

It is recommended that user agents that want to use HTTP/2 first initiate an HTTP/1.1 connection to the origin server and then upgrade to HTTP/2. If the upgrade fails then the user agent can still use the HTTP/1.1 connection. [RFC7540] Section 3 explains how to initiate HTTP/2 connections.

6.1 Interaction

Interaction Diagram

Figure 6-1. Interaction Diagram


The interaction shall be as shown in Figure 6-1.

Multiple communications modes are possible:

  • URI based using HTTP Get: WADO-URI request

  • RESTful Services (RS) using HTTP Get: WADO-RS, either:

    1. DICOM Requester (Retrieve Study, Series, or Instance DICOM Objects)

    2. Frame Pixel Data Requester (Retrieve Instance Frame Pixel Data)

    3. Bulk Data Requester (Retrieve Study, Series, Instance Bulk Data)

    4. Metadata Requester (Retrieve Study, Series, Instance Metadata)

  • RESTful Services (RS) using HTTP Get: QIDO-RS:

    1. Query Requester (Search for Study, Series or Instance DICOM Objects)

  • RESTful Services (RS) using HTTP POST: STOW-RS, either:

    1. DICOM Creator (Store Instances)

    2. Metadata and Bulk Data Creator (Store Instances)

  • RESTful Services (RS) using HTTP Options: RS Capabilities:

    1. Provided information about the capabilities of a DICOM RESTful web service provider)

6.1.1 Media Types

Media types are identifiers used to define the data format of a representation. HTTP uses media types in the Content-Type and Accept header fields in order to provide open and extensible data typing and type negotiation. The syntax of media types is:

    media-type = type "/" subtype *(OWS ";" OWS parameter)

Where

    type = token
    subtype = token
    parameter = token "=" (token / quoted-string) )

The <type>/<subtype> may be followed by parameters in the form of name=value pairs.

The type, subtype, and parameter name tokens are case-insensitive, but the case sensitivity of parameter values depends on the semantics of the parameter name. The presence or absence of a parameter might be significant to the processing of a media-type, depending on its definition within the media type registry.

A parameter value can be transmitted either as a token or quoted-string. The quoted and unquoted values are equivalent.

Media types are defined in [RFC7231] Section 3.1.1.1.

IANA maintains a registry of media types at http://www.iana.org/assignments/media-types/media-types.xhtml.

6.1.1.1 Multipart Media Types

Some of the services defined in this Standard support the multipart media types [RFC2387]. The syntax is:

    multipart-media-type = "multipart" "/" subtype *( OWS ";" OWS parameter )

The "application/multipart-related" media type is used by the RS services. Its syntax is:

    multipart-related = "multipart/related"
                         OWS ";" OWS "type" "=" DQUOTE media-type DQUOTE
                         OWS ";" OWS "boundary" "=" boundary
                         [related-parameters]

Where

    boundary = 0*69bchar bchar-nospace
    bchar = bchar-nospace / SP
    bchar-nospace = DIGIT / ALPHA / "'" / "(" / ") " / "+" / "_" / "," / "-"
                    / "." / "/" / ":" / "=" / "?" "/" / ":" / "=" / "?"
    related-parameters = [";" "start" "=" cid]
                         [";" "start-info" "=" cid-list]
    cid-list = cid cid-list
    cid = token / quoted-string

The "type" parameter is required. It contains the media type of the "root" body part. It always contains the special character "/" and thus requires quote marks.

The <cid> is a content identifier. It should be unique for each part of the multipart message.

Typically, the "start" and "start-info" parameters are not specified, and the "root" is the first body part.

6.1.1.2 DICOM Resource Categories

Table 6.1.1-1 defines Resource Categories that correspond to different SOP Classes. The following sections map each Resource Category to appropriate DICOM and Rendered media types.

Table 6.1.1-1. Resource Categories

Resource Category

Definition

Single Frame Image

This category includes all resources that:

  1. are instances of a single frame SOP Class, or

  2. are instances of a multi-frame SOP Class that contain only one frame, or

  3. are a single frame selected from an instance of a multi-frame SOP Class.

Multi-frame Image

This category includes all resources that are instances of a multi-frame SOP Class, that are not video and that contain more than one frame.

Video

This category includes all resources that contain more than one frame and:

  1. are instances encoded in the MPEG family of transfer syntaxes (which includes MP4 and H265), or

  2. are time based (motion) multi-frame images that the origin server is capable of encoding in the MPEG family.

Text

This category includes all resources that:

  1. contain the SR Document Content Module (see Section C.17.3 “SR Document Content Module” in PS3.3 ), such as narrative text, structured reports, CAD, measurement reports, and key object selection documents, or

  2. contain the Encapsulated Document Module (see Section C.24.2 “Encapsulated Document Module” in PS3.3 ).

Other

This category includes all resources that are not included above.


6.1.1.3 Rendered Media Types

DICOM instances may be converted by a rendering process into non-DICOM media types in order to display them using commonly available non-DICOM software, such as browsers.

For example:

  1. A DICOM SOP Instance containing an image could be rendered into the image/jpeg or image/png Rendered Media Types.

  2. A DICOM SOP Instance containing a multi-frame image in a lossless transfer syntax could be rendered into a video/mpeg or video/mp4 Rendered Media Type.

  3. A DICOM SOP Instance containing a Structured Report could be rendered into a text/html, text/plain, or application/pdf Rendered Media Type.

Note

Rendered Media Types are usually consumer format media types. Some of the same non-DICOM media types are also used as Bulk Data Media Types, that is, for encoding bulk data extracted from Encapsulated Pixel Data (used with compressed Transfer Syntaxes), without applying a rendering process; see Section 6.1.1.8.

Table 6.1.1-2 specifies the meaning of media type requirement terms used in Table 6.1.1-3 and the tables in Section 6.1.1.8.

Table 6.1.1-2. Definition of Media Type Requirement Terms

Requirement

Definition

default

The origin server shall return this media type when none of the Acceptable Media Types (see Section 6.1.1.4) are supported. The origin server shall support this media type.

required

The origin server shall support this media type.

optional

The origin server may support this media type.


Origin servers that support Web Services shall support rendering instances of different Resource Categories into Rendered Media Types as specified in Table 6.1.1-3.

Table 6.1.1-3. Rendered Media Types by Resource Category

Category

Media Type

URI

RS

Single Frame Image

image/jpeg

default

default

image/gif

optional

required

image/png

optional

required

image/jp2

optional

optional

Multi-frame Image

image/gif

optional

optional

Video

video/mpeg

optional

optional

video/mp4

optional

optional

video/H265

optional

optional

Text

text/html

default

default

text/plain

required

required

text/xml

optional

required

text/rtf

optional

optional

application/pdf

optional

optional


When an image/jpeg media type is returned, the image shall be encoded using the JPEG baseline lossy 8 bit Huffman encoded non-hierarchical non-sequential process defined in ISO/IEC 10918-1.

Note

A DICOM encapsulated CDA resource may be returned as a text/xml media type.

The origin server may support additional rendered media types.

A transfer syntax media type parameter is not permitted for Rendered Media Types.

6.1.1.4 Acceptable Media Types

The term Acceptable Media Types denotes the media types that are acceptable to the user agent in the response. The Acceptable Media Types are those specified in:

  • The <accept> query parameter, which may or may not be present.

  • The Accept header field, which shall be present.

All requests that expect a response with a payload, shall include the Accept header field. The response to a request without an Accept header field shall be 406 (Not Acceptable). Even if specific media types are provided in the <accept> query parameter, an Accept header field with one or more values shall be present, at a minimum */*.

The Acceptable Media Types shall be either DICOM media-types or Rendered media types, but not both. If the Acceptable Media Types contains both DICOM and Rendered Media Types, the origin server shall return 409 (Conflict).

The user agent may specify the relative degree of preference for media types, whether in the <accept> query parameter or the Accept header field, using the <weight> parameter. See [RFC7231] Section 5.3.1.

    weight = OWS ";" OWS "q=" qvalue
    qvalue = ("0" ["." 0*3DIGIT]) / ("1" ["." 0*3("0") ])

If no "q" parameter is present, the default qvalue is 1.

6.1.1.5 Accept Query Parameter

The <accept> query parameter is primarily designed for use in hyperlinks (URLs) embedded in documents, where the Accept header field is not accessible. It is similar to the Accept header field, except that it shall not have wildcards (<type>/* or */*).

The <accept> query parameter has the following syntax:

    accept = accept-name "=" 1#(media-type [weight])
    accept-name = "%s" quoted-string

Note

The "%s" that prefixes the <accept-name> specifies that it is a case sensitive token. See [RFC7405].

Its value is a comma-separated list of one or more <media-type>s, possibly including parameters. It shall be supported by the origin server. It is optional for the user agent.

The <accept-name> of the <accept> query parameter is defined by the Service. It is case-sensitive. Table 6.1.1-4 contains the <accept-name> of the <accept> query parameter for some services.

Table 6.1.1-4. <accept> Query Parameter Name by Service

Service

Name

URI

accept-name = "contentType"

RS

accept-name = "accept"


The <accept> query parameter should not be used when the user agent can specify the values in the Accept header field.

All media types present in an <accept> query parameter shall be compatible with a media range in the Accept header field, either explicitly or implicitly through wildcards.

Note

For example, the presence of image/jpeg in the <accept> query parameter will require the Accept header field to include one of the following values: image/jpeg, image/*, or */*.

See Section 6.1.4.

6.1.1.6 Accept Header field

The Accept header field is used to specify media ranges acceptable to the user agent. It has the following syntax:

    Accept = 1#(media-range [weight])

Where,

    media-range = media-type
                  / type "/" "*" parameters
                  / "*/*" parameters
    parameters ; See Section 6.1.1

The Accept header field shall be present. Its value shall be a comma-separated list of one or more media ranges acceptable in the response. See [RFC7231] Section 5.3.2.

A media range is either a media-type or a wildcard. Wildcards use the asterisk ("*") to group media types into ranges, with <type>/* indicating all subtypes of that type, and */* indicating all media types from the target's Resource's Category.

For example, the media range "image/*" matches "image/jpeg", which is the default media type for the Single Frame Image Resource Category, and "text/*" matches "text/html", which is the default media type for the Text Resource Category. The "*/*" media range matches the default media type for the target's Resource Category.

If the origin server receives a request without an Accept header field, but that might have a response payload, it shall return a 406 (Not Acceptable).

Any Accept header field values that are not valid or not supported shall be ignored.

6.1.1.7 Selected Media Type

The Selected Media Type is the media type selected by the origin server for the response payload. The media types in the <accept> query parameter and the media ranges in the Accept header field shall each be separately prioritized according to the rules defined in [RFC7231] Section 5.3.1.

For multipart payloads the Selected Media Type is determined independently for each message part in the response.

Note

The Selected Media Type of each message part depends on the Resource Category of the Instance and the Acceptable Media Types for that Resource Category.

The Selected Media Type is chosen as follows:

  1. Select the target's Resource Category

  2. Select the representation with the highest priority supported media type for that category in the <accept> query parameter, which is compatible with the Accept header field.

  3. If no media type in the <accept> query parameter is supported, select the highest priority supported media type for that category in the Accept header field, if any.

  4. Otherwise, select the default media type for the category if the Accept header field contains a wildcard media range matching the category, if any.

  5. Otherwise, return a 406 (Not Acceptable).

For a set of media types in the <accept> query parameter (step 2 above), or for a set of media ranges in the Accept header field (step 3 above), the highest priority supported media type is determined as follows:

  1. Assign a <qvalue> of 1 to any member of the set that does not have a one.

  2. Assign each representation supported by the origin server the <qvalue> of the most specific media type that it matches.

  3. Select the representation with the highest <qvalue>. If there is a tie, the origin server shall determine which is returned.

For example, consider an origin server that receives a request with the following Accept header field:

    Accept: text/*; q=0.5, text/html; q=0.4, text/html; level=1, text/html; level=2; q=0.7, image/png, */*; q=0.4

Suppose that for the resource indicated in the request, the origin server supports representations for the following media types:

    text/html(regular, level 1 and level 2)
    text/rtf
    text/plain
    text/x-latex

These media types are assigned the following <qvalue>s, based on the media ranges above:

Media Type

qvalue

Determining Media Range

text/html; level=1

1.0

text/html; level=1

text/html; level=2

0.7

text/html; level=2

text/plain

0.5

text/*

text/rtf

0.5

text/*

text/html

0.4

text/html

text/x-latex

0.4

*/*

Although "image/png" has been assigned a default <qvalue> of 1.0, it is not among the supported media types for this resource, and thus is not listed.

The selected media type is "text/html; level=1" since it is the supported media type in the Text Category with the highest qvalue.

6.1.1.8 DICOM Media Types and Media Types For Bulk Data

This section defines the media types used to represent DICOM Instances and bulk data. It describes:

  • The media type and transfer syntax parameter for DICOM PS3.10 Files

  • The media types that can be used for the bulk data of single and multi-frame images and video extracted from Instances.

  • The syntax of DICOM Media Types including their transfer syntax and character set parameters.

  • The query parameter for transfer syntax.

  • The meaning of Acceptable Transfer Syntaxes and Selected Transfer Syntax.

  • The media types supported by each service.

The media types defined in this section are distinct from those into which DICOM Instances may be rendered (which are defined in Section 6.1.1.3); some of the same media types are used for both rendered content and bulk data.

Depending on the service, the media types may be single part or multipart, and may have required or optional transfer syntax and/or character set parameters.

Table 6.1.1.8-1a, Table 6.1.1.8-1b, Table 6.1.1.8-1c and Table 6.1.1.8-1d specify the media types used to encode different representations of DICOM Instances for the Web Services. These media types apply to all Resource Categories and have default encodings for images and video data elements contained in the Instances.

The definitions of media type requirements are provided in Table 6.1.1-2.

Table 6.1.1.8-1a. Media Types for DICOM PS3.10 Files

Media Type

Descriptions

URI

RS

application/dicom

Encodes Composite SOP Instances in the DICOM File Format defined in PS3.10 Section 7 “DICOM File Format”.

See Table 6.1.1.8-2

See Table 6.1.1.8-2


Table 6.1.1.8-1b. Media Types for DICOM Metadata

Media Type

Descriptions

URI

RS

application/dicom+xml

Encodes Composite SOP Instances as XML Infosets defined in the Native Dicom Model defined in PS3.19.

not applicable

required

application/dicom+json

Encodes Composite SOP Instances in the JSON format defined in Annex F.

not applicable

required


Table 6.1.1.8-1c. Media Types for DICOM Uncompressed Bulk Data

Media Type

Descriptions

URI

RS

application/octet-stream

Encodes a Bulkdata object as a stream of uncompressed bytes, in little endian byte order.

Note

This is the same encoding defined in PS3.19 for the returned value of the getData() call for uncompressed Bulk Data.

not applicable

See Table 6.1.1.8-3a


Table 6.1.1.8-1d. Media Types for DICOM Compressed Bulk Data

Media Type

Descriptions

URI

RS

image/*

video/*

Encodes Bulkdata values, which in the case of compressed Pixel Data for WADO-RS services, will have each frame encoded as a separate part of a multipart response and identified by an appropriate Content-Type header.

Note

This is not the same encoding defined in PS3.19 for the returned value of the getData() call for compressed Pixel Data, which will contain the entire payload of the Pixel Data element encoded in Encapsulated Format as defined in PS3.5 (i.e., as a Sequence of Fragments).

not applicable

See Table 6.1.1.8-3b


Table 6.1.1.8-2 specifies, by Resource Category (see Table 6.1.1-1) , the application/dicom media type for PS3.10 Files, along with the default and allowed Transfer Syntax UID combinations for each resource category for the Web Services. The default media type for the Resource Category shall be returned when the origin server supports none of the Acceptable Media Types.

If no transfer-syntax parameter is specified for the media type for PS3.10 Files (application/dicom) then the Explicit VR Little Endian Transfer Syntax "1.2.840.10008.1.2.1" shall be used.

Note

This is different from the Default Transfer Syntax defined in Section 10.1 “DICOM Default Transfer Syntax” in PS3.5 , which is Implicit VR Little Endian.

Table 6.1.1.8-2. Transfer Syntax UIDs for 'application/dicom' Media Type Instances in the Image or Video Resource Categories

Category

Transfer SyntaxUID

Transfer Syntax Name

URI

RS

Single Frame Image

1.2.840.10008.1.2.1

Explicit VR Little Endian

default

default

1.2.840.10008.1.2.4.70

JPEG Lossless, Non-Hierarchical, First-Order Prediction(Process 14 [Selection Value 1]) :Default Transfer Syntax for Lossless JPEG Image Compression

optional

optional

1.2.840.10008.1.2.4.50

JPEG Baseline (Process 1) :Default Transfer Syntax for Lossy JPEG 8 Bit Image Compression

optional

optional

1.2.840.10008.1.2.4.51

JPEG Extended (Process 2 & 4) :Default Transfer Syntax for Lossy JPEG 12 Bit Image Compression (Process 4 only)

optional

optional

1.2.840.10008.1.2.4.57

JPEG Lossless, Non-Hierarchical (Process 14)

optional

optional

1.2.840.10008.1.2.5

RLE Lossless

optional

optional

1.2.840.10008.1.2.4.80

JPEG-LS Lossless Image Compression

optional

optional

1.2.840.10008.1.2.4.81

JPEG-LS Lossy (Near-Lossless) Image Compression

optional

optional

1.2.840.10008.1.2.4.90

JPEG 2000 Image Compression (Lossless Only)

optional

optional

1.2.840.10008.1.2.4.91

JPEG 2000 Image Compression

optional

optional

1.2.840.10008.1.2.4.92

JPEG 2000 Part 2 Multi-component Image Compression (Lossless Only)

optional

optional

1.2.840.10008.1.2.4.93

JPEG 2000 Part 2 Multi-component Image Compression

optional

optional

Multi-frame Image

1.2.840.10008.1.2.1

Explicit VR Little Endian

default

default

1.2.840.10008.1.2.4.90

JPEG 2000 Image Compression (Lossless Only)

optional

optional

1.2.840.10008.1.2.4.91

JPEG 2000 Image Compression

optional

optional

1.2.840.10008.1.2.4.92

JPEG 2000 Part 2 Multi-component Image Compression (Lossless Only)

optional

optional

1.2.840.10008.1.2.4.93

JPEG 2000 Part 2 Multi-component Image Compression

optional

optional

Video

1.2.840.10008.1.2.1

Explicit VR Little Endian

default

default

1.2.840.10008.1.2.4.100

MPEG2 Main Profile / Main Level

optional

optional

1.2.840.10008.1.2.4.101

MPEG2 Main Profile / High Level

optional

optional

1.2.840.10008.1.2.4.102

MPEG-4 AVC/H.264 High Profile / Level 4.1

optional

optional

1.2.840.10008.1.2.4.103

MPEG-4 AVC/H.264 BD-compatible High Profile / Level 4.1

optional

optional

1.2.840.10008.1.2.4.104

MPEG-4 AVC/H.264 High Profile / Level 4.2 For 2D Video

optional

optional

1.2.840.10008.1.2.4.105

MPEG-4 AVC/H.264 High Profile / Level 4.2 For 3D Video

optional

optional

1.2.840.10008.1.2.4.106

MPEG-4 AVC/H.264 Stereo High Profile / Level 4.2

optional

optional


Table 6.1.1.8-3a and Table 6.1.1.8-3b specify, by Resource Category (see Table 6.1.1-1) , the various media types for bulk data, along with the default and allowed media types and Transfer Syntax UID combinations for each resource category for the RS service.

Note

No entries are specified for the WADO-URI service, because it does not support separate retrieval of bulk data.

These media types can be used to retrieve image or video bulk data encoded in a specific Transfer Syntax.

Table 6.1.1.8-3a. Media Types and Transfer Syntax UIDs for Uncompressed Pixel Data in Bulk Data Values

Category

MediaType

Transfer SyntaxUID

Transfer Syntax Name

RS

Single Frame Image

application/octet-stream

1.2.840.10008.1.2.1

Explicit VR Little Endian

default

Multi-frame Image

application/octet-stream

1.2.840.10008.1.2.1

Explicit VR Little Endian

default

Video

application/octet-stream

1.2.840.10008.1.2.1

Explicit VR Little Endian

default


Table 6.1.1.8-3b. Media Types and Transfer Syntax UIDsfor Compressed Pixel Data in Bulk Data Values

Category

MediaType

Transfer SyntaxUID

Transfer Syntax Name

RS

Single Frame Image

image/jpeg

1.2.840.10008.1.2.4.70

JPEG Lossless, Non-Hierarchical, First-Order Prediction(Process 14 [Selection Value 1]) :Default Transfer Syntax for Lossless JPEG Image Compression

default

1.2.840.10008.1.2.4.50

JPEG Baseline (Process 1) :Default Transfer Syntax for Lossy JPEG 8 Bit Image Compression

optional

1.2.840.10008.1.2.4.51

JPEG Extended (Process 2 & 4) :Default Transfer Syntax for Lossy JPEG 12 Bit Image Compression (Process 4 only)

optional

1.2.840.10008.1.2.4.57

JPEG Lossless, Non-Hierarchical (Process 14)

optional

image/x-dicom-rle

1.2.840.10008.1.2.5

RLE Lossless

default

image/x-jls

1.2.840.10008.1.2.4.80

JPEG-LS Lossless Image Compression

default

1.2.840.10008.1.2.4.81

JPEG-LS Lossy (Near-Lossless) Image Compression

optional

image/jp2

1.2.840.10008.1.2.4.90

JPEG 2000 Image Compression (Lossless Only)

default

1.2.840.10008.1.2.4.91

JPEG 2000 Image Compression

optional

image/jpx

1.2.840.10008.1.2.4.92

JPEG 2000 Part 2 Multi-component Image Compression (Lossless Only)

default

1.2.840.10008.1.2.4.93

JPEG 2000 Part 2 Multi-component Image Compression

optional

Multi-frame Image

image/jpeg

1.2.840.10008.1.2.4.70

JPEG Lossless, Non-Hierarchical, First-Order Prediction(Process 14 [Selection Value 1]) :Default Transfer Syntax for Lossless JPEG Image Compression

default

1.2.840.10008.1.2.4.50

JPEG Baseline (Process 1) :Default Transfer Syntax for Lossy JPEG 8 Bit Image Compression

optional

1.2.840.10008.1.2.4.51

JPEG Extended (Process 2 & 4) :Default Transfer Syntax for Lossy JPEG 12 Bit Image Compression (Process 4 only)

optional

1.2.840.10008.1.2.4.57

JPEG Lossless, Non-Hierarchical (Process 14)

optional

image/x-dicom-rle

1.2.840.10008.1.2.5

RLE Lossless

default

image/x-jls

1.2.840.10008.1.2.4.80

JPEG-LS Lossless Image Compression

default

1.2.840.10008.1.2.4.81

JPEG-LS Lossy (Near-Lossless) Image Compression

optional

image/jp2

1.2.840.10008.1.2.4.90

JPEG 2000 Image Compression (Lossless Only)

default

1.2.840.10008.1.2.4.91

JPEG 2000 Image Compression

optional

image/jpx

1.2.840.10008.1.2.4.92

JPEG 2000 Part 2 Multi-component Image Compression (Lossless Only)

default

1.2.840.10008.1.2.4.93

JPEG 2000 Part 2 Multi-component Image Compression

optional

Video

video/mpeg2

1.2.840.10008.1.2.4.100

MPEG2 Main Profile / Main Level

optional

1.2.840.10008.1.2.4.101

MPEG2 Main Profile / High Level

default

video/mp4

1.2.840.10008.1.2.4.102

MPEG-4 AVC/H.264 High Profile / Level 4.1

default

1.2.840.10008.1.2.4.103

MPEG-4 AVC/H.264 BD-compatible High Profile / Level 4.1

optional

1.2.840.10008.1.2.4.104

MPEG-4 AVC/H.264 High Profile / Level 4.2 For 2D Video

optional

1.2.840.10008.1.2.4.105

MPEG-4 AVC/H.264 High Profile / Level 4.2 For 3D Video

optional

1.2.840.10008.1.2.4.106

MPEG-4 AVC/H.264 Stereo High Profile / Level 4.2

optional


The Implicit VR Little Endian (1.2.840.10008.1.2) ,and Explicit VR Big Endian (1.2.840.10008.1.2.2) transfer syntaxes shall not be used with Web Services.

If a transfer syntax parameter for a DICOM Media Type is not specified in a request or response, the Transfer Syntax in the response shall be the Transfer Syntax specified as the default for the Resource Category and media type combination in Table 6.1.1.8-3a or Table 6.1.1.8-3b.

The origin server may support additional Transfer Syntaxes.

Note

  1. The compressed bulk data of each part of a multipart payload contains only the compressed bit stream and not the DICOM PS3.5 Encapsulated Sequence or Delimiter Items.

  2. For the media type image/dicom+jpeg Transfer Syntaxes, the image may or may not include the JFIF marker segment. See Section 8.2.1 “JPEG Image Compression” in PS3.5 .

  3. For the media type image/dicom+jp2 and image/dicom+jpx Transfer Syntaxes, the image does not include the jp2 marker segment. See Section 8.2.4 “JPEG 2000 Image Compression” in PS3.5 and Section A.4.4 “JPEG 2000 Image Compression” in PS3.5 .

  4. The resource on the origin server may have been encoded in the Deflated Explicit VR Little Endian (1.2.840.10008.1.2.1.99) transfer syntax. If so, the origin server may inflate it, and then convert it into an Acceptable Transfer Syntax. Alternatively, if the user-agent allowed a Content-Encoding header field of 'deflate', then the deflated bytes may be transferred unaltered, but the transfer syntax parameter in the response should be the Explicit VR Little Endian transfer syntax.

  5. Compressed multi-frame image bulk data is encoded as one frame per part. E.g., each frame of a JPEG 2000 multi-frame image will be encoded as a separate part with an image/jp2 media type, rather than as a single part with a video/mj2 (RFC 3745) or uncompressed application/octet-stream media type.

  6. Video bulk data is encoded as a single part containing all frames. E.g., all frames of an MPEG-4 video will be encoded as a single part with a video/mp4 (RFC 4337) media type.

  7. Many of the media types used for compressed Pixel Data transferred as bulk data values are also used for consumer format media types. The browser may not be able to display the encoded data directly, even though some of the same media types are also used for encoding rendered Pixel Data; see Section 6.1.1.3.

    E.g., the media type for bulk data values of lossless 16-bit JPEG 10918-1 encoded Pixel Data is "image/jpeg", the same as might be used for 8-bit JPEG 10918-1 encoded Pixel Data, whether extracted as bulk data, or rendered. The transfer syntax parameter of the Content-Type header field is useful to signal the difference.

6.1.1.8.1 DICOM Media Type Syntax

The syntax of DICOM Media Types is:

    dicom-media-type = (dcm-singlepart / dcm-multipart) [dcm-parameters]

Where

    dcm-singlepart = dcm-mt-name
    dcm-multipart                                  ; see Section 6.1.1.8.1.1.
    dcm-parameters = transfer-syntax-mtp           ; see Section 6.1.1.8.1.2.
                   / charset-mtp                   ; see Section 6.1.1.8.1.3.
    dcm-mt-name = dicom / dicom-xml / dicom-json   ; DICOM Media Type name
    dicom = "application/dicom"
    dicom-xml = "application/dicom+xml
    dicom-json = "application/dicom+json"
    octet-stream = "application/octet-stream"

All DICOM Media Types may have a transfer syntax parameter, but its usage may be constrained by the service for which they are used.

Note

Note. The application/dicom+xml and application/dicom+json Media Types may have a transfer syntax parameter in order to specify the encoding of inline binary data.

All DICOM Media Types may have a character set parameter, but its usage may be constrained by the service for which they are used.

6.1.1.8.1.1 DICOM Multipart Media Types

The syntax of multipart media types is:

    dcm-multipart = "multipart/related"
    OWS ";" OWS "type" "=" dcm-mp-mt-name
    OWS ";" OWS "boundary=" boundary
    [dcm-parameters]
    [related-parameters]

Where

    dcm-mp-mt-name = dicom / dicom-xml / dicom-json / octet-stream

See Section 6.1.1.1 for the definition of boundary and related-parameters.

Each multipart media type shall include a "type" parameter that defines the media type of the parts, and shall also include a "boundary" parameter that specifies the boundary string that is used to separate the parts.

6.1.1.8.1.2 Transfer Syntax Parameter

All DICOM Media Types may have a single transfer syntax parameter, but its usage may be constrained by the service for which they are used.

RS origin servers shall support the transfer syntax parameter.

Transfer syntax parameters are forbidden in URI requests and responses.

The syntax is:

    transfer-syntax-mtp = OWS ";" OWS $s"transfer-syntax=" ts-value
    ts-value = transfer-syntax-uid / "*"
    transfer-syntax-uid ; a UID from PS3.6 Table A-1 with a UID Type of Transfer Syntax

The value of the transfer syntax parameter may be either a Transfer Syntax UID or the token "*".

For example, to specify that 1.2.840.10008.1.2.4.50 is the acceptable Transfer Syntaxes, an Accept header field could be:

    Accept: application/dicom; transfer-syntax=1.2.840.10008.1.2.4.50

A DICOM Media Type may only have one transfer syntax parameter and it shall have only one value.

Note

Per RFC 6838 Media Type Specifications and Registration Procedures, it is an error for a specific parameter to be specified more than once. If a choice of Transfer Syntaxes is acceptable. more than one media type may be provided in the Accept header with different q parameter values to indicate preference. E.g., to specify that 1.2.840.10008.1.2.4.50 and to specify that 1.2.840.10008.1.2.4.57 are acceptable but 1.2.840.10008.1.2.4.50 is preferred, an Accept header field could be:

    Accept: multipart/related; application/dicom;transfer-syntax=1.2.840.10008.1.2.4.50,
            application/dicom;transfer-syntax=1.2.840.10008.1.2.4.57;q=0.5

The wildcard value "*" indicates that the user agent will accept any Transfer Syntax. This allows, for example, the origin server to respond without needing to transcode an existing representation to a new Transfer Syntax, or to respond with the Explicit VR Little Endian Transfer Syntax regardless of the Transfer Syntax stored.

If an Origin server supports the transfer syntax parameter, it shall support the wildcard value.

Origin servers that support the transfer syntax parameter shall specify in their conformance statement those values of transfer syntax parameter that are supported in the response.

User agents that support the transfer syntax parameter shall specify in their conformance statement those transfer syntax parameter values that may be supplied in the request.

6.1.1.8.1.3 Character Set Parameter

The DICOM Media Type character set parameter is used to specify Acceptable Character Sets for the response. A DICOM Media Type may have a single character set parameter, which shall have only a single value.

The syntax is:

    charset-mtp = OWS ";" OWS %s"charset" "=" charset

All DICOM Media Types shall have a Default Character Set of UTF-8.

See Section 6.1.2 for character set details.

6.1.1.8.2 Transfer Syntax Query Parameter

The transfer syntax query parameter specifies a comma-separated list of one or more Transfer Syntax UIDs, as defined in PS3.6. It is optional.

The syntax is:

    transfer-syntax-qp = ts-parameter-name "=" (1#transfer-syntax-uid / "*")
    ts-parameter-name = %s quoted-string

The URI service defines the ts-parameter-name to be "transferSyntax", which is case-sensitive.

The RS service uses the transfer syntax parameter in the "accept" query parameter (see Section 6.1.1.5) and the transfer syntax query parameter is not supported.

6.1.1.8.3 Acceptable Transfer Syntaxes

Each media type in the Acceptable Media Types has an associated set of Acceptable Transfer Syntaxes.

The Acceptable Transfer Syntaxes for a media type can be specified in any of the following ways, depending on the service:

  1. The transfer syntax media type parameter contained in the accept query parameter (see Section 6.1.1.5)

  2. The value(s) contained in the transfer syntax query parameter (see Section 6.1.1.8.4)

  3. The transfer syntax media type parameter contained in the Accept header field.

6.1.1.8.4 Selected Transfer Syntax

The Selected Transfer Syntax is the transfer syntax selected by the origin server to encode a single message part in the response.

The origin server shall first determine the Selected Media Type as defined in Section 6.1.1.7 and then determine the Selected Transfer Syntax.

If the Selected Media Type was contained in the accept query parameter, then the Selected Transfer Syntax is determined as follows:

  1. Select the value of the transfer syntax parameter of the Selected Media Type, if any;

  2. Otherwise, select the value of the transfer syntax in the transfer syntax query parameter value for the Selected Media Type, if any;

  3. Otherwise select the default transfer syntax for the Selected Media Type

If the Selected Media Type was contained in the Accept header field, then the Selected Transfer Syntax is determined as follows:

  1. Select the transfer syntax parameter for the Selected Media Type, if any;

  2. Otherwise, select the default transfer syntax for the Selected Media Type.

Note

  1. The Selected Transfer Syntax may be different for each message part contained in a response.

  2. Implementers may use a different selection algorithm as long as the result is the same.

6.1.1.8.5 Support For DICOM Media Types by Service

The URI and RS APIs support the following DICOM Media Types:

    uri-media-type = dicom
    rs-media-types = (dcm-multipart / dicom-json) [dcm-parameters]

Support for the transfer syntax and charset media type parameters is required for RS services.

Support for the "transfer-syntax" and "charset" parameters is forbidden for URI Services (i.e., they may not present in the request or the response).

6.1.2 Character Sets

HTTP uses charset names to indicate or negotiate the character encoding of textual content in representations [RFC6365] Section 3.3.

Character sets may be identified using the value in the IANA Preferred MIME Name column in the IANA Character Set Registry http://www.iana.org/assignments/character-sets/character-sets.xhtml.

Character sets may be identified by using the DICOM Defined Terms for the character set. See Section C.12.1.1.2 “Specific Character Set” in PS3.3 , and Section 6.1.2.3 “Encoding of Character Repertoires” in PS3.5 .

The origin server shall support the "UTF-8" charset name for RS Retrieve Rendered, but is not required to support the DICOM Defined Term "ISO_IR 192".

The syntax is:

    charset = token / defined-term / DQUOTE defined-term DQUOTE

Where

token

A case-insensitive charset name from the Preferred MIME Name in the IANA Character Set Registry.

defined-term

See Section C.12.1.1.2 “Specific Character Set” in PS3.3 .

Some DICOM Defined Terms for character sets contain space characters; and shall be enclosed in double quotes in HTTP header fields and percent encoded in URLs.

The Conformance Statement shall document all supported character sets. The Retrieve Capabilities response for all RS Services shall also document all supported character sets.

A request without any <charset> query parameter or Accept-Charset header field implies that the user agent will accept any charset in the response.

Annex D contains a mapping of some Specific Character Set (0008,0005) Defined Terms to IANA charset tokens.

6.1.2.1 Acceptable Character Sets

The term Acceptable Character Sets denotes the character sets that are acceptable to the user agent in the response. The Acceptable Character Sets are those specified in:

  • the "charset" media type parameter

  • the <character-set> query parameter

  • the Accept-Charset header field

  • the default character set for the media type, if any

When the Acceptable Character Sets contains a list of one or more Defined Terms they should be ordered as specified in Section C.12.1.1.2 “Specific Character Set” in PS3.3 and Section 6.1.2.3 “Encoding of Character Repertoires” in PS3.5 . This is especially important for ISO 2022 character sets.

Any Accept-Charset header field values that are not defined in Annex D or not supported shall be ignored.

6.1.2.2 Character Set Query Parameter

The character set query parameter is primarily designed for use in hyperlinks (URLs) embedded in documents, where the Accept-Charset header field is not accessible.

The character set query parameter has the following syntax:

    charset-qp = name "=" 1#(charset [weight])

The character set query parameter value is a comma-separated list of one or more charsets. It is similar to the Accept-Charset header field, except that it shall not have wildcards. It shall be supported by the origin server. It is optional for the user agent.

All charsets present in the character set query parameter may have a corresponding character set in the Accept-Charset header field, either explicitly or implicitly through wildcards.

The name of the character set query parameter is defined by the Service. Table 6.1.2-1 contains the names of the character set query parameter for some services.

Table 6.1.2-1. Character Set Query Parameter Name by Service

Service

Name

URI

name = "charset"

RS Studies

name = "charset"


If this parameter has a value that is not supported it shall be ignored.

See Section 6.1.4.

6.1.2.3 Accept-Charset Header Field

The Accept-Charset header field has the following syntax:

    Accept-Charset = 1#(charset [weight]) / ("*" [weight])

The user agent may provide a list of Acceptable Character Sets in the Accept-Charset header field of the request. Its value is a comma-separated list of one or more <charset>s and/or the wildcard value ("*"). It shall be supported by the origin server. It is optional for the user agent.

The values of the Accept-Charset header field values are prioritized by their <weight> parameter.

If no wildcard ("*") is present, then any character sets not explicitly mentioned in the header field are considered "not acceptable" to the client.

A request without an Accept-Charset header field implies that the user agent will accept any charset in response.

If the media type defines a "charset" parameter, it should be included with the media type in the Accept header field, rather than in the Accept-Charset header field.

Any Accept-Charset header field values that are not supported shall be ignored.

6.1.2.4 Selected Character Set

The origin server shall determine the Selected Character Set(s) as follows:

  1. Select the first supported character set in the "charset" parameter(s) of the Selected Media Type.

  2. Otherwise, select the highest priority supported <charset> in the <character-set> query parameter.

  3. Otherwise, select the highest priority supported <charset> in the Accept-Charset header field.

  4. Otherwise, if the Selected Media Type has a default character set that is supported, select it.

  5. Otherwise, select UTF-8.

Rendered representations returned in the response shall have all contained strings returned in the Selected Character Sets.

If the character set in which the target resource is encoded is not the Selected CharacterSet:

  • If the origin server supports transcoding all glyphs used in the target resource into the Selected Character Set,it shall transcode the response payload into the Selected Character Set

  • Otherwise, the origin server shall return 406 (Not Acceptable).

Note

This means that some SOP Instances may be convertible and others will not be, even though they have the same Specific Character Set (0008,0005).

All origin servers shall support conversion to the UTF-8 character set for RS Rendered Retrieve.

If the user agent chooses to perform its own conversion rather than have it done by the origin server:

  1. The user agent may omit the Accept-Charset header field or send the "*" wildcard

  2. The user agent may transcode the character set replacing all unknown characters with a suitable replacement. For example:

6.1.3 Content-type Header Field

The Content-Type header field specifies the media type of the payload. It should only be present when a payload is present, and any media type parameters shall specify the encoding of the corresponding message part.

In particular, a DICOM Media Type used as the value of a Content-Type header field shall have zero or one transfer syntax parameter (see Section 6.1.1.8.1.2), and zero or one charset parameter (see Section 6.1.1.8.1.3), which corresponds to the character encoding of the corresponding message part.

    Content-Type: dicom-media-type +transfer-syntax-mtp +charset-mtp

If there is a conflict between the Transfer Syntax specified in the media type and the one specified in the File Meta Information Transfer Syntax UID (0002,0010) attribute, the latter has precedence.

6.1.4 Content-type Header Field

[RFC3986] does not permit an empty query component, i.e., if the "?" appears in the Target URI, then there shall be at least one Query Parameter in the URI.

The origin server may define and support additional Query Parameters, or additional Query Parameter values for an existing Query Parameter. If an origin server defines new or extends existing Query Parameters, they shall be included in the Conformance Statement and, if the service supports it, the Retrieve Capabilities response.

The origin server shall ignore any unsupported Query Parameters. The origin server shall process the request as if the unsupported parameters were not present, and should include a payload containing an appropriate warning or error message.

If a supported Query Parameter has an invalid value, the origin server shall return a 400 (Bad Request) error response, and should include should include a payload containing an appropriate warning or error message.

DICOM PS3.18 2017d - Web Services