PS3.18

DICOM PS3.18 2022c - Web Services

DICOM Standards Committee

A DICOM® publication


Table of Contents

Notice and Disclaimer
Foreword
1. Scope
2. Normative References
Bibliography
3. Definitions
Glossary
4. Symbols and Abbreviated Terms
5. Conventions
5.1. Message Syntax
5.1.1. Common Syntactic Rules For Data Types
5.1.2. URI Templates
5.1.3. List Rule('#')
5.2. Web Service Section Structure
5.3. Request and Response Header Field Tables
6. Conformance
7. Overview of DICOM Web Services (Informative)
7.1. DICOM Web Service Types
7.1.1. URI Web Service
7.1.2. RESTful Web Services and Resources
7.2. Resources, Representations, and Target URIs
7.2.1. DICOM Restful Resources
7.2.2. Representations
7.2.3. Target URIs
8. Common Aspects of DICOM Web Services
8.1. Transactions
8.1.1. Request Message Syntax
8.1.1.1. Method
8.1.1.2. Target Resource
8.1.1.3. Query Parameters
8.1.1.4. Request Header Fields
8.1.1.5. Request Payload
8.1.2. Response Message Syntax
8.1.2.1. Status Codes
8.1.2.2. Response Header Fields
8.1.2.3. Response Payload
8.2. Target Resources
8.3. Query Parameters
8.3.1. Query Parameter Syntax
8.3.1.1. Query Parameter Syntax
8.3.2. Query Parameter Usage
8.3.3. Content Negotiation Query Parameters
8.3.3.1. Accept Query Parameter
8.3.3.2. Character Set Query Parameter
8.3.4. Search Query Parameters
8.3.4.1. Attribute Matching
8.3.4.1.1. Matching Rules
8.3.4.2. Fuzzy Matching of Person Names
8.3.4.3. Attributes Included in the Response
8.3.4.4. Response Pagination
8.3.4.4.1. Paging Behavior
8.3.5. Rendering Query Parameters
8.3.5.1. Query Parameters For Rendered Resources
8.3.5.1.1. Image Annotation
8.3.5.1.2. Image Quality
8.3.5.1.3. Viewport Scaling
8.3.5.1.4. Windowing
8.3.5.1.5. ICC Profile
8.3.5.2. Query Parameters For Thumbnails
8.4. Header Fields
8.4.1. Content Negotiation Header Fields
8.4.1.1. Accept
8.4.1.1.1. Charset Media Type Parameter
8.4.2. Content Representation Header Fields
8.4.3. Payload Header Fields
8.5. Status Codes
8.6. Payloads
8.6.1. Payload Structure
8.6.1.1. Single Part Payload
8.6.1.2. Multipart Payload
8.6.1.2.1. Multipart Payload Syntax
8.6.2. DICOM Representations
8.6.2.1. Web Service Constraints
8.6.3. Status Report
8.7. Media Types
8.7.1. Multipart Media Types
8.7.2. DICOM Resource Categories
8.7.3. DICOM Media Type Sets
8.7.3.1. Instance Media Types
8.7.3.2. Metadata Media Types
8.7.3.3. Bulkdata Media Types
8.7.3.3.1. Uncompressed Bulkdata Media Types
8.7.3.3.2. Compressed Bulkdata Media Types
8.7.3.4. Transfer Syntax
8.7.3.5. Media Type Syntax
8.7.3.5.1. Multipart Media Types
8.7.3.5.2. Transfer Syntax Parameter
8.7.3.5.3. Character Set Parameter
8.7.3.6. Transfer Syntax Query Parameter
8.7.3.7. Acceptable Transfer Syntaxes
8.7.4. Rendered Media Types
8.7.5. Acceptable Media Types
8.7.6. Accept Query Parameter
8.7.7. Accept Header Field
8.7.8. Selected Media Type and Transfer Syntax
8.7.8.1. Selected Media Type
8.7.8.2. Selected Transfer Syntax
8.7.9. Content-Type Header Field
8.8. Character Sets
8.8.1. Acceptable Character Sets
8.8.2. Character Set Query Parameter
8.8.3. Character Set Media Type Parameters
8.8.4. Accept-charset Header Field
8.8.5. Selected Character Set
8.9. Retrieve Capabilities Transaction
8.9.1. Request
8.9.1.1. Resource
8.9.1.2. Query Parameters
8.9.1.3. Request Header Fields
8.9.1.4. Request Payload
8.9.2. Behavior
8.9.3. Response
8.9.3.1. Status Codes
8.9.3.1.1. Response Header Fields
8.9.3.2. Response Payload
8.9.4. Media Types
8.10. Notifications
8.10.1. Overview
8.10.2. Conformance
8.10.3. Transaction Overview
8.10.4. Open Notification Connection Transaction
8.10.4.1. Request
8.10.4.1.1. Target Resources
8.10.4.1.2. Query Parameters
8.10.4.1.3. Request Header Fields
8.10.4.1.4. Request Payload
8.10.4.2. Behavior
8.10.4.3. Response
8.10.4.3.1. Status Codes
8.10.4.3.2. Response Header Fields
8.10.4.3.3. Response Payload
8.10.5. Send Event Report Transaction
8.10.5.1. Request
8.10.5.1.1. Request Payload
8.10.5.2. Behavior
8.10.5.3. Response
8.11. Security and Privacy
9. URI Service
9.1. Overview
9.1.1. Resource Descriptions
9.1.2. Common Query Parameters
9.1.2.1. Mandatory Query Parameters
9.1.2.1.1. Request Type
9.1.2.1.2. Study UID
9.1.2.1.3. Series UID
9.1.2.1.4. Instance UID
9.1.2.2. Optional Query Parameters
9.1.2.2.1. Acceptable Media Types
9.1.2.2.2. Acceptable Character Sets
9.1.3. Common Media Types
9.2. Conformance
9.3. Transactions Overview
9.4. Retrieve DICOM Instance Transaction
9.4.1. Request
9.4.1.1. Target Resource
9.4.1.2. Query Parameters
9.4.1.2.1. Anonymize
9.4.1.2.2. Annotation
9.4.1.2.3. Transfer Syntax
9.4.1.3. Request Header Fields
9.4.1.4. Request Payload
9.4.2. Behavior
9.4.2.1. Request Type
9.4.2.2. Study, Series, and Instance UIDs
9.4.2.3. Anonymize
9.4.2.4. Transfer Syntax UID
9.4.3. Response
9.4.3.1. Status Codes
9.4.3.2. Response Header Fields
9.4.3.3. Response Payload
9.5. Retrieve Rendered Instance Transaction
9.5.1. Request
9.5.1.1. Target Resource
9.5.1.2. Query Parameters
9.5.1.2.1. Frame Number
9.5.1.2.2. Image Annotation
9.5.1.2.3. Image Quality
9.5.1.2.4. Viewport
9.5.1.2.4.1. Viewport Rows
9.5.1.2.4.2. Viewport Columns
9.5.1.2.5. Source Image Region
9.5.1.2.6. Windowing
9.5.1.2.6.1. Window Center
9.5.1.2.6.2. Window Width
9.5.1.2.7. Presentation State
9.5.1.2.7.1. Presentation Series UID
9.5.1.2.7.2. Presentation UID
9.5.1.3. Request Header Fields
9.5.1.4. Request Payload
9.5.2. Behavior
9.5.2.1. Frame Number
9.5.2.2. Windowing
9.5.2.3. Presentation State
9.5.2.4. Source Image Region
9.5.2.5. Viewport
9.5.3. Response
9.5.3.1. Status Codes
9.5.3.2. Response Header Fields
9.5.3.3. Response Payload
10. Studies Service and Resources
10.1. Overview
10.1.1. Resource Descriptions
10.1.2. Common Query Parameters
10.1.3. Common Media Types
10.2. Conformance
10.3. Transactions Overview
10.4. Retrieve Transaction
10.4.1. Request
10.4.1.1. Target Resources
10.4.1.1.1. Instance Resources
10.4.1.1.2. Metadata Resources
10.4.1.1.3. Rendered Resources
10.4.1.1.4. Thumbnail Resources
10.4.1.1.5. Bulkdata Resources
10.4.1.1.6. Pixel Data Resources
10.4.1.2. Query Parameters
10.4.1.3. Request Header Fields
10.4.1.4. Request Payload
10.4.2. Behavior
10.4.3. Response
10.4.3.1. Status Codes
10.4.3.2. Response Header Fields
10.4.3.3. Response Payload
10.4.3.3.1. Instance Resource Payload
10.4.3.3.2. Metadata Resource Payload
10.4.3.3.3. Rendered Resource Payload
10.4.3.3.4. Thumbnail Resource Payload
10.4.3.3.5. Bulkdata Resource Payload
10.4.3.3.6. Pixel Data Resource Payload
10.4.4. Media Types
10.4.5. Conformance Statement
10.5. Store Transaction
10.5.1. Request
10.5.1.1. Target Resources
10.5.1.1.1. DICOM Resources
10.5.1.2. Query Parameters
10.5.1.3. Request Header Fields
10.5.1.4. Request Payload
10.5.2. Behavior
10.5.3. Response
10.5.3.1. Status Codes
10.5.3.2. Response Header Fields
10.5.3.3. Response Payload
10.5.4. Media Types
10.5.5. Conformance Statement
10.6. Search Transaction
10.6.1. Request
10.6.1.1. Target Resources
10.6.1.2. Query Parameters
10.6.1.2.1. Attribute/Value Pair Requirements
10.6.1.2.2. Search Key Types and Requirements
10.6.1.2.3. Required Matching Attributes
10.6.1.3. Request Header Fields
10.6.1.4. Request Payload
10.6.2. Behavior
10.6.3. Response
10.6.3.1. Status Codes
10.6.3.2. Response Header Fields
10.6.3.3. Response Payload
10.6.3.3.1. Study Resource
10.6.3.3.2. Series Resources
10.6.3.3.3. Instance Resources
10.6.4. Media Types
10.6.5. Conformance Statement
11. Worklist Service and Resources
11.1. Overview
11.1.1. Resource Description
11.1.1.1. Workitems
11.1.1.2. Web Services and DIMSE Terminology
11.1.2. Common Query Parameters
11.1.3. Common Media Types
11.2. Conformance
11.3. Transactions Overview
11.4. Create Workitem Transaction
11.4.1. Request
11.4.1.1. Target Resources
11.4.1.2. Query Parameters
11.4.1.3. Request Header Fields
11.4.1.4. Request Payload
11.4.2. Behavior
11.4.3. Response
11.4.3.1. Status Codes
11.4.3.2. Response Header Fields
11.4.3.3. Response Payload
11.5. Retrieve Workitem Transaction
11.5.1. Request
11.5.1.1. Target Resources
11.5.1.2. Query Parameters
11.5.1.3. Request Header Fields
11.5.1.4. Request Payload
11.5.2. Behavior
11.5.3. Response
11.5.3.1. Status Codes
11.5.3.2. Response Header Fields
11.5.3.3. Response Payload
11.6. Update Workitem Transaction
11.6.1. Request
11.6.1.1. Target Resources
11.6.1.2. Query Parameters
11.6.1.3. Request Header Fields
11.6.1.4. Request Payload
11.6.2. Behavior
11.6.3. Response
11.6.3.1. Status Codes
11.6.3.2. Response Header Fields
11.6.3.3. Response Payload
11.7. Change Workitem State
11.7.1. Request
11.7.1.1. Target Resources
11.7.1.2. Query Parameters
11.7.1.3. Request Header Fields
11.7.1.4. Request Payload
11.7.2. Behavior
11.7.3. Response
11.7.3.1. Status Codes
11.7.3.2. Response Header Fields
11.7.3.3. Response Payload
11.8. Request Cancellation
11.8.1. Request
11.8.1.1. Target Resources
11.8.1.2. Query Parameters
11.8.1.3. Request Header Fields
11.8.1.4. Request Payload
11.8.2. Behavior
11.8.3. Response
11.8.3.1. Status Codes
11.8.3.2. Response Header Fields
11.8.3.3. Response Payload
11.9. Search Transaction
11.9.1. Request
11.9.1.1. Target Resources
11.9.1.2. Query Parameters
11.9.1.3. Request Header Fields
11.9.1.4. Request Payload
11.9.2. Behavior
11.9.3. Response
11.9.3.1. Status Codes
11.9.3.2. Response Header Fields
11.9.3.3. Response Payload
11.10. Subscribe Transaction
11.10.1. Request
11.10.1.1. Target Resources
11.10.1.2. Query Parameters
11.10.1.3. Request Header Fields
11.10.1.4. Request Payload
11.10.2. Behavior
11.10.3. Response
11.10.3.1. Status Codes
11.10.3.2. Response Header Fields
11.10.3.3. Response Payload
11.11. Unsubscribe Transaction
11.11.1. Request
11.11.1.1. Target Resources
11.11.1.2. Query Parameters
11.11.1.3. Request Header Fields
11.11.1.4. Request Payload
11.11.2. Behavior
11.11.3. Response
11.11.3.1. Status Codes
11.11.3.2. Response Header Fields
11.11.3.3. Response Payload
11.12. Suspend Global Subscription Transaction
11.12.1. Request
11.12.1.1. Target Resources
11.12.1.2. Query Parameters
11.12.1.3. Request Header Fields
11.12.1.4. Request Payload
11.12.2. Behavior
11.12.3. Response
11.12.3.1. Status Codes
11.12.3.2. Response Header Fields
11.12.3.3. Response Payload
11.13. Workitem Event Reports
12. Non-Patient Instance Service and Resources
12.1. Overview
12.1.1. Resource Descriptions
12.1.2. Common Query Parameters
12.1.3. Common Media Types
12.2. Conformance
12.3. Transactions Overview
12.4. Retrieve Transaction
12.4.1. Request
12.4.1.1. Target Resources
12.4.1.2. Query Parameters
12.4.1.3. Request Header Fields
12.4.1.4. Request Payload
12.4.2. Behavior
12.4.3. Response
12.4.3.1. Status Codes
12.4.3.2. Response Header Fields
12.4.3.3. Response Payload
12.5. Store Transaction
12.5.1. Request
12.5.1.1. Target Resources
12.5.1.2. Query Parameters
12.5.1.3. Request Header Fields
12.5.1.4. Request Payload
12.5.2. Behavior
12.5.3. Response
12.5.3.1. Status Codes
12.5.3.2. Response Header Fields
12.5.3.3. Response Payload
12.6. Search Transaction
12.6.1. Request
12.6.1.1. Target Resources
12.6.1.2. Query Parameters
12.6.1.3. Request Header Fields
12.6.1.4. Request Payload
12.6.2. Behavior
12.6.3. Response
12.6.3.1. Status Codes
12.6.3.2. Response Header Fields
12.6.3.3. Response Payload
A. Collected ABNF
B. Examples (Informative)
B.1. Retrieving a Simple DICOM Image in JPEG
B.2. Retrieving a DICOM SR in HTML
B.3. Retrieving a Region of A DICOM Image
B.4. Retrieving As A DICOM Media Type
B.5. Query Studies From a Certain Day and Limit the Number of Results, Start With Offset 0
B.6. Query Series From a Certain Study, Returned Data in JSON
B.7. Query Instances From a Series, Returned Data in XML
B.8. Retrieve Instance as DICOM
B.9. Retrieve Instance as Rendered JPEG Image
B.10. Retrieve Instance as Bulk Data
B.11. Retrieving a DICOM Image Object Using the Baseline 8-Bit Lossy JPEG Transfer Syntax
B.12. Rendering a Region of a DICOM Image, Converted in JPEG2000, With Annotations Burned Into the Image Containing the Patient Name and Technical Information, and Using a Specific Viewport and Windowing
B.13. Retrieve DICOM SR as HTML
B.14. Retrieve DICOM SR as JSON (only Metadata)
B.15. Check for Capability of Retrieving Metadata as XML
B.16. Retrieve Metadata as XML Using "accept" Parameter
B.17. Retrieve DICOM Frames as "octet-stream"
B.18. Retrieve DICOM Frames as Rendered in GIF Media Type
B.19. Retrieve Thumbnail for a Series in the JPEG Media Type
B.20. Retrieve Thumbnail for One Frame in the PNG Media Type
B.21. Store Single DICOM Instance
B.22. Store Multiple DICOM Instances
B.23. Store Multiple JPEG Files
B.24. Get All the Work Items
B.25. Cancel Work Item
C. Retired
D. IANA Character Set Mapping
E. Retired
F. DICOM JSON Model
F.1. Introduction to JavaScript Object Notation (JSON)
F.2. DICOM JSON Model
F.2.1. Multiple Results Structure
F.2.1.1. Examples
F.2.1.1.1. Native DICOM Model
F.2.1.1.2. DICOM JSON Model
F.2.2. DICOM JSON Model Object Structure
F.2.3. DICOM JSON Value Representation
F.2.4. DICOM JSON Value Multiplicity
F.2.5. DICOM JSON Model Null Values
F.2.6. BulkDataURI
F.2.7. InlineBinary
F.3. Transformation with other DICOM Formats
F.3.1. Native DICOM Model XML
F.4. DICOM JSON Model Example
F.5. Retired
G. WADL JSON Representation
G.1. Introduction
G.2. XML Elements
G.2.1. Doc Elements
G.2.2. Unique Elements
G.2.3. Repeatable Elements
H. Capabilities Description
I. Store Instances Response Module
I.1. Response Message Body
I.2. Store Instances Response Attribute Description
I.2.1. Warning Reason
I.2.2. Failure Reason
I.3. Response Message Body Example

List of Figures

7-1. DICOM Communication Model for Web Services
8.1-1. Interaction Diagram for Transactions
8.6-1. Mapping between IOD and HTTP message parts

List of Tables

5.1-1. ABNF for Common Syntactic Values
5.2-1. Request Header Fields
5.2-2. Response Header Fields
8.3.1-1. ABNF for Query Parameter
8.3.2-1. Query Parameter Usage
8.3.2-2. Example Query Parameter Table
8.3.4-1. Query Parameter Syntax
8.3.5-1. Retrieve Rendered Query Parameters
8.3.5-2. Thumbnail Query Parameters
8.4.1-1. Content Negotiation Header Fields
8.4.2-1. Content Representation Header Fields
8.4.3-1. Payload Header Fields
8.5-1. Status Code Meaning
8.6.1-1. Multipart Header Fields
8.7.2-1. Resource Categories
8.7.3-1. Definition of Media Type Requirement
8.7.3-2. Transfer Syntax UIDs for application/dicom Media Types
8.7.3-3. Media Types for Metadata
8.7.3-4. Transfer Syntax UIDs for Uncompressed Data in Bulkdata
8.7.3-5. Media Types and Transfer Syntax UIDs for Compressed Data in Bulkdata
8.7.4-1. Rendered Media Types by Resource Category
8.7.8-1. Media Type QValue Example
8.9.1-1. Request Header Fields
8.9.3-1. Status Code Meaning
8.9.3-2. Response Header Fields
8.10.3-1. Notification Sub-System Transactions
8.10.4-1. Request Header Fields
8.10.4-2. Status Code Meaning
8.10.4-3. Response Header Fields
9.1.2-1. Mandatory Query Parameters
9.1.2-2. Optional Query Parameters
9.4.1-1. Optional Query Parameters
9.4.1-2. Request Header Fields
9.4.3-1. Status Code Meaning
9.4.3-2. Response Header Fields
9.5.1-1. Query Parameters
9.5.1-2. Request Header Fields
9.5.3-1. Status Code Meaning
9.5.3-2. Response Header Fields
10.1-1. Resources and Descriptions
10.1.2-1. Common Query Parameters
10.3-1. Studies Service Transactions
10.3-2. Resources by Transaction
10.4.1-1. Retrieve Transaction Instance Resources
10.4.1-2. Retrieve Transaction Metadata Resources
10.4.1-3. Retrieve Transaction Rendered Resources
10.4.1-4. Retrieve Transaction Thumbnail Resources
10.4.1.5-1. Retrieve Transaction Bulkdata Resources
10.4.1.6-1. Retrieve Transaction Pixel Data Resources
10.4.1-5. Query Parameters by Resource
10.4.1-6. Request Header Fields
10.4.3-1. Status Code Meaning
10.4.3-2. Response Header Fields
10.4.4-1. Default, Required, and Optional Media Types
10.5.1-1. Store Transaction DICOM Resources
10.5.1-2. Request Header Fields
10.5.2-1. Media Type Transformation to Transfer Syntaxes
10.5.3-1. Status Code Meaning
10.5.3-2. Response Header Fields
10.5.4-1. Default, Required, and Optional Media Types
10.6.1-1. Search Transaction Resources
10.6.1-2. Search Resource Descriptions
10.6.1-3. Search Key Types
10.6.1-4. Required IE Levels by Resource
10.6.1-5. Required Matching Attributes
10.6.1-6. Request Header Fields
10.6.3-1. Status Code Meaning
10.6.3-2. Response Header Fields
10.6.3-3. Study Resource Search Response Payload
10.6.3-4. Series Resources Search Response Payload
10.6.3-5. Instance Resources Search Response Payload
10.6.4-1. Default, Required, and Optional Media Types
11.1.1-1. Resources, URI Templates and Descriptions
11.1.1-2. Correspondence between RESTful and DIMSE Terminology
11.1.2-1. Common Query Parameters
11.1.3-1. Default, Required, and Optional Media Types
11.3-1. Worklist Service Methods and Resource Templates
11.4.1-1. Create Transaction Resources
11.4.1-3. Request Header Fields
11.4.3-1. Status Code Meaning
11.4.3-2. Response Header Fields
11.5.1-1. Request Header Fields
11.5.3-1. Status Code Meaning
11.5.3-2. Response Header Fields
11.6.1-1. Request Header Fields
11.6.3-1. Status Code Meaning
11.6.3-2. Response Header Fields
11.7.1-1. Request Header Fields
11.7.3-1. Status Code Meaning
11.7.3-2. Response Header Fields
11.8.1-1. Request Header Fields
11.8.3-1. Status Code Meaning
11.8.3-2. Response Header Fields
11.9.1-1. Request Header Fields
11.9.3-1. Status Code Meaning
11.9.3-2. Response Header Fields
11.10.1-1. Subscribe Transaction Resources
11.10.1-2. uery Parameters by Resource
11.10.3-1. Status Code Meaning
11.10.3-2. Response Header Fields
11.11.1-1. Unsubscribe Transaction Resources
11.11.3-1. Status Code Meaning
11.11.3-2. Response Header Fields
11.12.1-1. Unsubscribe Transaction Resources
11.12.3-1. Status Code Meaning
11.12.3-2. Response Header Fields
12.1.1-1. Resource Categories, URI Templates and Descriptions
12.1.2-1. Common Query Parameters
12.1.3-1. Default, Required, and Optional Media Types
12.2-1. Required and Optional Transactions
12.3-1. NPI Service Transactions
12.3-2. Resources by Transaction
12.4.1-1. Retrieve Transaction Resources
12.4.1-2. Request Header Fields
12.4.3-1. Status Code Meaning
12.4.3-2. Response Header Fields
12.5.1-1. Store Transaction Resources
12.5.1-2. Request Header Fields
12.5.3-1. Status Code Meaning
12.5.3-2. Response Header Fields
12.6.1-1. Search Transaction Resources
12.6.1-2. NPI Resource Search Attributes
12.6.1-3. Request Header Fields
12.6.3-1. Status Code Meaning
12.6.3-2. Response Header Fields
D-1. IANA Character Set Mapping
F.2.3-1. DICOM VR to JSON Data Type Mapping
F.3.1-1. XML to JSON Mapping
H-1. Resources and Methods
I.1-1. Store Instances Response Module Attributes
I.2-1. Store Instances Response Warning Reason Values
I.2-2. Store Instances Response Failure Reason Values

Notice and Disclaimer

The information in this publication was considered technically sound by the consensus of persons engaged in the development and approval of the document at the time it was developed. Consensus does not necessarily mean that there is unanimous agreement among every person participating in the development of this document.

NEMA standards and guideline publications, of which the document contained herein is one, are developed through a voluntary consensus standards development process. This process brings together volunteers and/or seeks out the views of persons who have an interest in the topic covered by this publication. While NEMA administers the process and establishes rules to promote fairness in the development of consensus, it does not write the document and it does not independently test, evaluate, or verify the accuracy or completeness of any information or the soundness of any judgments contained in its standards and guideline publications.

NEMA disclaims liability for any personal injury, property, or other damages of any nature whatsoever, whether special, indirect, consequential, or compensatory, directly or indirectly resulting from the publication, use of, application, or reliance on this document. NEMA disclaims and makes no guaranty or warranty, expressed or implied, as to the accuracy or completeness of any information published herein, and disclaims and makes no warranty that the information in this document will fulfill any of your particular purposes or needs. NEMA does not undertake to guarantee the performance of any individual manufacturer or seller's products or services by virtue of this standard or guide.

In publishing and making this document available, NEMA is not undertaking to render professional or other services for or on behalf of any person or entity, nor is NEMA undertaking to perform any duty owed by any person or entity to someone else. Anyone using this document should rely on his or her own independent judgment or, as appropriate, seek the advice of a competent professional in determining the exercise of reasonable care in any given circumstances. Information and other standards on the topic covered by this publication may be available from other sources, which the user may wish to consult for additional views or information not covered by this publication.

NEMA has no power, nor does it undertake to police or enforce compliance with the contents of this document. NEMA does not certify, test, or inspect products, designs, or installations for safety or health purposes. Any certification or other statement of compliance with any health or safety-related information in this document shall not be attributable to NEMA and is solely the responsibility of the certifier or maker of the statement.

Foreword

This DICOM Standard was developed according to the procedures of the DICOM Standards Committee.

The DICOM Standard is structured as a multi-part document using the guidelines established in [ISO/IEC Directives, Part 2].

PS3.1 should be used as the base reference for the current parts of this Standard.

DICOM® is the registered trademark of the National Electrical Manufacturers Association for its standards publications relating to digital communications of medical information, all rights reserved.

HL7® is the registered trademark of Health Level Seven International, all rights reserved.

1 Scope

PS3.18 specifies web services (using the HTTP family of protocols) for managing and distributing DICOM (Digital Imaging and Communications in Medicine) Information Objects, such as medical images, annotations, reports, etc. to healthcare organizations, providers, and patients. The term DICOMweb™ is used to designate the RESTful Web Services described here.

Security considerations, including access control, authorization, and auditing are beyond the scope of PS3.18. Refer to PS3.15.

2 Normative References

The following normative documents contain provisions that, through reference in this text, constitute provisions of this Part of DICOM. For dated references, subsequent amendments to, or revisions of, any of these publications do not apply. However, parties to agreements based on this Part of DICOM are encouraged to investigate the possibility of applying the most recent editions of the normative documents indicated below. For undated references, the latest edition of the normative document referred to applies. Members of ISO and IEC maintain registers of currently valid International Standards.

2.1 International Organization for Standardization (ISO) and International Electrotechnical Commission (IEC)

[ISO/IEC Directives, Part 2] ISO/IEC. 2016/05. 7.0. Rules for the structure and drafting of International Standards. http://www.iec.ch/members_experts/refdocs/iec/isoiecdir-2%7Bed7.0%7Den.pdf .

[ISO/IEC 2022] ISO/IEC. 1994. Information technology - Character code structure and extension techniques.

[ISO 7498-1] ISO. 1994. Information Processing Systems - Open Systems Interconnection - Basic Reference Model.

[ISO/IEC 10918-1] ISO/IEC. 1994. JPEG Standard for digital compression and encoding of continuous-tone still images. Part 1 - Requirements and implementation guidelines.

[ISO/IEC 10646] ISO/IEC. 2003. Information Technology - Universal Multiple-Octet Coded Character Set (UCS). ISO/IEC 10646-2003 is the same as Unicode Version 4.0, available at http://unicode.org .

[ISO 15076-1] ISO. 2005. Image technology colour management - Architecture, profile format, and data structure. Also available as ICC.1:2004-10 (Profile version 4.2.0.0), International Color Consortium, available at http://www.color.org/v4spec.xalter .

[ISO/IEC 15444-1] ISO/IEC. 2004. JPEG 2000 Image Coding System.

[ISO/IEC 15444-2] ISO/IEC. 2004. JPEG 2000 Image Coding System: Extensions.

[ISO 15948] ISO. 2003. Information technology -- Computer graphics and image processing -- Portable Network Graphics (PNG): Functional specification. A Joint ISO/IEC International Standard and W3C Recommendation. Also available at: https://www.w3.org/TR/2003/REC-PNG-20031110/ .

[ISO 22028-2] ISO. 2013. Photography and graphic technology - Extended colour encodings for digital image storage, manipulation and interchange - Part 2: Reference output medium metric RGB colour image encoding (ROMM RGB). http://www.iso.org/iso/catalogue_detail.htm?csnumber=56591 .

[IEC 61966-2.1] IEC. 1999. Ed 1.0 as amended by Amendment A1:2003. Multimedia systems and equipment - colour measurement and management - Part 2.1: colour management - Default RGB colour space - sRGB.

2.2 Internet Engineering Task Force (IETF) and Internet Assigned Names Authority (IANA)

[IANA Character Sets] IANA. . Character Sets. http://www.iana.org/assignments/character-sets/character-sets.xhtml .

[IANA HTTP Status Code Registry] IANA. . Hypertext Transfer Protocol (HTTP) Status Code Registry. http://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml .

[IANA Media Types] IANA. . Media Types. http://www.iana.org/assignments/media-types/media-types.xhtml .

[RFC822] IETF. August 1982. Standard for ARPA Internet Text Messages. http://tools.ietf.org/html/rfc822 .

[RFC1945] IETF. May 1996. Hypertext Transfer Protocol Version 1.0 (HTTP/1.0) . http://tools.ietf.org/html/rfc1945 .

[RFC2045] IETF. November 1996. Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies. http://tools.ietf.org/html/rfc2045 .

[RFC2046] IETF. November 1996. Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types. http://tools.ietf.org/html/rfc2046 .

[RFC2387] IETF. August 1998. The MIME Multipart/Related Content-type. http://tools.ietf.org/html/rfc2387 .

[RFC2818] IETF. May 2000. HTTP Over TLS. http://tools.ietf.org/html/rfc2818 .

[RFC2978] IETF. October 2000. IANA Charset Registration Procedures. http://tools.ietf.org/html/rfc2978 .

[RFC3240] IETF. February 2002. Digital Imaging and Communications in Medicine (DICOM) - Application/dicom MIME Sub-type Registration. http://tools.ietf.org/html/rfc3240 .

[RFC3536] IETF. May 2003. Terminology Used in Internationalization in the IETF. http://tools.ietf.org/html/rfc3536 .

[RFC3745] IETF. April 2004. MIME Type Registrations for JPEG 2000 (ISO/IEC 15444). http://tools.ietf.org/html/rfc3745 .

[RFC3986] IETF. Uniform Resource Identifiers (URI): Generic Syntax. http://tools.ietf.org/html/rfc3986 .

[RFC_4337] IETF. March 2006. MIME Type Registration for MPEG-4. http://tools.ietf.org/html/rfc4337 .

[RFC4627] IETF. July 2006. The application/json Media Type for JavaScript Object Notation (JSON). http://tools.ietf.org/html/rfc4627 .

[RFC4648] IETF. October 2006. The Base16, Base32, and Base64 Data Encodings. http://tools.ietf.org/html/rfc4648 .

[RFC5234] IETF. January 2008. Augmented BNF for Syntax Specifications: ABNF. http://tools.ietf.org/html/rfc5234 .

[RFC6365] IETF. September 2011. Terminology Used in Internationalization in the IETF. http://tools.ietf.org/html/rfc6365 .

[RFC6338] IETF. August 2011. Definition of a Uniform Resource Name (URN) Namespace for the Schema for Academia (SCHAC). http://tools.ietf.org/html/rfc6338 .

[RFC6455] IETF. December 2011. The WebSocket Protocol. http://tools.ietf.org/html/rfc6455 .

[RFC6570] IETF. March 2012. URI Template. http://tools.ietf.org/html/rfc6570 .

[RFC6838] IETF. January 2013. Media Type Specifications and Registration Procedures. http://tools.ietf.org/html/rfc6838 .

[RFC7159] IETF. March 2014. The JavaScript Object Notation (JSON) Data Interchange Format. http://tools.ietf.org/html/rfc7159 .

[RFC7230] IETF. June 2014. Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing. http://tools.ietf.org/html/rfc7230 .

[RFC7231] IETF. June 2014. Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content. http://tools.ietf.org/html/rfc7231 .

[RFC7232] IETF. June 2014. Hypertext Transfer Protocol (HTTP/1.1): Conditional Requests. http://tools.ietf.org/html/rfc7232 .

[RFC7233] IETF. June 2014. Hypertext Transfer Protocol (HTTP/1.1): Range Requests. http://tools.ietf.org/html/rfc7233 .

[RFC7234] IETF. June 2014. Hypertext Transfer Protocol (HTTP/1.1): Caching. http://tools.ietf.org/html/rfc7234 .

[RFC7235] IETF. June 2014. Hypertext Transfer Protocol (HTTP/1.1): Authentication. http://tools.ietf.org/html/rfc7235 .

[RFC7236] IETF. June 2014. Initial Hypertext Transfer Protocol (HTTP) Authentication Scheme Registrations. http://tools.ietf.org/html/rfc7236 .

[RFC7237] IETF. June 2014. Initial Hypertext Transfer Protocol (HTTP) Method Registrations. http://tools.ietf.org/html/rfc7237 .

[RFC7405] IETF. December 2014. Case-Sensitive String Support in ABNF. http://tools.ietf.org/html/rfc7405 .

[RFC7525] IETF. May 2015. TLS Recommendations. http://tools.ietf.org/html/rfc7525 .

[RFC7540] IETF. May 2015. Hypertext Transfer Protocol Version 2 (HTTP/2). http://tools.ietf.org/html/rfc7540 .

2.3 Other References

[Adobe RGB] Adobe Systems Incorporated. 1998. 2005-05. Adobe RGB (1998) Color Image Encoding. http://www.adobe.com/digitalimag/pdfs/AdobeRGB1998.pdf .

[Fielding] Architectural Styles and the Design of Network-based Software Architectures. Fielding. 2000. http://www.ics.uci.edu/~fielding/pubs/dissertation/fielding_dissertation.pdf .

[FHIR Access Denied] HL7. . FHIR Security - Access Denied Response Handling. http://hl7.org/fhir/security.html#AccessDenied .

[IHE RAD TF Vol2] Integrating the Healthcare Enterprise (IHE). Radiology Technical Framework Volume 2. http://www.ihe.net/uploadedFiles/Documents/Radiology/IHE_RAD_TF_Vol2.pdf .

[MNG] Multiple-image Network Graphics. http://www.libpng.org/pub/mng .

[ONC Privacy Security Guide] US Office of the National Coordinator for Health Information Technology (ONC). . Guide to Privacy and Security of Electronic Health Information. http://www.healthit.gov/sites/default/files/pdf/privacy/privacy-and-security-guide.pdf .

[OWASP Information Leakage] Open Web Application Security Project (OWASP). . Top 10 2007 - Information Leakage and Improper Error Handling. http://www.owasp.org/index.php/Top_10_2007-Information_Leakage_and_Improper_Error_Handling .

[WADL] W3C. 31 August 2009. . Member Submission - Web Application Description Language. http://www.w3.org/Submission/wadl/ .

[Wikipedia REST] Wikipedia. . Representational State Transfer. http://en.wikipedia.org/wiki/Representational_state_transfer .

3 Definitions

For the purposes of this Part of DICOM, the following terms and definitions apply.

3.1 Reference Model Definitions

This Part of the Standard makes use of the following terms defined in [ISO 7498-1]:

Application Entity (AE)

See [ISO 7498-1].

Real-World Activity

See [ISO 7498-1].

3.2 DICOM Introduction and Overview Definitions

This Part of the Standard makes use of the following terms defined in PS3.1:

Service-Object Pair Class (SOP Class)

Service-Object Pair Class (SOP Class).

3.3 DICOM Message Exchange

This Part of the Standard makes use of the following terms defined in PS3.7:

DICOM Message Service Element (DIMSE)

DICOM Message Service Element (DIMSE).

3.4 DICOM Information Object Definitions

This Part of the Standard makes use of the following terms defined in PS3.3:

Multi-frame Image

Multi-frame Image.

3.5 DICOM Conformance

This Part of the Standard makes use of the following terms defined in PS3.2:

Conformance Statement

Conformance Statement.

3.6 DICOM Data Structures and Encoding

This Part of the Standard makes use of the following terms defined in PS3.5:

Data Element

Data Element.

Data Element Tag

Data Element Tag.

Data Set

Data Set.

Sequence of Items

Sequence of Items.

Unique Identifier (UID)

Service-Object Pair Class (SOP Class).

3.7 DICOM Service Class Definitions

This Part of the Standard makes use of the following terms defined in PS3.4:

Service-Object Pair Instance (SOP Instance)

Service-Object Pair Instance (SOP Instance).

3.8 HyperText Transfer Protocol (HTTP/HTTPS) Definitions

This Part of the Standard makes use of the following terms defined in [RFC7230] Section 2.1 Client/Server Messaging:

HTTP

See [RFC7230].

HTTPS

See [RFC7230].

origin server

See [RFC7230].

user agent

See [RFC7230].

3.9 Web Services Definitions

Bulk Data

An object that contains an octet-stream containing one or more Value Fields (typically containing large data, such as Pixel Data) extracted from a DICOM Dataset. See Metadata.

Note

  1. The octet-stream does not include the Attribute Tag, Value Representation, or Attribute Length.

  2. For the value of a frame of a Pixel Data Attribute encoded in a compressed Transfer Syntax, it does not include the Basic Offset Table and Data Stream Fragment Item tags and lengths.

Bulk Data URI

A Uniform Resource Identifier that references Bulkdata.

DICOM Object

An instance of a data object as defined by PS3.3 that has been allocated an unique identifier in the format specified for SOP Instance UID in PS3.3 and has been chosen as an object to be saved securely for some period of time. Within the DICOM Standard, a DICOM Object is typically a Composite Service Object Pair (SOP) Instance.

DICOM Resource

One or more DICOM Objects that are referenced by a URL.

DIMSE Proxy

An origin server that responds to DICOM Web Service requests by executing DIMSE transactions to a backend server.

Event Report

A Dataset containing elements describing an event that occurred on the origin server. See Section 11.12.

Metadata

A DICOM Dataset where zero or more elements (typically containing large data, such as Pixel Data) have been replaced with Bulkdata URIs.

Note

Metadata does not include the Group 0002 File Meta Information Data Elements, which describe but are not part of a Dataset, per Section 7.1 in PS3.10.

RESTful Web Service

A web service is RESTful if it is implemented using the REST architecture and principles. See https://en.wikipedia.org/wiki/Representational_state_transfer.

Service

When used in this Part of the Standard the term Service means a set of transactions and resources to which those transactions apply.

sRGB

A standard RGB color space defined in [IEC 61966-2.1].

Status Report

A Status Report is information contained in a response payload describing warnings or errors related to a request.

Subscriber

The creator or owner of a Subscription, typically a user agent.

Target URI

The URI contained in a request message. It designates the resource that is the target of the request.

Thumbnail

A single frame image that is representative of the content of a DICOM Study, Series, Instance, or Frame. It is encoded in a Rendered Media Type. See Section 8.7.4 and Section 10.4.4.

Transaction

When used in this Part of the Standard the term Transaction means an HTTP/HTTPS request/response message pair.

UTF-8

Unicode UTF-8 character set defined in [ISO/IEC 10646].

3.10 DICOM Media Storage and File Format Definitions:

This Part of the Standard makes use of the following terms defined in PS3.10:

DICOM File

DICOM File.

DICOM File Format

DICOM File Format.

DICOM File Service

DICOM File Service.

File

File.

4 Symbols and Abbreviated Terms

ABNF

Augmented Backus-Naur Form. See [RFC5234] and [RFC7405].

DICOM

Digital Imaging and Communications in Medicine

HL7

Health Level Seven

HTML

HyperText Markup Language

HTTP

HyperText Transfer Protocol

HTTP/1.1

Version 1.1 of the HyperText Transfer Protocol

HTTP/2

Version 2 of the HyperText Transfer Protocol

HTTPS

HyperText Transfer Protocol Secure

HTTPS/1.1

Version 1.1 of the HyperText Transfer Protocol Secure

HTTPS/2

Version 2 of the HyperText Transfer Protocol Secure

IETF

Internet Engineering Task Force

IHE

Integrating the Healthcare Enterprise

JSON

JavaScript Object Notation

QIDO-RS

Query based on ID for DICOM Objects by RESTful Services

REST

Representational State Transfer, a web services architecture. See [Wikipedia REST] and [Fielding].

RESTful

A service implemented using the REST architecture.

SOP

Service Object Pair

STOW-RS

STore Over the Web by RESTful Services

UID

Unique (DICOM) Identifier

UPS-RS

Unified Procedure Step by RESTful Services

URI

Uniform Resource Identifier. See [RFC3986].

URL

Uniform Resource Locator. See [RFC3986].

WADL

Web Application Description Language

WADO-RS

Web Access to DICOM Objects by RESTful Services

WADO-URI

Web Access to DICOM Objects by URI

XML

eXtensible Markup Language

5 Conventions

This section defines conventions used throughout the rest of this Part of the Standard.

5.1 Message Syntax

The syntax of the request and response messages for transactions are defined using the ABNF Grammar used in [RFC7230], which is based on the ABNF defined in [RFC5234]. This Part of the Standard also uses the ABNF extensions in [RFC7405], which defines '%s' prefix for denoting case sensitive strings.

The syntax rules defined herein are valid for the US-ASCII character set or character sets that are supersets of US-ASCII, e.g., Unicode UTF-8.

In the ABNF used to define the syntax of messages, the following conventions are used:

  1. Syntactic variables are lowercase.

  2. Terminal rules are uppercase. For example, 'SP' stands for the US-ASCII space (0x20) literal character, and 'CRLF' stands for the ASCII carriage return (0xD) and line feed (0xA) literal characters.

  3. Header Field names are capitalized and quotation marks that denote literal strings for header field names are omitted. The Header Field names are the only capitalized names used in the grammar. See [RFC7231] Section 1.2. For example:

    Accept: media-type CRLF

    is equivalent to

    "Accept:" media-type CRLF

In this Part of the Standard, as with HTTP in general, resources are identified by URIs [RFC3986]. Each service defines the resources it manages, and the URI Templates used to define the structure of the URIs that reference them.

In HTTP RFCs, ABNF rules for obs-text and obs-fold denote "obsolete" grammar rules that appear for historical reasons. These rules are not used in DICOM Web Services syntax definitions.

See Annex A for the Combined ABNF for DICOM Web Services.

5.1.1 Common Syntactic Rules For Data Types

Table 5.1-1 defines the syntax of some common rules used in defining data values in this Part of the Standard.

Table 5.1-1. ABNF for Common Syntactic Values

Name

Rule

int
= [+ / -] 1*DIGIT
; An integer
uint
= 1*DIGIT
; An unsigned integer
non-zero-digit
= %31-39
pos-int
= non-zero-digit *DIGIT
; An integer greater than zero
decimal
=int ["." uint] [("E" / "e") int]
; a fixed- or floating-point number with at most 16 characters
string
= %s 1*QCHAR
; A case sensitive string
base64
; Use base64 defined in [RFC4648] Section 5
uid
= uid-root 1*("." uid-part)
uid-root
= "0" / "1" / "2"
uid-part
= "0" / pos-int

5.1.2 URI Templates

The URI Template [RFC6570] syntax has been extended to allow case sensitive variable names. This has been done by modifying the varchar production (see [RFC6570] Section 2.3) as follows:

varchar = %x20-21 / %x23-7E / pct-encoded

5.1.3 List Rule('#')

The ABNF has been extended with the List Rule, which is used to define comma-separated lists. It does not allow empty lists, empty list elements, or the legacy list rules defined in [RFC7230] Section 7.

1#element = element *(OWS "," OWS element)
#element = 1#element
<n>#<m>element = element <n-1>*<m-1> (OWS "," OWS element)

Where

n >= 1 and m > n

5.2 Web Service Section Structure

This Part of the Standard is organized so that new Services may be appended as new numbered sections at the end of the document.

5.3 Request and Response Header Field Tables

Request header field requirements are described using tables of the following form:

Table 5.2-1. Request Header Fields

Name

Value

Usage

Description

User Agent

Origin Server

...

...


The Name column contains the name of the HTTP header field as defined in [RFC7230, RFC7231].

The Value column defines either the value type or the specific value contained in the header field.

The Usage User Agent column defines requirements for the user agent to supply the header field in the request.

The Usage Origin Server column defines requirements for the origin server to support the header field.

The content of the Usage columns is either:

M

Mandatory

C

Conditional

O

Optional

The Description column of conditional request header fields specifies the condition for the presence of the header field.

  • "Shall be present if <condition>" means that if the <condition> is true, then the header field shall be present; otherwise, it shall not be present.

  • "May be present otherwise" is added to the description if the header field may be present, even if the condition is not true.

Response header field requirements are described using tables of the following form:

Table 5.2-2. Response Header Fields

Name

Value

Origin Server Usage

Description

...

...


For response header fields the Usage column defines requirements for the origin server to supply the header field.

6 Conformance

An implementation claiming conformance to this Part of the Standard shall function in accordance with all its mandatory sections.

DICOM Web Services are used to transmit Composite SOP Instances. All Composite SOP Instances transmitted shall conform to the requirements specified in other Parts of the Standard.

An implementation may conform to the DICOM Web Services by supporting the role of origin server or user agent, or both, for any of the Services defined in this Part of the Standard. The structure of Conformance Statements is specified in PS3.2.

An implementation shall describe in its Conformance Statement the Real-World Activity associated with its use of DICOM Web Services, including any proxy functionality between a Web Service and the equivalent DIMSE Service.

An implementation shall describe in its Conformance Statement the security mechanisms utilized by the implementation.See Section 8.11.

7 Overview of DICOM Web Services (Informative)

Figure 5-1 of PS3.1 presents the general communication model of the DICOM Standard, which spans both network (on-line) and storage media interchange (off-line) communications. Application Entities may utilize any of the following transport mechanisms:

  • the DICOM Message Service and Upper Layer Service, which provides independence from specific physical networking communication support and protocols such as TCP/IP,

  • the DICOM Web Service API and HTTP Service, which allows use of common hypertext and associated protocols for transport of DICOM services,

  • the Basic DICOM File Service, which provides access to Storage Media independently from specific physical media storage formats and file structures, or

  • DICOM Real-Time Communication, which provides real-time transport of DICOM metadata based on SMPTE and RTP.

PS3.18 describes the DICOM Web Services, which use the HTTP and HTTPS protocols as their transport medium, as depicted in Figure 7-1.

DICOM Communication Model for Web Services

Figure 7-1. DICOM Communication Model for Web Services


7.1 DICOM Web Service Types

This Part of the Standard defines DICOM Web Services. Each service allows a user agent to interact with an origin server to manage a set of DICOM Resources. Each DICOM Web Service operates on a set of resources and defines a set of Transactions that operate on those resources. All Transactions are defined in terms of HTTP request/response message pairs.

When used in this Part of the Standard, the term HTTP refers to the family of HTTP protocols including: HTTP/1.1, HTTPS/1.1, HTTP/2, and HTTPS/2, as defined by the relevant IETF RFCs, but does not include HTTP/1.0 or HTTPS/1.0. The HTTP standards are normative for all aspects of HTTP message format and transmission.

There are two general types of DICOM Web Services: URI and RESTful. This distinction is based on the type of web service protocol used to specify resources and transactions.

7.1.1 URI Web Service

The URI Web Service retrieves representations of its resources, those resources being Composite SOP Instances (Instance). The URI service defines two transactions that retrieve Instances in different media types. All URI transactions use the query component of the URI in the request message to specify the transaction.

The functionality of the URI Web Service Transactions is similar to, but more limited than, the Retrieve Transaction of the Studies Web Service.

7.1.2 RESTful Web Services and Resources

Each RESTful Web Service defines the set of resources, and the transactions that can be applied to those resources.

The defined RESTful Web Services are:

Studies Web Service

Enables a user agent to manage Studies stored on an origin server.

Worklist Web Service

Enables a user agent to manage the Worklist containing Workitems stored on an origin server.

Non-Patient Instance Web Service

Enables a user agent to manage Non-Patient Instances, e.g., Color Palettes, stored on an origin server.

7.2 Resources, Representations, and Target URIs

In RESTful Web Services, a resource is an abstract object with a type, associated data, relationships to other resources,and a set of methods that operate on it. Resources are grouped into collections. Collections are themselves resources as well. Each collection is unordered and contains only one type of resource. Collections can exist globally, at the top level of an API, but can also be contained inside a resource. In the latter case, we refer to these collections as sub-collections. Sub-collections usually express some kind of "contained in" relationship.

7.2.1 DICOM Restful Resources

The DICOM Resources defined in this Part of the Standard are typically either a DICOM Web Services or DICOM Information Objects. Examples include Studies, Series, Instances, Worklists, and Workitems.

DICOM Resources are grouped into collections and hierarchies. The following resources are examples of collections:

Resource Path

Contents

/studies

A collection of Studies.

/series

A collection of Series.

/instance

A collection of Instances.

/frames

A sequence of Frames.

The following resources are examples of hierarchies:

/studies/{study}/series

Contains a collection of Series.

/studies/{study}/series/{series}/instances

Contains a collection of Instances.

/studies/{study}/series/{series}/instances/{instance}/frames

Contains a sequence of frames.

A DICOM Web Service origin server manages a collection of resources. This might not be done directly; for example, an origin server could act as a proxy, converting RESTful requests into DIMSE requests, and DIMSE responses into RESTful responses.

Resources are typically created and/or accessed by user agents.

7.2.2 Representations

A resource is an abstract concept that is made concrete by a representation, which is a data object encoded in an octet-stream. For example, a DICOM Study (abstract) might be represented by a sequence of octets encoded in a selected Media Type. See Section 8.7.3.

A media type describes the format or encoding of a representation. Examples of media types are application/dicom, application/dicom+json, image/jpeg, and text/html.

7.2.3 Target URIs

Resources are identified by URIs. Each service defines the resources that it manages and the format of the URIs used to reference those resources. The format of URIs is defined using URI Templates. See [RFC6570].

8 Common Aspects of DICOM Web Services

This section describes details and requirements that are common to all Web Services defined in this Part of the Standard.

A user agent or origin server that implements a Service in this Part of the Standard shall conform to Chapter 8 unless stated otherwise in the specification of that Service and its Transactions.

8.1 Transactions

Each transaction is composed of a request message and a response message, sometimes referred to as a request/response pair. When used in this Part of the Standard the term "request" means "request message", and "response" means "response message", unless clearly stated otherwise. Figure 8.1-1 is an interaction diagram that shows the message flow of a transaction. When it receives the request, the origin server processes it and returns a response.

The request includes a method, the URI of the Target Resource, and header fields. It might also include Query Parameters and a payload.

The response includes a status code, a reason phrase, header fields, and might also include a payload.

Interaction Diagram for Transactions

Figure 8.1-1. Interaction Diagram for Transactions


8.1.1 Request Message Syntax

This Part of the Standard uses the ABNF defined in Section 5.1 to define the syntax of transactions.

All Web Services API request messages have the following syntax:

method SP target-uri SP version CRLF
*(header-field CRLF)
CRLF
[payload]

Where

method = "CONNECT" / "DELETE" / "GET" / "HEAD" / "OPTIONS" / "POST" / "PUT"

Each transaction defines the method it uses.

SP= %x20

The US-ASCII Space character

target-uri = "/" {/resource} {?parameters*}

Each transaction defines a URI Template for the Target Resource. The template specifies the format of URIs that reference the Target Resource of a request. See Section 8.1.1.2.

version = ("HTTP" / "HTTPS") "/" ("1.1" / "2")

The version of the HTTP protocol; one of "HTTP/1.1", "HTTP/2", "HTTPS/1.1", or "HTTPS/2".

CRLF = %x0D.0A

A US-ASCII carriage return (%x0D) followed by a linefeed (%x0A).

*(header-field CRLF)

Zero or more header fields each followed by a CRLF delimiter.

[payload] = *OCTET / multipart-payload

An optional payload containing zero or more 8-bit OCTETs.

Note

The method, SP, version, CRLF, Accept, header-field, and payload are all HTTP productions from [RFC7230], and [RFC7231]. The definitions are reproduced here for convenience.

8.1.1.1 Method

The request method is one of the HTTP methods, such as CONNECT, DELETE, GET, HEAD, OPTIONS, POST, PUT. See [RFC7230] Section 4.

8.1.1.2 Target Resource

The Target Resource of a request is specified by the Target URI contained in the request message. See Section 8.2.

8.1.1.3 Query Parameters

Query parameters are contained in the query component (see [RFC3986]) of the URI. The user agent may use Query Parameters to supply parameters to the request. See Section 8.3.

8.1.1.4 Request Header Fields

Request header fields are used to specify metadata for the request. Most requests have one or more Content Negotiation (see Section 8.4.1) header fields. If a request has a payload, the request will have the corresponding Content Representation (see Section 8.4.2) and Payload (see Section 8.4.3) header fields.

8.1.1.5 Request Payload

The payload of the request is an octet-stream containing the content of the message. See Section 8.6. The presence of a payload in a request is signaled by a Content-Length or Content-Encoding header field.

8.1.2 Response Message Syntax

The syntax of a response message is:

versionSP status-codeSP reason-phrase CRLF
*(header-field CRLF)
CRLF
[payload]

Where

status-code = 3DIGIT

A three-digit code specifying the status of the response.

reason-phrase = *(HTAB / SP / VCHAR)

A human readable phrase that corresponds to the status. An implementation may define its own reason phrases. The reason-phrase syntax is slightly modified from that in [RFC7230]; this Part of the Standard does not allow obsolete text (obs-text) in the reason-phrase.

Note

The status-code production is from [RFC7230].

The origin server shall always return a response message.

8.1.2.1 Status Codes

The response message shall always include a valid 3-digit status code. Section 8.5 defines the status codes used by transactions. IANA maintains a registry of HTTP Status codes. See [IANA HTTP Status Code Registry].

8.1.2.2 Response Header Fields

Response header fields are used to specify metadata for the response. The response will have the Content Representation (see Section 8.4.2) and Payload (see Section 8.4.3) header fields that correspond to the contents of the payload.

8.1.2.3 Response Payload

The payload of the response is an octet-stream containing one or more representations. See Section 8.6.

A transaction typically defines two types of payloads for a response message: a success payload, and a failure payload.

A failure response payload should contain a Status Report describing any failures, warnings, or other useful information.

8.2 Target Resources

Transaction specifications define what resource types are valid Target Resources for the transaction and define the format of the URI for the Target Resource (and Query Parameters) using URI Templates. The URI of a Target Resource is referred to as the Target URI. Transaction specifications also define what resource types are valid resources for the response.

A Target URI is composed of three components: The Base URI, the Target Resource Path, and Query Parameters (which are often optional).

No whitespace is permitted in URIs. Whitespace around line breaks and the line breaks themselves should be stripped before parsing the URI. See [RFC3986] Appendix C.

The most general template for a Target URI is:

target-uri = "/" {/resource} {?optional*}

or if any of the Query Parameters are required

target-uri = "/" {/resource} ?{required*}{&optional*}

Where

"/"

The slash character ('/') is used to designate the Base URI.

{/resource}

A URI template for the Target Resource Path, a relative path component that references the Target Resource. The '/' in the template indicates that reserved characters, such as '/', can be used in the template expansion. See [RFC6570].

"/{/resource}" indicates the absolute URI to the Target Resource on the origin server.

{required*}

A URI Template for one or more required query parameters. See Section 8.1.1 for an example.

{&optional*)

A URI Template for zero or more optional query parameters. See Section 8.3.1 for an example.

The Base URI of a Service is an absolute URI that specifies the location of the origin server implementing the Service. Each Target URI defined by this Part of the Standard starts with a "/", which is a shorthand that designates the Base URI of the Service. The Base URI may support more than one Service.

The Service Root Path is the Base URI without the Scheme and Authority components.

The Target Resource Path is a relative URI that specifies the path to the resource from the Base URI of the Service. It is specified by a URI Template that uses Path Expansion {/var} as defined in [RFC6570].

For example, given the URI:

http://dicom.nema.org/service/studies/2.25.123456789/series/2.25.987654321

The Base URI is:

http://dicom.nema.org/service

The Service Root Path is:

/service

The Target Resource Path is:

/studies/2.25.123456789/series/2.25.987654321

The URI Template for this resource is:

/studies/{study}/series/{series}

Where

{study}

is the Study Instance UID of a Study

{series}

is the Series Instance UID of a Series

8.3 Query Parameters

Query Parameters are specified in the query component of the URI (see [RFC3986] Section 3.4.

The query component of a request URI may only be used to specify one or more Query Parameters. These parameters are referred to as Query Parameters to distinguish them from header field parameters or other types of parameters that may be contained in the payload.

The Query Parameters are specified using a URI Template that uses Form {?var} and Query Continuation Style {&var} Query Expansion as defined in [RFC6570].

If a Target URI includes a "query component" (see [RFC3986] Section 3.4), it shall contain Query Parameters that conform to the syntax defined here.

The Services and Transactions defined elsewhere in this Part of the Standard may further refine the qp-name and qp-value rules defined below.

[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 documented 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 may return a response containing appropriate warning and/or error messages.

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

8.3.1 Query Parameter Syntax

Query parameters have the following syntax:

query-parameters = "?" parameter [*("&" parameter) ]

Each parameter after the first, is separated from the following parameter by the "&" character. Each parameter has the following syntax:

parameter = qp-name 
          / qp-name "=" 1#qp-value
          / qp-name "=" 1#attribute
          / attribute 
          / attribute "=" 1#qp-value

The qp-name is case sensitive, and starts with an alphabetic or underscore character, followed by zero or more alphanumeric or underscore "_" characters:

qp-name = %s 1*(ALPHA / "_") *(ALPHA / DIGIT / "_")

A qp-name by itself (with no values) is a legal Query Parameter. A parameter qp-name may also be followed by a comma-separated list of one or more qp-values, or one or more Attributes.

The qp-values are case-sensitive. A qp-value is composed of qp-chars, where qp-char is the set of legal query component characters as defined by [RFC3986], minus the equal ("="), ampersand ("&"), and comma (",") characters.

qp-value   = %s DQ 1*qp-char DQ
qp-char    = unreserved / pct-encoded / qp-special
qp-special = "!" / "$" / "'" / "(" / ")" / "*" / "+" / ";" /":" / "@" / "/" / "?"

The only visible US-ASCII characters disallowed in the query component by [RFC3986] are "#", "[", "]". This Part of the Standard further disallows "&", "=", and ",". However, the characters ("#", "[", "]" "&", "=", and ",".) may be included in qp-values if they are percent encoded.

Each Attribute is either a simple-attribute or a sequence-attribute:

attribute = simple-attribute / sequence-attribute

A simple-attribute is a single Data Element Tag or Keyword (see Table 6-1 “Registry of DICOM Data Elements” in PS3.6) that does not have a VR of SQ:

simple-attribute = keyword / tag
keyword          = %s DQ 1*ALPHA *(ALPHA / DIGIT) DQ
tag              = 8HEXDIG

DICOM keywords are case sensitive; they shall start with an alphabetic character followed by zero or more alphanumeric characters. See PS3.6.

A sequence-attribute is two or more attributes separated by the dot character ("."), all but the last attribute shall have a VR of SQ, and the last attribute shall not have a VR of SQ.

sequence-attribute = (keyword / tag) *("." attribute)

The following are examples of valid values for attribute:

0020000D
StudyInstanceUID
00101002.00100020
OtherPatientIDsSequence.PatientID
00101002.00100024.00400032
OtherPatientIDsSequence.IssuerOfPatientIDQualifiersSequence.UniversalEntityID

Some Query Parameters have a qp-name, which is an attribute, and a value that is a comma-separated list of one or more qp-values. The qp-values of an attribute parameter shall satisfy its Value Representation and Value Multiplicity, as defined in PS3.5 and PS3.6, of the corresponding attribute.

Unlike the Value Representations defined in PS3.5, Query Parameters:

  • shall not be padded to an even length

  • shall not contain any NULL (%x00) characters

  • shall encode UIDs as specified in PS3.5, except that they shall not be padded to an even length

8.3.1.1 Query Parameter Syntax

The syntax and semantics of valid qp-names, qp-values and attributes are specified by the defining Service or Transaction; however, they shall conform to the rules in this Section.

Table 8.3.1-1 contains the collected syntax of Query Parameters. The Services and Transactions defined elsewhere in this Part of the Standard may further refine the qp-name, attribute, and qp-value rules.

All qp-names are case sensitive.

Table 8.3.1-1. ABNF for Query Parameter

Name

Rule

query-parameters
= "?" parameter *("&" parameter)
parameter
= qp-name; a name only
/ qp-name "=" 1#qp-value ; a name with one or more values
/ qp-name "=" 1#attribute; a name with one or more attributes
/ attribute; an attribute only
/ attribute "=" 1#qp-value ; an attribute with one or more values
qp-name
= %s (ALPHA / "_") *(ALPHA / DIGIT / "_")
qp-value
=int / uint / pos-int / decimal / float /string / base64 / uid
/ %s 1*qp-char/ %s DQ 1*qp-special DQ; See Section 5.1.1
qp-char
= unreserved / pct-encoded
qp-special
= "!" / "$" / "'" / "(" / ") " / "*" / "+" / ";"/":" / "@" / "/" / "?"
simple-attribute
= keyword / tag
sequence-attribute
= keyword *( "." attribute) / tag *( "." attribute )
keyword
= %suppercase *( ALPHA / DIGIT )
uppercase
=%x41-5A
tag
= 8HEXDIG

Note

The syntax of qp-values is defined in Section 5.1.1.

The qp-char (Query Parameter characters) rule defined above is the query rule of [RFC3986], which defines the legal characters for the query component, minus the equal sign ("="), comma (","), and ampersand ("&"). So, the qp-char rule is the VCHAR rule minus "#", "[", "]", "=", "&", and ",".

All DICOM keywords are case sensitive. See PS3.6.

8.3.2 Query Parameter Usage

An implementation's support for Query Parameters is either Mandatory or Optional. Each Query Parameter section contains a table specifying Query Parameter keys, values, user agent and origin server usage requirements. Table 8.3.2-1 specifies the usage symbols, types, and definitions.

Table 8.3.2-1. Query Parameter Usage

Symbol

Type

M

Mandatory

C

Conditional

O

Optional


Table 8.3.2-2 shows an example Query Parameter table.

Table 8.3.2-2. Example Query Parameter Table

Name

Values

Usage

Section

User Agent

Origin Server

requestType

"WADO"

M

M

Section 9.1.2.1.1

studyUID

uid

M

M

Section 9.1.2.1.3

seriesUID

uid

M

M

Section 9.1.2.1.3

objectUID

uid

M

M

Section 9.1.2.1.4


The usage columns specify the Query Parameters that the user agent must supply, and the origin server must support.

8.3.3 Content Negotiation Query Parameters

The parameters defined in this section are primarily designed for use in hyperlinks, i.e., URIs embedded in documents, where the Content Negotiation header fields (see Section 8.3.3) are not accessible.

8.3.3.1 Accept Query Parameter

The Accept Query Parameter has the following syntax:

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

The Accept Query Parameter has the same syntax as the Accept header field (see Section 8.4.3), except that it shall not have wildcards (<type>/* or */*). See Section 8.7.

Note

  1. The normal name of this parameter is "accept"; however, the URI Service uses an accept-name of "contentType". See Section 9.1.2.2.1.

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

The parameter value is a comma-separated list of one or more media-types.

The Accept Query Parameter should not be used when the user agent can specify the values by using 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 or more of the following values: image/jpeg, image/*, or */*.

If none of the Acceptable Media Types (see Section 8.7.5) are supported by the origin server, the origin server response shall be in the default media type for the Resource Category of the Target Resource. If there is no default media type defined for the Target Resource, the origin server response shall be 406 (Not Acceptable) and may include a payload containing an appropriate Status Report.

If a DICOM Media Type is present, non-DICOM Media Types shall not be present. If both DICOM and non-DICOM Media Types are present, the response shall be 400 (Bad Request), and may include a payload containing an appropriate Status Report.

8.3.3.2 Character Set Query Parameter

The Character Set Query Parameter has the following syntax:

character-set = "charset" "=" 1#(charset [weight])

The Character Set Query Parameter value is a comma-separated list of one or more character set identifiers. It is like the Accept-Charset header field, except that it shall not have wildcards. See Section 8.8.

Note

Character set identifiers present in the character set Query Parameter typically have a corresponding character set identifier in the Accept-Charset header field, either explicitly or implicitly through wildcards.

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

8.3.4 Search Query Parameters

Table 8.3.4-1 contains the syntax for the names and values of search parameters, along with a reference to the section where their meaning is defined. Search transactions shall support these parameters. The ABNF for the various search parameters is:

Table 8.3.4-1. Query Parameter Syntax

Term

Value

Usage

Description

User Agent

Origin Server

search
= match / fuzzymatching / includefield
/ limit / offset
match
; See attribute matching rules below

O

M

Section 8.3.4.1

fuzzymatching
= "fuzzymatching" "=" true / false

O

M

Section 8.3.4.2

includefield
= "includefield" "=" 1#attribute / "all"

O

M

Section 8.3.4.3

limit
= "limit" "=" uint ; Maximum number of results

O

M

Section 8.3.4.4

offset
= "offset" "=" uint ; Number of skipped results

O

M

Section 8.3.4.4


The following sections describe these parameters in detail.

8.3.4.1 Attribute Matching

The syntax of the match Query Parameter shall be:

match          = normal-match / uid-list-match
normal-match   = 1*("&" attribute "=" value)
uid-list-match = 1*("&" attribute "=" 1#value)
attribute      = (attribute-id) *("." attribute-id)
attribute-id   = tag *("." tag) / keyword *("." keyword)
tag            = 8HEXDIG
keyword= ;A keyword from Table 6-1 “Registry of DICOM Data Elements” in PS3.6.

One or more DICOM Attribute/Values pairs specify the matching criteria for the search.

Each search transaction defines which Attributes are required or permitted.

Note

DICOM Attributes should not be confused with XML attributes. The Tags and Keywords for DICOM Attributes are defined in Table 6-1 “Registry of DICOM Data Elements” in PS3.6.

DICOM Attribute/Values pairs shall satisfy the following requirements:

  1. Each attribute-id shall be a Data Element Tag or Keyword.

  2. Each attribute in the Query Parameter shall be not be repeated.

  3. Each attribute in the Query Parameter shall have a single value, unless the associated DICOM Attribute allows UID List matching (see Section C.2.2.2.2 in PS3.4 ), in which case the value is a comma-separated list of UIDs.

  4. If a tag represents a Private Data Element the query shall also include a corresponding Private Creator Element (see Section 7.8.1 in PS3.5 ).

  5. The acceptable values are determined by the types of matching allowed by C-FIND for its associated attribute. See Section C.2.2.2 in PS3.4 . All characters in values that are not qp-chars shall be percent-encoded. All non-ASCII characters shall be percent encoded. See [RFC3986] for details.

The following US-ASCII characters"#", "[", "]", "&", "=", and "," shall be percent encoded in any Query Parameter.

The match Query Parameter corresponds to DIMSE Matching Keys. See Section K.2.2.1.1 in PS3.4 .

8.3.4.1.1 Matching Rules

The matching semantics for each attribute are determined by the types of matching allowed by C-FIND. See Section C.2.2.2 “Attribute Matching” in PS3.4.

Matching results shall be generated according to the Hierarchical Search Method described in Section C.4.1.3.1.1 “Hierarchical Search Method” in PS3.4.

Combined date-time matching shall be performed as specified in Section C.2.2.2.5 “Range Matching” in PS3.4.

Note

If an origin server is acting as a proxy for a C-FIND SCP that does not support combined date-time matching, it shall perform a C-FIND request using only the date and filter any results that are outside the time range before returning a response.

If the Timezone Offset From UTC (0008,0201) Attribute is specified in the request, dates and times in the request are to be interpreted in the specified time zone. See Section C.4.1.1 in PS3.4 .

8.3.4.2 Fuzzy Matching of Person Names

A single parameter specifies whether Fuzzy Matching of Person Names is to be performed.

This parameter is optional for the user agent.

This parameter is optional for the origin server.

If this parameter is not present its value is "false".

fuzzymatching = "fuzzymatching" "=" ("true" / "false")

If the value is "false", then the search shall be performed without Fuzzy Matching.

If the value is "true" and the origin server supports Fuzzy Matching, then the search shall be performed with Fuzzy Matching of Person Name Attributes as specified in Section C.2.2.2.1.1 in PS3.4 and shall be documented in the Conformance Statement and, if the service supports it, the Retrieve Capabilities response.

If the value is "true" and the origin server does not support Fuzzy Matching, then:

  • The search shall be performed without Fuzzy Matching.

  • The response shall include the following HTTP Warning header (see [RFC7234] Section 5.5) :

    Warning: 299 <service>: The fuzzymatching parameter is not supported. Only literal matching has been performed.

    where <service> is the base URI for the origin server. This may be a combination of scheme, authority, and path.

  • The response may include a payload containing an appropriate Status Report.

8.3.4.3 Attributes Included in the Response

A parameter specifies the Attributes that should be included in the response. The value is either a comma-separated list of attributes, or the single keyword "all", which means that all available attributes of the object should be included in the response.

includefield = *("includefield" "=" (1#attribute / "all") )

The request may contain one or more include parameters; however, if a parameter with the value of "all" is present, then other includefield parameters shall not be present. If an attribute is a value of an includefield parameter, it is equivalent to C-FIND Universal matching for that attribute. See Section C.2.2.2.3 in PS3.4 .

If an include parameter represents a Private Data Element a corresponding Private Creator Element shall be specified as an additional match parameter (see Section 7.8.1 in PS3.5 ).

The includefield Query Parameter corresponds to DIMSE Return Keys. See Section K.2.2.1.2 in PS3.4 .

8.3.4.4 Response Pagination

The following two parameters can be used to paginate a search response that might contain more matches than can readily be handled.

offset = "offset" "=" uint

A single parameter specifies the number of matches the origin server shall skip before the first returned match. The "offset" parameter value is an unsigned integer (uint). If this Query Parameter is not present, its value defaults to 0.

limit = "limit" "=" uint

A single parameter specifies the maximum number of matches the origin server shall return in a single response. The "limit" parameter value is an unsigned integer. If this parameter is not present, its value is determined by the origin server.

8.3.4.4.1 Paging Behavior

The search requests shall be idempotent, that is, two separate search requests with the same Target Resource, Query Parameters, and header fields shall return the same ordered list of matches, if the set of matches on the origin server has not changed.

Given the following definitions:

offset

the value of the "offset" query parameter.

limit

the value of the "limit" query parameter.

maxResults

the maximum number of results the origin server allows in a single response.

matches

the number of matches resulting from the search.

results

the number of results returned in the response. It is equal to the minimum of:

  • The maximum of zero and the value of matches - offset

  • The value of maxResults

  • The value of limit

remaining

the number of matches that were not yet returned.

The results returned in the response are determined as follows:

  • If (results <= 0) then there are no matches, and a 204 (No Content) response shall be returned with an empty payload.

  • Otherwise, a 200 (OK) response shall be returned with a payload containing the results.

  • If (remaining > 0) the response shall include a Warning header field (see [RFC7234] Section 5.5) containing the following:

    Warning: 299 <service>: There are <remaining> additional results that can be requested

The response may include a payload containing an appropriate Status Report.

If the set of matching results has changed due to changes in the origin server contents, then the ordered list of results may be different for subsequent transactions with identical requests, and the results of using the "offset" and "limit" parameters may be inconsistent.

8.3.5 Rendering Query Parameters

This section defines the Query Parameter syntax and behavior for Retrieve requests for Rendered Media Types.

All Retrieve transactions for Rendered Media Types shall support these parameters.

8.3.5.1 Query Parameters For Rendered Resources

The Query Parameters defined in this section specify various rendering transformations to be applied to the DICOM images, video, and text contained in the parent DICOM Resource.

The following rules pertain to all parameters defined in this section:

  1. All parameters are optional for the user agent.

  2. Not all parameters are required to be supported by the origin server.

  3. These parameters only apply to resources that are images and video.

The set of transformations specified by the parameters in this section shall be applied to the images as if the parameters were a Presentation State, that is, in the order specified by the applicable image rendering pipeline specified in PS3.4.

Table 8.3.5-1 shows the Query Parameters that may be used when requesting a Rendered Representation.

Table 8.3.5-1. Retrieve Rendered Query Parameters

Key

Values

Target Resource Category

Section

accept
Rendered Media Type

All Categories

8.3.3.1

annotation
"patient" and/or "technique"

Image (single or multi-frame) or Video

8.3.5.1.1

charset
character set token

All Categories

8.3.3.2

quality
uint

Image (single or multi-frame) or Video

8.3.5.1.2

viewport
vw, vh, [ sx, sy, sw, sh ]

Non-Presentation States

8.3.5.1.3

viewport
vw, vh,

Presentation States

8.3.5.1.3

window
center, width, shape

Non-Presentation States

8.3.5.1.4

iccprofile
"no", "yes", "srgb", "adobergb" or "rommrgb"

Image (single or multi-frame) or Video

8.3.5.1.5


8.3.5.1.1 Image Annotation

This parameter specifies that the rendered images or video will have annotations. Its name is "annotation" and its value is a comma-separated list of one or more keywords. It has the following syntax:

annotation = %s"annotation=" 1#( %s"patient" / %s"technique" )

Where

"patient"

Indicates that the rendered images shall be annotated with patient information (e.g., patient name, birth date, etc.).

"technique"

Indicates that the rendered images shall be annotated with information about the procedure that was performed (e.g., image number, study date, image position, etc.).

When this parameter is not present, no annotations shall be applied.

The image rendering pipelines specified in PS3.4 require that annotations be applied after all other parameters have been applied and the image or video has been rendered. The exact nature and presentation of the annotations is determined by the origin server and is "burned-in" to the rendered content.

The origin server may support additional keywords, which shall be documented in the Conformance Statement and, if the service supports it, the Retrieve Capabilities response.

If any of the parameter values are not keywords, or there are no parameter values, the origin server shall return a 400 (Bad Request) response and may include a payload containing an appropriate error message.

The origin server shall ignore any unsupported parameter values. If unsupported values are present, the origin server shall include the following header field:

Warning 299 <service>: The following annotation values are not supported: <values>

and may include a payload containing an appropriate warning message.

Note

  1. The exact nature and presentation of the annotation is determined by the origin server. The annotation is burned into the rendered image pixels.

  2. A user agent wanting more control over annotations may retrieve an image, omitting the "annotation" parameter, and separately retrieve the metadata, and create customized annotations on the image.

  3. A user agent wanting more control over annotations can retrieve an image, omitting the "annotation" parameter, separately retrieve the metadata, and create customized annotations on the image.

  4. The Target Resource could already contain "burned-in" text that is beyond the control of this parameter.

8.3.5.1.2 Image Quality

The "quality" parameter specifies the requested quality of the rendered images or video. It has the following syntax:

quality = %s"quality=" uint

Where

uint

is an unsigned integer between 1 and 100 inclusive, with 100 being the best quality.

If the value of this parameter is missing or is not an integer between 1 and 100 inclusive, the response shall be a 400 (Bad Request) and may include a payload containing an appropriate error message.

The "quality" parameter is only supported for media types that allow lossy compression.

The meaning of this parameter is determined by the origin server and shall be documented in the Conformance Statement and, if the Service supports it, Retrieve Capabilities response.

Note

  1. Decompression and re-compression may degrade the image quality if the original image was already irreversibly compressed. If the image has been already lossy compressed using the same format as required (e.g., jpeg), it may be sent as it is without decompressing and re-compressing it.

  2. The origin server could choose to disregard the quality parameter if the resultant image quality would be too low.

8.3.5.1.3 Viewport Scaling

The "viewport" parameter specifies a rectangular region of the source image(s) or video to be cropped, and a rectangular region corresponding to the size of the user agent's viewport to which the cropped image or video should be scaled.

The syntax of this parameter for a Presentation State Instance or a Thumbnail is:

%s"viewport=" vw "," vh

Otherwise it is:

%s"viewport=" vw "," vh ["," [sx] "," [sy] "," [sw] "," [sh] ]

Where

vw and vh

are positive integers specifying the width and height, in pixels, of the rendered image or video. Both values are required.

sx and sy

are decimal numbers whose absolute values specify, in pixels, the top-left corner of the region of the source image(s) to be rendered. If either sx or sy is not specified, it defaults to 0. A value of 0,0 specifies the top-left corner of the source image(s).

sw and sh

are decimal numbers whose absolute values specify, in pixels, the width and height of the region of the source image(s) to be rendered. If sw is not specified, it defaults to the right edge of the source image. If sh is not specified, it defaults to the bottom edge of the source image. If sw is a negative value, the image is flipped horizontally. If sh is a negative value, the image is flipped vertically.

The origin server shall crop the source images or video to the region specified by sx, sy, sw, and sh. It shall then scale the source content, maintaining the aspect ratio of the cropped region, until either the rendered content width or height is the same as the viewport width or height, whichever avoids truncation. In other words, viewport scaling makes the image(s) as large as possible, within the viewport, without overflowing the viewport area and without distorting the image.

If any of the optional parameter values are not present, the default value shall be used. Individual values may be elided, but the commas between the values shall be present. For example:

viewport=512,512,,,512,512

The missing sx and sy parameter values default to 0.

If trailing values are elided, then the trailing commas shall be omitted. For example:

viewport=1024,1024

The missing sx, sy, sw, sh will have their default values, i.e., the image(s) shall not be cropped, i.e., the full image is rendered.

If the viewport parameter is not present, the rendered image(s) or video shall not be scaled, i.e., the rendered image(s) shall contain the same sized pixel matrix as the source DICOM image.

If any of the following are true:

  • This parameter specifies viewport dimensions that are either ill-formed or not supported

  • The Target Resource is a Presentation State or Thumbnail and anything other than vw and vh are specified

then the response shall be 400 (Bad Request) and may include a payload containing an appropriate Status Report.

Note

The default values for sx and sy differ from the defaults in the Specified Displayed Area in Presentation States, which uses integer values with the top left corner being (1\1). See Section C.10.4 in PS3.3 .

8.3.5.1.4 Windowing

The "window" parameter controls the windowing of the images or video as defined in Section C.8.11.3.1.5 in PS3.3 . It has the following syntax:

%s"window=" center "," width "," function

Where

center

is a decimal number containing the window-center value

width

is a decimal numbercontaining the window-width value

function

is one of the following keywords: "linear", "linear-exact", or "sigmoid".

Note

These correspond to the differently capitalized and punctuated values of VOI LUT Function (0028,1056). See Section C.11.2.1.2 in PS3.3 .

All three parameters shall be present with valid values.

If any of the parameter values are missing or ill-formed, the origin server shall return a 400 (Bad Request) response and may include a payload containing an appropriate error message.

If the Target Resource is a Presentation State, this parameter shall not be used. If this parameter is present when the Target Resource is a Presentation state, the origin server shall return a 400 (Bad Request).

8.3.5.1.5 ICC Profile

The "iccprofile" parameter specifies the color characteristics of, and inclusion of an ICC Profile in, the rendered images. It has the following syntax:

%s"iccprofile=" 1#( %s"no" / %s"yes" / %s"srgb" / %s"adobergb" / %s"rommrgb" )

Where

"no"

indicates that no ICC profile shall be present in the rendered image in the response.

"yes"

indicates that an ICC profile shall be present in the rendered image in the response, describing its color characteristics, if the Media Type supports embedded ICC Profiles.

"srgb"

indicates that an sRGB ICC profile shall be present in the image, if the Media Type supports embedded ICC Profiles, and that the pixels of the rendered image in the response shall be transformed from their original color space and be encoded in the sRGB color space [IEC 61966-2.1].

"adobergb"

indicates that an Adobe RGB ICC profile shall be present in the image, if the Media Type supports embedded ICC Profiles, and that the pixels of the rendered image in the response shall be transformed from their original color space and be encoded in the Adobe RGB color space [Adobe RGB].

"rommrgb"

indicates that a ROMM RGB ICC profile shall be present in the image, if the Media Type supports embedded ICC Profiles, and that the pixels of the rendered image in the response shall be transformed from their original color space and encoded in the ROMM RGB color space [ISO 22028-2].

When this parameter is not present:

  • an ICC profile may or may not be present in the image in the response;

  • the color characteristics of the image in the response may or may not be consistent with any DICOM ICC Profile (0028,2000) Attribute in the metadata.

The ICC Profile in the image in the response shall be:

  • the ICC profile of the color space specified explicitly by the parameter,

  • otherwise, the ICC profile encoded in the source DICOM ICC Profile (0028,2000) Attribute, if any, appropriate to the selected frame,

  • otherwise, the ICC profile, if any, embedded in the stored compressed representation of the selected frame,

  • otherwise, at the discretion of the origin server, the ICC profile of a well-known color space listed in Section C.11.15.1.2 “Color Space” in PS3.3 that is appropriate to the type and source of the image.

If the Media Type does not support embedded ICC Profiles:

  • a 400 Bad Request error shall be returned if the parameter value is other than "no"

Note

  1. This parameter allows ICC profile information to be present in the image in the response so that the user agent can make use of it for local color management (e.g., an ICC profile capable browser can apply the profile when displaying the rendered image in the response).

  2. This parameter provides a limited mechanism for requesting that the origin server perform some color management. It provides the names of well-known color spaces for the rendered image in the response. It does not provide a mechanism to supply an arbitrary ICC profile, such as the calibration profile of a display, so it does not absolve the user agent from the need to handle its own color calibration and color management.

  3. ICC profiles can theoretically be large relative to the compressed pixel data of a single frame, so the user agent may specify a parameter value of "no", retrieve the DICOM ICC Profile (0028,2000) Attribute value(s) that apply to multiple frames from the metadata, and combine these itself.

  4. ICC profiles are embedded in rendered images of Media Type image/jpeg as one or more chunks in APP2 marker segments with an identifier of "ICC_PROFILE", as defined in Annex B of [ISO 15076-1].

  5. ICC profiles are embedded in rendered images of Media Type image/jp2 either as JP2 Restricted or JPX Full profiles according to [ISO/IEC 15444-1] and [ISO/IEC 15444-2], respectively; rendered images in the response are not subject to the prohibition against inclusion of a JP2 box in JPEG 2000 compressed data streams in DICOM images.

  6. ICC profiles are embedded in rendered images of Media Type image/png in an iCCP chunk, as defined in [ISO 15948].

8.3.5.2 Query Parameters For Thumbnails

Table 8.3.5-2shows the Query Parameters that may be used when requesting a Thumbnail representation.

Table 8.3.5-2. Thumbnail Query Parameters

Key

Values

Target Resource Category

Section

accept
Rendered Media Type

All Categories

Section 8.3.3.1

charset
character set token

All Categories

Section 8.3.3.2

viewport
vw, vh

All Categories

Section 8.3.5.1.3


The Viewport parameter only has width and height values. If no viewport parameter is provided the origin server will determine the size of the thumbnail.

8.4 Header Fields

The following sections specify important header fields, some of which have stronger requirements than those specified in the HTTP Standard.

8.4.1 Content Negotiation Header Fields

HTTP uses the Accept and Content-Type header fields for content negotiation and data typing. The media types in the Accept header field of a request define the media types that the user agent would find acceptable in the response. The media type in the Content-Type header field of a message, or payload part, describes the format of the representation contained in the message payload or payload part.

Content Negotiation header fields in requests allow the user agent to specify acceptable representations for the response. Table 8.4.1-1 lists the content negotiation header fields. The values in these fields apply to any content in the response, including representations of the Target Resource, representations of error or processing status, and potentially even the miscellaneous text strings that might appear within the HTTP protocol. See [RFC7231] Section 5.3.

Table 8.4.1-1. Content Negotiation Header Fields

Name

Value

Usage

Description

Accept

1#media-range

M

All requests that expect to receive a response with a payload shall contain an Accept header field. See Section 8.4.1.1.

Accept-Charset

1#charset

O

The Accept-Charset header field may be sent by a user agent to indicate what charsets are acceptable in response content. See [RFC7231] Section 5.3.3.

Accept-Encoding

1#encoding

O

The Accept-Encoding header field may be used to indicate the content-codings (see [RFC7231] Section 3.1.2.1) acceptable in the response. See [RFC7231] Section 5.3.4.

Accept-Language

1#language

O

The Accept-Language header field may be used by user agents to indicate the set of natural languages that are preferred in the response. See [RFC7231] Section 5.3.5.


8.4.1.1 Accept

User agents use the Accept header field to specify Acceptable Media Types for the response payload. The Accept header field can be used to indicate that the response payload is specifically limited to a set of desired media types. It has the following syntax:

Accept      = "Accept:" #( media-range [accept-params] )
media-range = ("*/*" 
              / (type "/" "*") 
              / (type "/" subtype)
              ) *(OWS ";" OWS accept-params)
accept-params = weight *(accept-ext)

Most requests have an Accept header field that contains a comma-separated list of one or more media ranges. A media-range extends media-type with wildcards (*/* or type/*) and parameters that are not defined for media-types. See [RFC7231] Section 5.3.2 for details.

For example, if the user agent is willing to accept any media type in the response it should include */* as a value of the Accept header field.

Many of the content negotiation header fields use a weight parameter, named "q" (case-insensitive), to assign a relative "weight" to the preference for that associated kind of content.

The media types in the Accept header can be given a priority ordering by using weights.

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

This weight is often referred to as "quality value" or "qvalue". See [RFC7231] Section 5.3.1.

All requests that might have a response containing a payload shall provide an Accept header field.

See Section 8.7.5 for Acceptable Media Types.

8.4.1.1.1 Charset Media Type Parameter

Many media types, especially text/* types, define a "charset" parameter that specifies the character set for the representation. See [RFC7231] Section 3.1.1.2.

DICOM Media Types define a "charset" parameter. See Section 8.7.3.5.3.

For example,

application/dicom; charset=ISO-8859-1

See Section 8.8.1 for Acceptable Character Sets.

8.4.2 Content Representation Header Fields

The media type in the Content-Type header field of a message, or payload part, describes the format of the representation contained in the payload or part.

When a message has a payload, the Content Representation Header Fields provide metadata describing how to interpret the representation(s) contained in the payload. Table 8.4.2-1 describes the Content Representation Header Fields, and the usage requirements (Mandatory, Conditional, or Optional) for when they shall be present.

Table 8.4.2-1. Content Representation Header Fields

Name

Value

Usage

Requirement

Content-Type

media-type

C

Specifies the media type of the representation contained in the payload.

If a message has a payload, it shall have a Content-Type header field specifying the media type of the payload. See [RFC7231] Section 3.1.1.5.

Content-Encoding

encoding

C

Specifies any content encodings applied to the representation (beyond those inherent in the media type), and thus what decoding to apply to obtain a representation in the media type specified by the Content-Type. See [RFC7230] Section 3.1.2.2.

Content-Encoding allows compression, encryption, and/or authentication of representations.

Shall be present if a content encoding has been applied to the representation in the payload.

Content-Language

language

O

Specifies the natural language(s) of the intended audience used in representation. See [RFC7231] Section 3.1.3.2.

Content-Location

url

C

Contains a URL that references the specific resource corresponding to the representation in the payload.

Shall be present if the payload contains a representation of a resource.


8.4.3 Payload Header Fields

The Payload Header Fields contain metadata describing the payload, not the representation it contains. Table 8.4.3-1 describes the payload header fields, and the usage requirements (Mandatory, Conditional, or Optional) for when they shall be present.

Table 8.4.3-1. Payload Header Fields

Name

Value

Usage

Description

Content-Length

uint

C

Specifies the decimal number of octets in the payload.

If the response message has a payload and does not have a Content-Encoding header field, it shall have a Content-Length header field specifying the length in octets (bytes) of the payload.

Shall not be present if the message has a Content-Encoding header field. Shall be present otherwise, even is the size of the payload is zero.

Content-Range

range

C

Specifies the range of a partial representation contained in a payload. See [RFC7233] Section 4.2.

The Content-Range header field is sent in a single part 206 (Partial Content) response to indicate the partial range of the selected representation enclosed as the message payload.

It is sent in each part of a multipart 206 response to indicate the range enclosed within each body part.

It is sent in 416 (Range Not Satisfiable) responses to provide information about the selected representation.

Transfer-Encoding

encoding

C

See [RFC7230] Section 3.3.1.

Shall be present if transfer-encodings have been applied to the payload.


8.5 Status Codes

Each response message contains a status-code.

The most common HTTP status codes used are listed in Table 8.5-1 Most of these codes are described in detail in [RFC7231]. IANA maintains the HTTP Status Code Registry [IANA HTTP Status Code Registry], which contains a complete list of registered status codes.

Table 8.5-1. Status Code Meaning

Status

Code

Description

Success

The 2xx (Successful) class of status code indicates that the client's request was successfully received, understood, and accepted.

200

(Success)

All Target Resource representations are contained in the payload. See [RFC7231] Section 6.3.1.

201

(Created)

The request has been fulfilled and has resulted in one or more new resources being created. See [RFC7231] Section 6.3.2.

202

(Accepted)

The request has been accepted for processing, but the processing has not been completed. The payload of this response should contain a Status Report. [RFC7231] Section 6.3.3.

The user agent may be able to inspect relevant resources to determine the status at some later time.

203

(Non-Authoritative Information)

The request was successful, but the enclosed payload has been modified from that of the origin server's 200 (OK) response by a transforming proxy. See [RFC7230] Section 5.7.2 and [RFC7230] [RFC7231] Section 6.3.4.

204

(No-Content)

The server has successfully fulfilled the request and there is no additional content to send in the response payload body. This should be the response when content is successfully uploaded, and the response has no payload.

For example, this status code is used in the response to a Conditional Retrieve request), when the Target Resource has not been modified. See [RFC7231] Section 6.3.5.

205

(Reset Content)

The server has fulfilled the request and desires that the user agent reset the "document view", which caused the request to be sent, to its original state as received from the origin server.

206

(Partial Content)

The 206 (Partial Content) status code indicates that the server is successfully fulfilling a range request for the Target Resource by transferring one or more parts of the selected representation that correspond to the satisfiable ranges found in the request's Range header field.

This status code shall only be used with Range Requests. See [RFC7233].

Note

This status code was previously (erroneously) used to indicate that only some of a payload was stored.

Redirection

The 3xx (Redirection) class of status code indicates that further action needs to be taken by the user agent to fulfill the request.

301

(Moved Permanently)

The origin server has assigned the Target Resource to a new permanent URI, indicated in a Location header field.

This status is typically needed when the resource has been moved from one service to another, for example during a migration.

303

(See Other)

The origin the server is redirecting the user agent to a different resource, as indicated by a URI in the Location header field, which will provide a response to the original request.

304

(Not Modified)

The origin server has received a conditional GET or HEAD request that would have resulted in a 200 (OK) response if it were not for the fact that the condition evaluated to false.

Client Error

The 4xx (Client Error) class of status code indicates that the user agent has erred.

For all these error codes,the origin server should return a payload containing an explanation of the error situation, and whether it is a temporary or permanent condition, except when responding to a HEAD request.

400

(Bad Request)

The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request …).

401

(Unauthorized)

The request has not been fulfilled because it lacks valid authentication credentials for the service or Target Resource. The server generating a 401 response shall send a WWW-Authenticate header field ([RFC7235] Section 4.1) containing at least one challenge applicable to the server or Target Resource.

403

(Forbidden)

The origin server understood the request, but refused to authorize it (e.g., an authorized user with insufficient privileges). If authentication credentials were provided in the request, the server considers them insufficient to grant access. The origin server may respond with a 404 (Not Found) if not permitted to use this status code.

404

(Not Found)

The origin server did not find a representation for the Target Resource or is not willing to disclose that one exists. This might be a temporary condition. If the origin server knows that the resource has been deleted, the 410 (Gone) status code shall be returned rather than 404.

405

(Method Not Allowed)

The method in the request is known by the origin server but not supported by the target service or resource. The origin server shall include an Allow header field in a 405 response containing a list of the target service or resource's currently supported methods.

406

(Not Acceptable)

The Target Resource does not have a representation that would be acceptable to the user agent, per the content negotiation header fields in the request, and the server is unwilling to supply a default representation.

The origin server should return a payload that lists the available media types and corresponding resource identifiers.

409

(Conflict)

The request could not be completed due to a conflict with the current state of the Target Resource. This code is used in situations where the user agent might be able to resolve the conflict and resubmit the request. The origin server should return a payload containing enough information for the user agent to recognize the source of the conflict.

In the DICOM context, this code might indicate that the origin server was unable to store any Instances due to a conflict in the request (e.g., unsupported SOP Class or Instance mismatch).

410

(Gone)

Access to the Target Resource is no longer available at the origin server and this condition is likely to be permanent. If the origin server does not know, or has no facility to determine, whether the condition is permanent, the 404 (Not Found) status code should be used instead.

411

(Length Required)

The origin server refuses to accept the request because the Content-Length header field was not specified.

413

(Payload Too Large)

The server is refusing to process the request because the request payload is larger than the server is willing or able to process.

414

(URI Too Long)

The server is refusing to service the request because the request-target ([RFC7230] Section 5.3) is longer than the server is willing to interpret.

415

(Unsupported Media Type)

The origin server does not support the Content-Type in the request payload. This error typically occurs when the user agent is trying to create or update a resource.

The origin server should return a payload that lists the available media types and corresponding resource identifiers.

Note

This is different from 406 (Not Acceptable).

Server Error

The 5xx (Server Error) class of status code indicates that the server is aware that it has erred or is incapable of performing the requested method.

For all these error codes, the server should send an explanation of the error situation, and whether it is a temporary or permanent condition, except when responding to a HEAD request.

500

(Internal Server Error)

The server encountered an unexpected condition that prevented it from fulfilling the request.

501

(Not Implemented)

The server does not support the functionality required to fulfill the request.

In the DICOM context, this status code shall be used for SOP Class Not Supported errors.

503

(Service Unavailable)

The origin server is currently unable to handle the request due to a temporary overload or scheduled maintenance, which will likely be alleviated after some delay.

505

(HTTP Version Not Supported)

The origin server does not support, or refuses to support, the major version of HTTP that was used in the request message.


When a web server determines that a user agent should not receive certain information, the web server must choose the status code and the contents of a Status Report carefully. For example, local policy may dictate that the web service returns a 404 (Not Found) rather than a 401 (Unauthorized) status code to avoid allowing the user agent to infer the existence of a resource. The status code and payload of the response needs to be controlled by policy and context, balancing usability of the returned result against appropriate protection. See also [FHIR Access Denied] and [OWASP Information Leakage].

8.6 Payloads

Both request and response messages may have message bodies. The message body (if any) of an HTTP message is used to carry the payload of the message. The message body is identical to the payload unless a content coding has been applied, as described in [RFC7230] Section 3.3.1. This Part of the Standard uses the term "payload" to denote the message body before any content coding has been applied to it.

A message may or may not have a payload. A payload may be empty; that is, its length is zero. If a message has no payload, then the message shall have neither Content-Encoding nor Content-Length header fields. If a message has a payload to which a transfer-coding has been applied, then the message shall have a Content-Encoding header field. If a message has a payload that has not had a transfer-coding applied, then the message shall have a Content-Length header field.

Any message containing a payload shall have appropriate Content Representation [RFC7231] Section 3.1 and Payload Header Fields [RFC7231] Section 3.3.

8.6.1 Payload Structure

Payloads contain representations. Payloads may be single part or multipart.

The message Content-Type header field contains a media type that includes multipart/related when the payload is multipart, otherwise the payload is single part.

8.6.1.1 Single Part Payload

A message with a single part payload contains one representation that is described by the Content Representation Header Fields (see Section 8.4.3) contained in the message header.

A message with a single part payload shall have a Content-Type header field with a single part media-type (see Section 8.7.3).

8.6.1.2 Multipart Payload

A message with a multipart payload contains one or more representations. Each representation goes in a separate part.

A message with a multipart payload shall have a Content-Type header field with a multipart media-type.

The media type of the root representation (see [RFC2387]) may be specified by the Content-Type header field of the message. If no root parameter is specified, then the root representation is the first representation in the payload.

Each part in a multipart payload shall start with a boundary string, followed by a Content-Type header field with a single part media type (see Section 8.7.3), followed by other fields as specified in Table 8.6.1-1. See also Figure 8.6-1. Other header fields may be included.

Note

Understanding the nature of an encoded Bulkdata resource may depend on the corresponding Metadata reference to the bulkdataURI and is not necessarily implicit in the Content-Type header field.

The Content-Location is used to identify the specific resource (e.g. down to the level of a specific frame or instance or bulkdataURI) represented in this part. This allows the payload recipient to distinguish the parts, for example when each part contains a different frame of a requested multi-frame instance.

Note

  1. The metadata in the response of a Search Transaction is not considered a representation of a resource, so a Content-Location is not required.

  2. In the case of a rendered resource, the Content-Location will identify the resource from which the rendering was generated.

Table 8.6.1-1. Multipart Header Fields

Name

Value

Usage

Description

Content-Type

media-type

M

Content-Encoding

encoding

C

Shall be present if the response payload has a content encoding

Content-Length

uint

C

Shall be present if the response payload does not have a content encoding

Content-Location

url

C

Shall be present if the response payload contains a representation of a resource. See [RFC7231] Section 3.1.4.2.

Location

url

C

See [RFC7231] Section 7.1.2.


See Section 8.7.1 and [RFC7231].

The following is an example template of a multipart request or response message that has a multipart payload:

request-line / response-line
Content-Type: multipart-media-type CRLF
Content-Location: "/" {/url} CRLF
*(header-field CRLF)
CRLF
multipart-payload

The Content-Type header field shall have a multipart media-type. For example:

Content-Type: multipart/related; type=DQ root-media-type DQ; boundary="---boundary---"

Where

multipart-media-type

is a media type defined by [RFC2387].

root-media-type

is a single part media type that specifies the media type of the root, typically the first part, in the payload. If the value of the type parameter and the root body part's content-type differ then the user agent's behavior is undefined.

boundary

specifies a string that acts as a boundary between message parts.

If a multipart payload contains representations of Metadata (see Section 8.7.3.3.1), and Bulkdata (see Section 8.7.3.3.2), then all Metadata message parts that reference a Bulkdata part shall precede the referenced Bulkdata part. The Content-Location of the Bulkdata part shall contain the corresponding BulkDataURI used in the referencing Metadata.

Figure 8.6-1 shows the correspondence between the IOD representation and a multipart payload.

Mapping between IOD and HTTP message parts

Figure 8.6-1. Mapping between IOD and HTTP message parts


8.6.1.2.1 Multipart Payload Syntax

The syntax of a multipart payload is:

multipart-payload = 1*(DASH boundary CRLF part CRLF) DASH boundary DASH

Where

DASH         = "--"
boundary     = 0*69(bchar / SP) bchar
bchar        = DIGIT / ALPHA / "'" / "(" / ")" / "+" / "_"   ; The legal boundary characters
             / "," / "-" / "." / "/" / ":" / "=" / "?"
part         = Content-Type: media-type CRLF
               Content-Location: url CRLF
               (Content-Length: uint CRLF / Content-Encoding: encoding CRLF)
               [Content-Description: text CRLF]
               *(header-field CRLF)
               CRLF
               part-payload
part-payload = *OCTET

For example, if the boundary is "++++", then a message payload containing three parts would be structured as follows:

--++++CRLF
Content-Type: media-type CRLF
Content-Location: url CRLF
(Content-Length: uint CRLF / Content-Encoding: encoding CRLF)
[Content-Description: {description} CRLF]
CRLF
payload CRLF
--++++CRLF
Content-Type: media-type CRLF
. . .
payload CRLF
--++++CRLF
Content-Type: media-type CRLF
. . .
payload CRLF
--++++--

8.6.2 DICOM Representations

All DICOM objects are defined by Information Object Definitions (IODs). See PS3.3. Representations of DICOM Resources are encodings of DICOM Information Objects into octet streams.

Each IOD has an associated set of Attributes, which define semantic concepts. Each Attribute has:

  • a Tag, which identifies the Attribute using an integer

  • a Keyword, which identifies the Attribute using a token

  • a Type, which indicates whether the Attribute is required or optional

  • a Value Representation, which defines the data type of the Attribute's value(s)

  • a Value Multiplicity, which specifies the number of values that the Attribute may have

A Data Element is a concrete representation of an Attribute See PS3.5. Each Data Element has:

  • an identifier, which would typically be its Tag, but could be its Keyword

  • a Value Representation, which defines its data type

  • a Value Length

  • a Value Field, which is a sequence of bytes containing zero or more values

Each Instance contains Data Elements representing the Attributes from the Patient, Study, Series, and Instance levels of the IOD. For example, if a Series resource contains 12 Instances, then a transaction that retrieves that Series will contain a representation of the Series and its 12 Instances, in a specific media type, and each Instance will have Patient, Study, Series, and Instance level Attributes.

This Part of the Standard defines three distinct representations of DICOM Resources that can be encoded into DICOM Media Types: Instances, Metadata, and Bulkdata.

DICOM Media Types and their corresponding representations are defined in Section 8.7.3. Other media types used in this Part of the Standard are defined in Section 8.7.4.

8.6.2.1 Web Service Constraints

DICOM Web Services only support representations with explicit Value Representations. Implicit Value Representations (see Section 7.1.3 “Data Element Structure with Implicit VR” in PS3.5) shall not be used.

8.6.3 Status Report

A Status Report is a description of warnings or errors encountered by the origin server in processing a request. The contents should be clear and succinct. If the request does not include an Acceptable Media Type, the Status Report should use the default media type for the Text Resource Category, which is text/html.

8.7 Media Types

Media types are the basis for both content negotiation and data typing of message payloads. Each PS3.18 service, and/or transaction defines the media types and associated representations that are default, required and optional.

The media type also specifies whether the payload contains a single representation (single part), or multiple representations (multipart). Multipart payloads are only defined for the RESTful APIs. See Section 8.6.1.2 and Section 10.4.3.

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 to provide open and extensible data typing and type negotiation. The syntax of media types is:

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

Where

type         = token
subtype      = token
mt-parameter = mtp-name "=" mtp-value 
mtp-name     = token
mtp-value    = (token / quoted-string)

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

The type, subtype, and mtp-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.

An mtp-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 [IANA Media Types].

Many media types specify a character set parameter.

Note

The term "MIME Type" is not synonymous with "Media Type". MIME types are defined by Multipurpose Internet Mail Extensions [RFC2045] and used by email programs. Media Types are defined by Media Type Specifications and Registration Procedures [RFC6838].

8.7.1 Multipart Media Types

Some of the services defined in this Part of the 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 RESTful services. Its syntax is:

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

Where

boundary           ; See Section 8.6.1.2.1
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.

8.7.2 DICOM Resource Categories

Table 8.7.2-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 8.7.2-1. Resource Categories

Resource Category

Definition

Single Frame Image

This category includes all resources that are:

  1. Instances of a single frame SOP Class, or

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

  3. 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 are:

  1. Instances encoded in the MPEG family of Transfer Syntaxes (which includes MPEG2, MPEG-4 AVC/H.264 and HEVC/H.265), or

  2. 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 contain:

  1. 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. 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, for example waveforms.


Note

The Resource Category is independent of the Transfer Syntax used to natively encode or return the Resource. In particular, if the Transfer Syntax is one of the JPIP Transfer Syntaxes (for which the pixel data is not included in the returned objects, but rather a URL of the JPIP provider for retrieving the pixel data is present in the metadata) the Resource Category will still be Single Frame Image or Multi-Frame Image, and not Text or Other.

8.7.3 DICOM Media Type Sets

This section defines the media types used to represent DICOM Instances, Metadata and Bulkdata. It describes:

  • The media type and Transfer Syntax parameters for DICOM PS3.10 Instances

  • The media types that can be used for Metadata

  • The media types and Transfer Syntaxes parameters for Bulkdata

  • 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 defined in this section are distinct from those into which DICOM Instances may be rendered (which are defined in Section 8.7.4); some of the same media types are used for both rendered content and Bulkdata.

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.

The Implicit VR Little Endian (1.2.840.10008.1.2), and Explicit VR Big Endian (1.2.840.10008.1.2.2 - Retired) 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 8.7.3-2, Table 8.7.3-4 or Table 8.7.3-5, unless the origin server has only access to the pixel data in lossy compressed form or the pixel data in a lossless compressed form that is of such length that it cannot be encoded in the Explicit VR Little Endian Transfer Syntax.

Table 8.7.3-1 specifies the definition of media type requirement terms used in the tables in this section.

Table 8.7.3-1. Definition of Media Type Requirement

Requirement

Optionality

Definition

Default

D

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

Required

R

The origin server shall support this media type.

Optional

O

The origin server may support this media types.


Table 8.7.3-2, Table 8.7.3-3, Table 8.7.3-4, and Table 8.7.3-5 specify the media types used to encode different representations of DICOM Instances. These media types apply to all Resource Categories and have default encodings for images and video data elements contained in the Instances.

8.7.3.1 Instance Media Types

The application/dicom media type specifies a representation of Instances encoded in the DICOM File Format specified in Section 7 “DICOM File Format” in PS3.10.

Note

The origin server may populate the PS3.10 File Meta Information with the identification of the Source, Sending and Receiving AE Titles and Presentation Addresses as described in Section 7.1 in PS3.10 , or these Attributes may have been left unaltered from when the origin server received the objects. The user agent storing the objects received in the response may populate or coerce these Attributes based on its own knowledge of the endpoints involved in the transaction, so that they accurately identify the most recent storage transaction.

Table 8.7.3-2 specifies the default and optional Transfer Syntax UID combinations for each DICOM Resource Category (see Table 8.7.2-1). The default media type for the Resource Category shall be returned when the origin server supports none of the Acceptable Media Types, unless the origin server has only access to the pixel data in lossy compressed form or the pixel data in a lossless compressed form that is of such length that it cannot be encoded in the Explicit VR Little Endian Transfer Syntax.

Table 8.7.3-2. Transfer Syntax UIDs for application/dicom Media Types

Category

Transfer Syntax UID

Transfer Syntax Name

Optionality

Single Frame Image

1.2.840.10008.1.2.1

Explicit VR Little Endian

D

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

O

1.2.840.10008.1.2.4.50

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

O

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)

O

1.2.840.10008.1.2.4.57

JPEG Lossless, Non-Hierarchical (Process 14)

O

1.2.840.10008.1.2.5

RLE Lossless

O

1.2.840.10008.1.2.4.80

JPEG-LS Lossless Image Compression

O

1.2.840.10008.1.2.4.81

JPEG-LS Lossy (Near-Lossless) Image Compression

O

1.2.840.10008.1.2.4.90

JPEG 2000 Image Compression (Lossless Only)

O

1.2.840.10008.1.2.4.91

JPEG 2000 Image Compression

O

1.2.840.10008.1.2.4.92

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

O

1.2.840.10008.1.2.4.93

JPEG 2000 Part 2 Multi-component Image Compression

O

Multi-frame Image

1.2.840.10008.1.2.1

Explicit VR Little Endian

D

1.2.840.10008.1.2.4.90

JPEG 2000 Image Compression (Lossless Only)

O

1.2.840.10008.1.2.4.91

JPEG 2000 Image Compression

O

1.2.840.10008.1.2.4.92

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

O

1.2.840.10008.1.2.4.93

JPEG 2000 Part 2 Multi-component Image Compression

O

Video

1.2.840.10008.1.2.1

Explicit VR Little Endian

D

1.2.840.10008.1.2.4.100

MPEG2 Main Profile @ Main Level

O

1.2.840.10008.1.2.4.101

MPEG2 Main Profile @ High Level

O

1.2.840.10008.1.2.4.102

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

O

1.2.840.10008.1.2.4.103

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

O

1.2.840.10008.1.2.4.104

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

O

1.2.840.10008.1.2.4.105

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

O

1.2.840.10008.1.2.4.106

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

O

1.2.840.10008.1.2.4.100.1

Fragmentable MPEG2 Main Profile @ Main Level

O

1.2.840.10008.1.2.4.101.1

Fragmentable MPEG2 Main Profile @ High Level

O

1.2.840.10008.1.2.4.102.1

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

O

1.2.840.10008.1.2.4.103.1

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

O

1.2.840.10008.1.2.4.104.1

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

O

1.2.840.10008.1.2.4.105.1

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

O

1.2.840.10008.1.2.4.106.1

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

O

1.2.840.10008.1.2.4.107

HEVC/H.265 Main Profile / Level 5.1

O

1.2.840.10008.1.2.4.108

HEVC/H.265 Main 10 Profile / Level 5.1

O

Text

1.2.840.10008.1.2.1

Explicit VR Little Endian

D

Other

1.2.840.10008.1.2.1

Explicit VR Little Endian

D


Note

The Transfer Syntaxes used in a DICOM-RTV Metadata Flow are not included, since they are not used to produce a representation of an Instance encoded in the DICOM File Format.

8.7.3.2 Metadata Media Types

Table 8.7.3-3 specifies the media types that may be used to encode representations of Metadata for the URI and RESTful services. Only the RESTful Services support Metadata representations.

Table 8.7.3-3. Media Types for Metadata

Media Type

Descriptions

URI

RESTful

application/dicom+xml

Encodes Instances as XML Infosets defined in the Native DICOM Model defined in PS3.19.

not applicable

required

application/dicom+json

Encodes Instances in the JSON format defined in Annex F.

not applicable

required


8.7.3.3 Bulkdata Media Types

Bulkdata representations are only supported by RESTful services. There are two categories of Bulkdata: uncompressed and compressed.

The Selected Media Type will be the default media type for the Resource Category when the origin server supports none of the Acceptable Media Types, as described in Section 8.7.8, unless the origin server has only access to the pixel data in lossy compressed form or the pixel data in a lossless compressed form that is of such length that it cannot be encoded in the Explicit VR Little Endian Transfer Syntax.

The origin server may support additional Transfer Syntaxes.

If no media type Transfer Syntax parameter is specified, then the Explicit VR Little Endian Transfer Syntax "1.2.840.10008.1.2.1" shall be used, unless the origin server has only access to the pixel data in lossy compressed form or the pixel data in a lossless compressed form that is of such length that it cannot be encoded in the Explicit VR Little Endian Transfer Syntax.

Note

The tables in this section have no entries for the URI service, since they do not support separate retrieval of Bulkdata.

Depending on the Selected Media Type, the pixel data of a resource in the Single Frame Image Resource Category is encoded in:

  • one compressed Bulkdata representation, or

  • one uncompressed Bulkdata representation.

Depending on the Selected Media Type, the pixel data of a resource in the Multi-Frame Image Resource Category is encoded in:

  • multiple Single Frame Image compressed Bulkdata representations: one for each frame, or

  • one Multi-Frame Image uncompressed Bulkdata representation.

Depending on the Selected Media Type, the pixel data of a resource in the Video Resource Category is encoded in:

  • one Video compressed Bulkdata representation, or

  • one Video uncompressed Bulkdata representation.

8.7.3.3.1 Uncompressed Bulkdata Media Types

Table 8.7.3-4 specifies the default media type and Transfer Syntax UIDs, by Resource Category (see Table 8.7.2-1) that can be used with uncompressed Bulkdata for the RESTful services. Uncompressed Bulkdata is encoded as a stream of uncompressed bytes (octets) 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 Bulkdata.

Table 8.7.3-4. Transfer Syntax UIDs for Uncompressed Data in Bulkdata

Category

Media Type

Transfer Syntax UID

Transfer Syntax Name

RESTful

Single Frame Image

application/octet-stream

1.2.840.10008.1.2.1

Explicit VR Little Endian

D

Multi-Frame Image

application/octet-stream

1.2.840.10008.1.2.1

Explicit VR Little Endian

D

Video

application/octet-stream

1.2.840.10008.1.2.1

Explicit VR Little Endian

D

Text

application/octet-stream

1.2.840.10008.1.2.1

Explicit VR Little Endian

D

Other

application/octet-stream

1.2.840.10008.1.2.1

Explicit VR Little Endian

D


Note

Even though the Transfer Syntax is Explicit VR Little Endian, the Value Representation is not actually encoded at the beginning of the octet-stream. The Value Representation is contained in the Metadata that references the Bulkdata.

8.7.3.3.2 Compressed Bulkdata Media Types

Compressed Bulkdata contains only the compressed octet stream without the fragment delimiters.

Table 8.7.3-5 specifies the default and optional media types and Transfer Syntax UID combinations for each Resource Category (see Table 8.7.2-1) of compressed Bulkdata for the RESTful services.

Note

  1. Some of the Transfer Syntax Names include text about Default Transfer Syntax, however this applies to its role in DIMSE transactions, rather than the default for RESTful services (which is specified in the RESTful column of the table).

  2. The Media Type column reflects the data encoding but does not include extended media type descriptors such as "multipart/related" that describe further packaging of the encoded data.

These media types can be used to retrieve Bulkdata, such as images or video, encoded in a specific Transfer Syntax.

For details on how Compressed Bulkdata is packaged into single part or multipart payloads, see Section 8.6.1.

Table 8.7.3-5. Media Types and Transfer Syntax UIDs for Compressed Data in Bulkdata

Resource Category

Media Type

Transfer Syntax UID

Transfer Syntax Name

Optionality

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

D

1.2.840.10008.1.2.4.50

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

O

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)

O

1.2.840.10008.1.2.4.57

JPEG Lossless, Non-Hierarchical (Process 14)

O

image/dicom-rle

1.2.840.10008.1.2.5

RLE Lossless

D

image/jls

1.2.840.10008.1.2.4.80

JPEG-LS Lossless Image Compression

D

1.2.840.10008.1.2.4.81

JPEG-LS Lossy (Near-Lossless) Image Compression

O

image/jp2

1.2.840.10008.1.2.4.90

JPEG 2000 Image Compression (Lossless Only)

D

1.2.840.10008.1.2.4.91

JPEG 2000 Image Compression

O

image/jpx

1.2.840.10008.1.2.4.92

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

D

1.2.840.10008.1.2.4.93

JPEG 2000 Part 2 Multi-component Image Compression

O

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

D

1.2.840.10008.1.2.4.50

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

O

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)

O

1.2.840.10008.1.2.4.57

JPEG Lossless, Non-Hierarchical (Process 14)

O

image/dicom-rle

1.2.840.10008.1.2.5

RLE Lossless

D

image/jls

1.2.840.10008.1.2.4.80

JPEG-LS Lossless Image Compression

D

1.2.840.10008.1.2.4.81

JPEG-LS Lossy (Near-Lossless) Image Compression

O

image/jp2

1.2.840.10008.1.2.4.90

JPEG 2000 Image Compression (Lossless Only)

D

1.2.840.10008.1.2.4.91

JPEG 2000 Image Compression

O

image/jpx

1.2.840.10008.1.2.4.92

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

D

1.2.840.10008.1.2.4.93

JPEG 2000 Part 2 Multi-component Image Compression

O

Video

video/mpeg2

1.2.840.10008.1.2.4.100

MPEG2 Main Profile @ Main Level

O

1.2.840.10008.1.2.4.100.1

Fragmentable MPEG2 Main Profile @ Main Level

O

1.2.840.10008.1.2.4.101

MPEG2 Main Profile @ High Level

D

1.2.840.10008.1.2.4.101.1

Fragmentable MPEG2 Main Profile @ High Level

O

video/mp4

1.2.840.10008.1.2.4.102

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

D

1.2.840.10008.1.2.4.102.1

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

D

1.2.840.10008.1.2.4.103

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

O

1.2.840.10008.1.2.4.103.1

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

O

1.2.840.10008.1.2.4.104

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

O

1.2.840.10008.1.2.4.104.1

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

O

1.2.840.10008.1.2.4.105

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

O

1.2.840.10008.1.2.4.105.1

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

O

1.2.840.10008.1.2.4.106

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

O

1.2.840.10008.1.2.4.106.1

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

O

Text

N/A (no defined compression transfer syntaxes for Text)

Other

N/A (no defined compression transfer syntaxes for Other)


The origin server may support additional Transfer Syntaxes.

For the media type image/jpeg Transfer Syntaxes, the image may or may not include the JFIF marker segment. The image may or may not include APP2 marker segments with an identifier of "ICC_PROFILE". There is no requirement for the origin server to add a JFIF marker segment nor to copy the value of the ICC Profile (0028,2000) Attribute, if present, into APP2 marker segments in the compressed data stream. See Section 8.2.1 “JPEG Image Compression” in PS3.5.

For the media type image/jp2 and image/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

Compressed multi-frame image pixel data is encoded as individual frames. E.g., each frame of a JPEG 2000 multi-frame image will be encoded separately as image/jp2 representations, rather than as a single video/mj2 ([RFC3745]) or application/octet-stream representation. See Section 8.6.1.2 for details on how multiple representations can be packaged into a multipart payload.

Video pixel data is encoded as a single video representation. E.g., all frames of an MPEG-4 video will be encoded as a single video/mp4 ([RFC_4337]) representation.

Note

  1. 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.

  2. Many of the media types used for compressed Pixel Data transferred as Bulkdata values are also used for consumer format media types. A web 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 8.7.4.

    For example, the media type for Bulkdata values of lossless 16-bit JPEG [ISO/IEC 10918-1] encoded Pixel Data is "image/jpeg", the same media type as might be used for 8-bit JPEG [ISO/IEC 10918-1] encoded Pixel Data, whether extracted as Bulkdata, or rendered. The Transfer Syntax parameter of the Content-Type header field is useful to signal the difference.

  3. Previously, experimental Media Types "image/x-dicom-rle" and "image/x-jls" were defined, so origin servers and user agents may want to account for these when communicating with older implementations. These have been replaced with the standard Media Types "image/dicom-rle" and "image/jls", respectively.

8.7.3.4 Transfer Syntax

The Default Transfer Syntax for DICOM objects contained in a payload shall be Explicit VR Little Endian Uncompressed "1.2.840.10008.1.2.1". If the Transfer Syntax is not specified in a message, then the Default Transfer Syntax shall be used, unless the origin server has only access to the pixel data in lossy compressed form or the pixel data in a lossless compressed form that is of such length that it cannot be encoded in the Explicit VR Little Endian Transfer Syntax.

Note

  1. 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.

  2. Every origin server is required to be able to convert any Data Set it is going to return into the Explicit VR Little Endian Transfer Syntax, regardless of the form in which it originally received or stored the Data Set, except in the cases of when the decompressed Pixel Data is too large to encode in the Explicit VR Little Endian Transfer Syntax or is received in a lossy compressed form. In the case of lossy compressed Pixel Data, the origin server is permitted to return the lossy compressed Transfer Syntax appropriate to the lossy form that was received. In the case of lossless compressed Pixel Data that is too large to encode in the Explicit VR Little Endian Transfer Syntax, the origin server is permitted to return any appropriate lossless compression Transfer Syntax, not necessarily that in which the image was received, as an alternative to the Explicit VR Little Endian Transfer Syntax.

  3. If transcoding to the Explicit VR Little Endian Transfer Syntax, a VR of UN may be needed for the encoding of Data Elements with explicit VR whose value length exceeds 65534 (216-2) (FFFEH, the largest even length unsigned 16 bit number) but which are defined to have a 16 bit explicit VR length field. See Section 6.2.2 in PS3.5 .

Implicit VR Little Endian, or Explicit VR Big Endian shall not be used.

The response payload encoding requirements are defined in Section 8.7.8.

Note

The transfer syntax can be one of the JPIP Transfer Syntaxes, in which case the returned objects will contain the URL of the JPIP provider for retrieving the pixel data.

The origin server may support additional Transfer Syntaxes.

8.7.3.5 Media Type Syntax

The syntax of Media Type usage in DICOM is:

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

Where

dcm-singlepart = dcm-mt-name
dcm-multipart  ;see Section 8.7.3.5.1
dcm-parameters = transfer-syntax-mtp ;see Section 8.7.3.5.2
               / charset-mtp;see Section 8.7.3.5.3
dcm-mt-name    = dicom / dicom-metadata / bulkdata / pixeldata ;DICOM Media Type name
dicom          = "application/dicom"
dicom-metadata = dicom-xml / dicom-json
dicom-xml      = "application/dicom+xml"
dicom-json     = "application/dicom+json"
bulkdata       = octet-stream / pixeldata
octet-stream   = "application/octet-stream"
pixeldata      = image-pixel / video-pixel
rendered       = image-pixel / video-pixel
image-pixel    = "image/jpeg" / "image/dicom-rle" / "image/jls" / "image/jp2" / "image/jpx"
video-pixel    = "video/mpeg2" / "video/mp4"

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

Note

The application/dicom+xml and application/dicom+json Media Types may have a Transfer Syntax parameter in order to specify the encoding of base64 data.

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

8.7.3.5.1 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-mt-name / rendered

See Section 8.6.1.2.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. For example:

Accept: multipart/related; type="application/octet-stream", multipart/related; type="image/*"; boundary=**, multipart/related; type="video/*"; boundary=**
8.7.3.5.2 Transfer Syntax Parameter

For a given DICOM Media Type, a single Transfer Syntax parameter value may be specified, but its usage may be constrained by the service for which they are used.

RESTful origin servers shall support the Transfer Syntax parameter.

Transfer syntax media type parameters are forbidden in URI Service 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 Table A-1 “UID Values” in PS3.6 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 [RFC6838] 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; type="application/dicom";transfer-syntax=1.2.840.10008.1.2.4.50;boundary=**, multipart/related; type="application/dicom";transfer-syntax=1.2.840.10008.1.2.4.57;q=0.5;boundary=**

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, unless the origin server has only access to the pixel data in lossy compressed form or the pixel data in a lossless compressed form that is of such length that it cannot be encoded in the Explicit VR Little Endian Transfer Syntax.

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.

8.7.3.5.3 Character Set Parameter

All DICOM Media Types may have a single Character Set parameter, which shall have only a single value, that specifies the Acceptable Character Set for the response.

The syntax is:

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

All DICOM Media Types have a Default Character Set of UTF-8. See Section 8.8 for character set details.

8.7.3.6 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.

The syntax is:

transfer-syntax-qp = %s"transferSyntax" "=" (1#transfer-syntax-uid / "*")

This Query Parameter is only used by the URI Service.

RESTful services specify the Transfer Syntax in the "accept" Query Parameter (see Section 8.3.3.1) and do not use Transfer Syntax Query Parameter.

8.7.3.7 Acceptable Transfer Syntaxes

Each DICOM Media Type in the Acceptable Media Types has an Acceptable Transfer Syntax, which is explicitly specified or has a default value.

Depending on the service, the Acceptable Transfer Syntax for a DICOM Media Type can be specified in the:

  1. Transfer Syntax media type parameter contained in the Accept Query Parameter (see Section 8.3.3.1)

  2. Transfer Syntax media type parameter contained in the Accept header field

  3. Transfer Syntax Query Parameter (see Section 8.7.3.5)

8.7.4 Rendered Media Types

DICOM Instances may be converted by a rendering process into non-DICOM Media Types. This can be useful to display or process them using non-DICOM software, such as browsers.

For example, an Instance containing:

  1. an image could be rendered into the image/jpeg or image/png Rendered Media Types.

  2. a multi-frame image in a lossless Transfer Syntax could be rendered into a video/mpeg or video/mp4 Rendered Media Type.

  3. 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 Bulkdata Media Types, that is, for encoding Bulkdata extracted from Encapsulated Pixel Data (used with compressed Transfer Syntaxes), without applying a rendering process. See Section 8.7.3.3.

Rendered images shall contain no more than 8 bits per channel.

Origin servers shall support rendering Instances of different Resource Categories into Rendered Media Types as specified in Table 8.7.4-1.

Table 8.7.4-1. Rendered Media Types by Resource Category

Category

Media Type

URI

RESTful

Single Frame Image

image/jpeg

D

D

image/gif

O

R

image/png

O

R

image/jp2

O

O

Multi-frame Image

image/gif

O

O

Video

video/mpeg

O

O

video/mp4

O

O

video/H265

O

O

Text

text/html

D

D

text/plain

R

R

text/xml

O

R

text/rtf

O

O

application/pdf

O

O


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].

The origin server may support additional Rendered Media Types, which shall be documented in the Conformance Statement and, if the service supports it, the Retrieve Capabilities response.

A Transfer Syntax media type parameter is not permitted for Rendered Media Types.

8.7.5 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.

The response to a request without an Accept header field shall be 406 (Not Acceptable). The presence of an Accept Query Parameter does not eliminate the need for an Accept header field. For details see Section 8.3.3.1.

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 400 (Bad Request).

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.

8.7.6 Accept Query Parameter

The Accept Query Parameter can be used to specify Acceptable Media Types. See Section 8.7.5.

8.7.7 Accept Header Field

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

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

The Accept header field 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. 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. DICOM specifies that the */* media range matches the default media type for the target's Resource Category. If no default media type is defined for a Resource Category, then any media type from the Resource Category is acceptable.

If the response might contain a payload, an Accept header field shall be present in the request.

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, including media type parameters, that are not valid or not supported shall be ignored by the origin server.

8.7.8 Selected Media Type and Transfer Syntax

The selection of the media type and transfer syntax by the origin server are interrelated.

8.7.8.1 Selected Media Type

The Selected Media Type is the media type selected by the origin server for the representation in 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.

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. Identify the target's Resource Category

  2. Select the representation with the highest priority supported media type for that category in the Accept Query Parameter.

  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).

Note

  1. If the Selected Media Type is the Explicit VR Little Endian and the pixel data is compressed and when uncompressed is of such length that it cannot contained in a value field, then the origin server will respond with a 406 (Not Acceptable), and the user agent may try again with a different set of Acceptable Media Types.

  2. If transcoding to the Explicit VR Little Endian Transfer Syntax, a VR of UN may be needed for the encoding of Data Elements with explicit VR whose value length exceeds 65534 (216-2) (FFFEH, the largest even length unsigned 16-bit number) but which are defined to have a 16-bit explicit VR length field. See Section 6.2.2 “Unknown (UN) Value Representation” in PS3.5.

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 which 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 qvalues, based on the media ranges above:

Table 8.7.8-1. Media Type QValue Example

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.

8.7.8.2 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 8.7.8 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, if any;

  3. Otherwise select the default Transfer Syntax (see Table 8.7.3-2, Table 8.7.3-4 or Table 8.7.3-5) 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 if the result is the same.

8.7.9 Content-Type Header Field

The Content-Type header field specifies the media type of the payload. It shall 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 8.7.3.5.2), and zero or one charset parameter (see Section 8.7.3.5.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.

8.8 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 [IANA Character Sets].

Character sets may also be identified by using the DICOM Defined Terms for the character set (see Annex D, Section C.12.1.1.2 in PS3.3 , and Section 6.1.2.3 “Encoding of Character Repertoires” in PS3.5), which shall be quoted strings since they contain the space (' ') character.

The syntax is:

charset = token / defined-term / DQ defined-term DQ

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.

The origin server shall support the "UTF-8" charset name for RESTful Retrieve Rendered transaction but is not required to support the DICOM Defined Term "ISO_IR 192". 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 URIs.

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

A request without any Character Set Query Parameter or Accept-Charset header field implies that the user agent will accept any character set in the response.

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

8.8.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 Acceptable Character Sets contains a list of one or more Defined Terms they shall be ordered by the user agent 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 charset values that are not valid or not supported shall be ignored by the origin server.

8.8.2 Character Set Query Parameter

See Section 8.3.3.2 .

8.8.3 Character Set Media Type Parameters

DICOM Media Types accept character set (charset) parameters. See Section 8.7.3.5.3.

Many other media types also accept character set (charset) parameters. See [IANA Media Types].

8.8.4 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 charsets and/or the wildcard value ("*").

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.

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

8.8.5 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 theSelected 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 Instances may be convertible, and others will not be, even though they have the same Specific Character Set (0008,0005).

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:

    • A question mark ("?"), or other similar character indicating an unknown character.

    • The corresponding Unicode Code Point for the character, represented as "U+xxxx".

    • The four characters "\nnn", where "nnn" is the 3-digit octal representation of each byte (see Section 6.1.2.3 “Encoding of Character Repertoires” in PS3.5).

8.9 Retrieve Capabilities Transaction

This transaction retrieves a Capabilities Description (see Annex H), which is a machine-readable description of the service(s) implemented by an origin server. All RESTful services defined by this Part of the Standard shall implement this transaction.

The Target Resource for this transaction is an origin server. The response contains a Capabilities Description, which describes the transactions, resources, representations, etc. that are supported by the service(s).

8.9.1 Request

The request shall have the following syntax:

OPTIONS SP / SP version CRLF
Accept: 1#media-type CRLF
*(header-field CRLF)
CRLF

8.9.1.1 Resource

The Target Resource for this transaction is the Base URI ("/") for the Service. See Section 8.2.

8.9.1.2 Query Parameters

This transaction has no Query Parameters.

8.9.1.3 Request Header Fields

Table 8.9.1-1. Request Header Fields

Name

Value

Usage

Description

User Agent

Origin Server

Accept

media-type

M

M

The Acceptable Media Types for the response payload

Accept-Charset

charset

O

O

The Acceptable Character Sets of the response payload


See also Section 8.4.

8.9.1.4 Request Payload

The request has no payload.

8.9.2 Behavior

The origin server shall return a Capabilities Description, as defined in Annex H, in an Acceptable Media Type.

8.9.3 Response

The format of the response is as follows:

version SP status-code SP reason-phrase CRLF
[Content-Type: media-type CRLF]
[(Content-Length: uint) / (Content-Encoding: encoding) CRLF]
*(header-field CRLF)
CRLF
[payload / status-report]

8.9.3.1 Status Codes

Table 8.9.3-1 shows some common status codes corresponding to this transaction. See also Section 8.5 for additional status codes.

Table 8.9.3-1. Status Code Meaning

Status

Code

Meaning

Success

200 (OK)

All Instances were successfully retrieved.

304 (Not Modified)

The user agent's current representation is up to date, so no payload was returned. This status code shall only be returned for a conditional request containing an If-None-Match header field.

Failure

400 (Bad Request)

There was a problem with the request.


8.9.3.1.1 Response Header Fields

Table 8.9.3-2. Response Header Fields

Name

Value

Origin Server Usage

Description

Content-Type

media-type

M

The media-type of the payload

Content-Length

uint

C

Shall be present if a content encoding has not been applied to the payload

Content-Encoding

encoding

C

Shall be present if a content encoding has been applied to the payload


See also Section 8.4.

8.9.3.2 Response Payload

A success response shall have a payload containing a Capabilities Description in the Selected Media Type. The Capabilities Description shall conform to the requirements and structure defined in Annex H.

A failure response payload may contain a Status Report describing any failures, warnings, or other useful information.

8.9.4 Media Types

The media types supported by the Retrieve Capabilities service are application/vnd.sun.wadl+xml (Web Application Description Language) or application/json.

8.10 Notifications

8.10.1 Overview

Some RESTful Services support Notifications.

8.10.2 Conformance

An implementation shall document whether or not it supports notifications in the Conformance Statement. If the service supports notification it shall describe how WebSocket connections are opened.

8.10.3 Transaction Overview

Any service that supports Notifications shall support the following transactions:

Table 8.10.3-1. Notification Sub-System Transactions

Name

Method

Description

Open Notification Connection

GET

The user agent requests that the origin server create a Notification Connection between them.

Send Event Report

N/A

The origin server sends an Event Report to an End-Point


8.10.4 Open Notification Connection Transaction

This transaction creates a connection between the user agent and the origin server over which the origin server can send Event Reports to the user agent.

Note

An origin server might play the role of a user agent when communicating with another origin-server.

The connection uses the WebSocket protocol. The connection can use the same TCP port as the HTTP connection, but they are separate connections.

See [RFC6455] for details of the WebSocket protocol.

8.10.4.1 Request

There is more than one way to establish a WebSocket connection. An origin server that conforms to [RFC6455] will at least support requests to open a WebSocket over an HTTP connection that have the following syntax:

GET SP / SP version CRLF
Host: host CRLF
Upgrade: "WebSocket" CRLF
Connection: "Upgrade" CRLF
Origin: url CRLF
Sec-WebSocket-Key: nonce CRLF
Sec-WebSocket-Protocol: protocols CRLF
Sec-WebSocket-Version: "13" CRLF
*(<header-field> CRLF)
CRLF

The origin server may support other methods of opening a WebSocket connection, which should be included in the Conformance Statement and the Retrieve Capabilities response.

8.10.4.1.1 Target Resources

The Target Resource is an origin server implementing a DICOM RESTful Service.

8.10.4.1.2 Query Parameters

This transaction has no query parameters.

8.10.4.1.3 Request Header Fields

Table 8.10.4-1 shows the Request Header Field usage for opening a WebSocket connection over http/https.

Table 8.10.4-1. Request Header Fields

Name

Value

Usage

Content-Type

media-type

M

Upgrade

"WebSocket"

M

Connection

"Upgrade"

M

Origin

url

M

Sec-WebSocket-Key

accept-key

M

Sec-WebSocket-Protocol

protocols

O

Sec-WebSocket-Version

version

M


For details of the request header field values and other methods of opening a WebSocket connection see [RFC6455].

8.10.4.1.4 Request Payload

The request has no payload.

8.10.4.2 Behavior

When the origin server receives this request, it shall open and maintain a WebSocket connection between itself and the user agent.

If the connection is lost at any point, the user agent can re-establish it by repeating this transaction.

8.10.4.3 Response

The response shall have the following syntax:

version SP status-code SP reason-phrase CRLF
Upgrade: "WebSocket" CRLF
Connection: "Upgrade" CRLF
Sec-WebSocket-Accept: response-key CRLF
Sec-WebSocket-Protocol: protocol CRLF
*(header-field CRLF)
CRLF
8.10.4.3.1 Status Codes

Table 8.10.4-2 shows some common status codes corresponding to this transaction. See also Section 8.5 for additional status codes.

Table 8.10.4-2. Status Code Meaning

Status

Code

Meaning

Success

101 (Switching Protocols)

The protocol was successfully changed to WebSocket.

Failure

400 (Bad Request)

There was a problem with the request.


8.10.4.3.2 Response Header Fields

Table 8.10.4-3. Response Header Fields

Name

Value

Origin Server Usage

Description

Upgrade

"WebSocket"

M

Connection

"Upgrade"

M

Origin

url

M

Sec-WebSocket-Accept

response-key

M

See [RFC6455]

Sec-WebSocket-Protocol

protocol

M

See [RFC6455]


See also Section 8.4.

8.10.4.3.3 Response Payload

The response has no payload.

8.10.5 Send Event Report Transaction

The origin server uses this transaction to notify a user agent of Events.

This transaction sends a notification, containing an Event Report, over an established Notification Connection from an origin server to a user agent. Unlike most transactions, this transaction is initiated by the origin server.

This transaction corresponds to a DIMSE N-EVENT-REPORT action.

Each service may define Events, and the corresponding Event Report messages and their contents, related to its resources.

8.10.5.1 Request

The request shall use the WebSocket Data Frame transmission protocol.

8.10.5.1.1 Request Payload

The data frames shall have an opcode of "%x1" (text).

The data frame payload data shall be a DICOM JSON Dataset containing the Attributes of the Event Report.

Note

  1. The WebSocket protocol does not currently allow content negotiation so it is not possible to support both XML and JSON encoding of Event Report messages.

  2. If the Event Reports are being proxied into DIMSE N-EVENT Reports, a Message ID (0000,0110) must be managed by the proxy.

8.10.5.2 Behavior

The user agent shall accept all Attributes included in any Event Report. No requirements are placed on what the user agent does with this information.

8.10.5.3 Response

None.

8.11 Security and Privacy

It is very likely that DICOM objects contain Protected Health Information. Privacy regulations in the United States (HIPAA), Europe (GDPR), and elsewhere, require that Individually Identifiable Information be kept private. It is the responsibility of those implementing and deploying the DICOM Standard to ensure that applicable regulations for security and privacy are satisfied.

See, for example, [ONC Privacy Security Guide].

The DICOM PS3.10 File Format has security considerations that will apply whenever DICOM PS3.10 File format is used. See Section 7.5 in PS3.10 .

9 URI Service

9.1 Overview

The URI Service, also known as WADO-URI, enables a user agent to retrieve representations of Instances using HTTP.

9.1.1 Resource Descriptions

The URI Service does not define resources in the form of a Target Resource Path, such as {/resource}. The Target URI of each transaction is a reference to the Base URI ("/") and the Target Resource is identified using query parameter values. The resources for the URI Service are instances of Composite Storage SOP Classes defined in PS3.4.

9.1.2 Common Query Parameters

The Query Parameters specified in this Section may be used with either the Retrieve DICOM Instance or Retrieve Rendered Instance transactions, and are applicable to all supported SOP Classes.

9.1.2.1 Mandatory Query Parameters

The origin server shall support Query Parameters as required in Table 9.1.2-1.

The user agent shall supply in the request Query Parameters as required in Table 9.1.2-1.

The Query Parameters may appear in any order.

Table 9.1.2-1. Mandatory Query Parameters

Name

Values

Usage

Section

User Agent

Origin Server

requestType

"WADO"

M

M

Section 9.1.2.1.1

studyUID

uid

M

M

Section 9.1.2.1.3

seriesUID

uid

M

M

Section 9.1.2.1.3

objectUID

uid

M

M

Section 9.1.2.1.4


See Section 8.3.

Note

To identify a SOP Instance, only a SOP Instance UID is required, because any UID is globally unique. However, the Standard requires that the UIDs of the higher levels in the DICOM Information Model (i.e., series and study) are specified, in order to support the use of DICOM devices that support only the baseline hierarchical (rather than extended relational) Query/Retrieve model, which requires the Study Instance UID and Series Instance UID to be defined when retrieving an Instance, as defined in PS3.4.

9.1.2.1.1 Request Type
requestType = %s"requestType=" token
token       = "WADO"

This parameter specifies that this is a URI service request. The parameter name shall be "requestType", and the value shall be "WADO".

If the value is other than "WADO", and the origin server does not support the value, the response shall be 400 (Bad Request), and may include a payload containing an appropriate error message.

9.1.2.1.2 Study UID
study = %s"studyUID=" uid

The value of this parameter is a Study Instance UID.

9.1.2.1.3 Series UID
series = %s"seriesUID=" uid

The value of this parameter is a Series Instance UID.

9.1.2.1.4 Instance UID
instance = %s"objectUID=" uid

The value of this parameter is a SOP Instance UID.

9.1.2.2 Optional Query Parameters

The parameters defined in this section are optional for all URI requests.

Table 9.1.2-2. Optional Query Parameters

Key

Values

Usage

Section

User Agent

Origin Server

contentType

media-type

O

O

Section 8.3.3.1

charset

token

O

O

Section 8.3.3.2


See Section 8.3.

9.1.2.2.1 Acceptable Media Types

The Accept Query Parameter specifies the Acceptable Media Types for the response payload. See Section 8.7.5. The case-sensitive name of the parameter is "contentType". Its syntax is:

accept = %s"contentType=" dicom / 1#rendered-media-type

The value of this parameter, if present, shall be either application/dicom, or one or more of the Rendered Media Types.

The DICOM Media Type transfer-syntax and character set parameters are forbidden in the request. If either are present, the response shall be 400 (Bad Request), and may include a payload containing an appropriate error message.

See Section 8.7.5 for other errors related to this parameter.

Note

URI origin servers may support Transfer Syntax and charset Query Parameters. This is different from the approach used by the DICOM RESTful services, which uses transfer-syntax and charset media type parameters.

9.1.2.2.2 Acceptable Character Sets
charset-qp = %s"charset=" 1#(charset [weight])

The value of this parameter is a comma-separated list of one or more character-set identifiers. See Section 8.8.1.

9.1.3 Common Media Types

The origin server shall support the application/dicom media type as described in Section 8.7.3.1 and Rendered Media Types as described in Section 8.7.4.

Support for the Transfer Syntax and Character Set media type parameters is forbidden for URI Services.

9.2 Conformance

An implementation conforming to the URI service shall support retrieval of one or more of the Information Objects specified for the Storage Service Class, as specified in Section B.5 in PS3.4 .

An implementation's Conformance Statement shall document the Information Objects supported for the URI service, and whether it plays the role of origin server or user agent, or both.

9.3 Transactions Overview

The URI Service has two transactions:

Retrieve DICOM Instance

This transaction retrieves a single Instance in the application/dicom media type.

Retrieve Rendered Instance

This transaction retrieves a single Instance in a Rendered Media Type.

These two transactions have the same "requestType" type but are differentiated by their Selected Media Type.

If there is no "contentType" Query Parameter and the Accept header field is '*/*', then the Selected Media Type defaults to 'image/jpeg' media type and the transaction defaults to Retrieve Rendered Instance.

9.4 Retrieve DICOM Instance Transaction

This transaction retrieves a single Instance in the application/dicom media type. See Section 8.7.3.

9.4.1 Request

The request shall have the following syntax:

GET SP / ?{requestType}&{study}&{series}&{instance}
         {&accept}
         {&charset}
         {&anonymize}
         {&transferSyntax}
         SP HTTP/1.1 CRLF
Accept: uri-media-type CRLF
*(header-field CRLF)
CRLF

9.4.1.1 Target Resource

The Target Resource shall be an Instance of a Composite Storage SOP class defined in PS3.4.

9.4.1.2 Query Parameters

The origin server shall support Query Parameters as required in Table 9.4.1-1 .

The user agent shall supply in the request Query Parameters as required in Table 9.4.1-1 .

Table 9.4.1-1. Optional Query Parameters

Key

Values

Usage

Section

User Agent

Origin Server

anonymize

"yes"

O

O

Section 9.4.1.2.1

annotation

"patient"

"technique"

O

O

Section 9.4.1.2.2

transferSyntax

uid

O

O

Section 9.4.1.2.3


9.4.1.2.1 Anonymize
anonymize = %s"anonymize=" token
token = "yes"

This parameter specifies that the returned representations shall have all Individually Identifiable Information (III) removed, as defined in Annex E “Attribute Confidentiality Profiles (Normative)” in PS3.15 Basic Profile with Clean Pixel Data Option. Its name is "anonymize" and its value is a token. The defined token is "yes". If this parameter is not present, no anonymization is requested.

9.4.1.2.2 Annotation
annotation = 1#( %s"patient" / %s"technique" )

This parameter specifies that the rendered images shall be annotated with patient and/or procedure information. Its value is a comma-separated list of one or more keywords.

Where

"patient"

indicates that the rendered images shall be annotated with patient information (e.g., patient name, birth date, etc.).

"technique"

indicates that the rendered images shall be annotated with information about the procedure that was performed (e.g., image number, study date, image position, etc.).

The origin server may support additional keywords, which should be included in the Conformance Statement and the Retrieve Capabilities response.

9.4.1.2.3 Transfer Syntax
transfer-syntax = %s"transferSyntax" "=" transfer-syntax-uid

This parameter specifies a Transfer Syntax UID. Its name is "transferSyntax" and its value is a single Transfer Syntax UID. It is optional for both the user agent and origin server. See Section 8.7.3.5 for details.

9.4.1.3 Request Header Fields

The origin server shall support header fields as required in Table 9.4.1-2 in the request.

The user agent shall supply in the request header fields as required in Table 9.4.1-2.

Table 9.4.1-2. Request Header Fields

Name

Values

Usage

Description

User Agent

Origin Server

Accept

media-type

O

M

The Acceptable Media Types for the response payload

Accept-Charset

charset

O

M

The Acceptable Character Sets of the response payload


See also Section 8.4.

9.4.1.4 Request Payload

The request has no payload.

9.4.2 Behavior

A success response shall contain the Target Resource in an Acceptable DICOM Media Type. See Section 8.7.5.

9.4.2.1 Request Type

If the Query Parameter is not present; or if it is present with a value other than "WADO" and the origin server does not support the value, then the origin server shall return a 400 (Bad Request) response and may include a payload containing an appropriate error message.

9.4.2.2 Study, Series, and Instance UIDs

If the Study, Series, or Instance UID Query Parameters are not present, the origin server shall return a 400 (Bad Request) response and may include a payload containing an appropriate error message.

9.4.2.3 Anonymize

If the Query Parameter is supported and present, and if any of the following are true:

  • the number of parameter values is not equal to one, or

  • the parameter value is not "yes"

then the origin server shall return a 400 (Bad Request) response and may include a payload containing an appropriate error message.

If the Target Resource has not already been de-identified, the returned Instance shall have a new SOP Instance UID.

If the origin server is either unable or refuses to anonymize the Target Resource, it may return an error response.

9.4.2.4 Transfer Syntax UID

If this Query Parameter is supported and present with a value that is a valid Transfer Syntax UID, the response payload shall be encoded in the specified Transfer Syntax.

If it is not present, the response payload shall be encoded in the default Transfer Syntax for DICOM Web Services, which is Explicit VR Little Endian Uncompressed.

If the Query Parameter is supported and present, and if any of the following are true:

  • the number of parameter values is not equal to one, or

  • the parameter value is not a valid UID

then the origin server shall return a 400 (Bad Request) response and may include a payload containing an appropriate error message.

If the parameter value is a valid Transfer Syntax UID, but is not supported by the origin server, the response shall be 406 (Not Acceptable), and may include a payload containing a list of the Transfer Syntaxes supported by the origin server.

Note

The origin server may not be able to convert all Instances to all the Transfer Syntaxes it supports.

9.4.3 Response

version SP status-code SP reason-phrase
[Content-Type: media-type CRLF]
[(Content-Length: uint / Content-Encoding: encoding) CRLF]
Content-Location: url CRLF
*(header-field CRLF)
CRLF
[payload / status-report]

9.4.3.1 Status Codes

Table 9.4.3-1 shows some common status codes corresponding to this transaction. See also Section 8.5 for additional status codes.

Table 9.4.3-1. Status Code Meaning

Status

Code

Meaning

Success

200 (OK)

The Instance was successfully retrieved.

Failure

400 (Bad Request)

There was a problem with the request.

404 (Not Found)

The resource corresponding to the UIDs in the Query Parameters was not found.

410 (Gone)

The resource corresponding to the UIDs in the Query Parameters, once existed, but no longer exists.


9.4.3.2 Response Header Fields

The origin server shall support header fields as required in Table 9.4.3-2.

Table 9.4.3-2. Response Header Fields

Name

Value

Origin Server Usage

Description

Content-Type

dicom-media-type

M

The media-type of the payload

Content-Length

uint

M

Shall be present if a content encoding has not been applied to the payload

Content-Encoding

encoding

M

Shall be present if a content encoding has been applied to the payload


See Section 8.4.

9.4.3.3 Response Payload

A successful response shall have a payload containing the Target Resource in the application/dicom media type.

A failure response payload may contain a Status Report describing any failures, warnings, or other useful information.

9.5 Retrieve Rendered Instance Transaction

This transaction returns a single Instance in a Rendered Media Type. See Section 8.7.4.

The Acceptable Media Type shall not be application/dicom. If it is, the response should be 406 (Not Acceptable) response.

9.5.1 Request

The request shall have the following syntax:

GET SP /?{requestType}&{study}&{series}&{instance}{&frameNumber}
         {&accept}
         {&charset}
         {&annotation}
         {&rows}
         {&columns}
         {&region}
         {&windowCenter}
         {&windowWidth}
         {&imageQuality}
         {&annotation}
         {&presentationSeriesUID}
         {&presentationUID}
SP HTTP/1.1 CRLF
Accept: 1#media-type CRLF
*(header-field CRLF)
CRLF

9.5.1.1 Target Resource

The Target Resource shall be an Instance of a Composite SOP Class as defined in PS3.3.

9.5.1.2 Query Parameters

The Query Parameters in this section shall only be included in a request if the DICOM Category of the Target Resource is Single Frame, Multi-Frame, or Video as defined in Section 8.7.2.

The origin server shall support Query Parameters as required in Table 9.5.1-1.

The user agent shall supply in the request Query Parameters as required in Table 9.5.1-1.

Table 9.5.1-1. Query Parameters

Key

Values

Usage

Section

User Agent

Origin Server

contentType

rendered-media-type

O

M

Section 9.1.2.2.1

charset

charset

O

M

Section 9.1.2.2.2

frameNumber

uint

O

O

Section 9.5.1.2.1

imageAnnotation

"patient" / "technique"

O

O

Section 9.5.1.2.2

imageQuality

uint

O

O

Section 9.5.1.2.3

rows

uint

O

O

Section 9.5.1.2.4.1

columns

uint

O

O

Section 9.5.1.2.4.2

region

4decimal

O

O

Section 9.5.1.2.5

windowCenter

decimal

O

O

Section 9.5.1.2.6.1

windowWidth

decimal

O

O

Section 9.5.1.2.6.2

presentationSeriesUID

uid

O

O

Section 9.5.1.2.7.1

presentationUID

uid

O

O

Section 9.5.1.2.7.2


9.5.1.2.1 Frame Number
frame-number = %s"frameNumber" "=" uint

This parameter specifies a single frame within a multi-frame image Instance, as defined in PS3.3 that shall be returned. Its name is "frameNumber" and its value shall be a positive integer (i.e., starts at 1 not 0).

9.5.1.2.2 Image Annotation

See Section 8.3.5.1.1.

9.5.1.2.3 Image Quality

See Section 8.3.5.1.2.

9.5.1.2.4 Viewport

The Viewport Query Parameters specify the dimensions of the user agent's viewport. The Viewport Rows and Columns parameters specify the height and width, in pixels, of the returned image. If either parameter is present, both shall be present.

The Viewport parameters syntax in this Section overrides that described in Section 8.3.5.1.3; however, the scaling behavior described in that section still applies.

9.5.1.2.4.1 Viewport Rows
rows = %s"rows" "=" uint

This parameter specifies the number of pixel rows in the returned image. It corresponds to the height in pixels of the user agent's viewport. Its name is "rows" and its value shall be a positive integer.

9.5.1.2.4.2 Viewport Columns
columns = %s"columns" "=" uint

This parameter specifies the number of pixel columns in the returned image. It corresponds to the width, in pixels, of the user agent's viewport. Its name is "columns" and its value shall be a positive integer.

9.5.1.2.5 Source Image Region
region = %s"region" "=" xmin "," ymin "," xmax "," ymax
xmin = decimal
ymin = decimal
xmax = decimal
ymax = decimal

This parameter specifies a rectangular region of the Target Resource. Its name is "region" and its values shall be a comma-separated list of four positive decimal numbers:

xmin

the left column of the region

ymin

the top row of the region

xmax

the right column of the region

ymax

the bottom row of the region

The region is specified using a normalized coordinate system relative to the size of the original image matrix, measured in rows and columns. Where

  • 0.0, 0.0 corresponds to the top row and left column of the image

  • 1.0, 1.0 corresponds to the bottom row and right column of the image

and

  • 0.0 <= xmin < xmax <= 1.0

  • 0.0 <= ymin < ymax <= 1.0

This parameter when used in conjunction with one of the viewport parameters, allows the user agent to map a selected area of the source image into its viewport.

9.5.1.2.6 Windowing

The Windowing parameters (Window Center and Window Width) are optional; however, if either is present, both shall be present. If only one is present the origin server shall return a 400 (Bad Request) response and may include a payload containing an appropriate error message.

The URI Service does not support the "function" Query Parameter, which is described in Section 8.3.5.1.4.

The Windowing and Presentation State parameters shall not be present in the same request. If both are present the origin server shall return a 400 (Bad Request) response and may include a payload containing an appropriate error message.

The Windowing parameters shall not be present if contentType is application/dicom; if either is present the origin server shall return a 400 (Bad Request) response and may include a payload containing an appropriate error message.

9.5.1.2.6.1 Window Center
window-center = %s"windowCenter" "=" decimal

This parameter specifies the Window Center of the returned image as defined in PS3.3. Its name is "windowCenter" and its value shall be a decimal number.

9.5.1.2.6.2 Window Width
window-width = %s"windowWidth" "=" decimal

This parameter specifies the Window Width of the returned image as defined in PS3.3. Its name is "windowWidth" and its value shall be a decimal number.

9.5.1.2.7 Presentation State

The parameters below specify the Series and SOP Instance UIDs of a Presentation State. They are optional. However, if one is present, they shall both be present.

If the Presentation State parameters are present, then the only other optional parameters that may be present are Annotation, Image Quality, Region, and Viewport.

9.5.1.2.7.1 Presentation Series UID
presentation-series = %s"presentationSeriesUID" "=" uid

This parameter specifies the Series containing the Presentation State Instance to be used to render the image. Its name shall be "presentationSeriesUID" and its value shall be a Series Instance UID.

9.5.1.2.7.2 Presentation UID
presentation-instance = %s"presentationUID" "=" uid

This parameter identifies the Presentation State Instance, which is used to render the image. Its name is "presentationUID" and its value shall be a Presentation State Instance UID of a Presentation State Instance.

9.5.1.3 Request Header Fields

The origin server shall support header fields as required in Table 9.5.1-2.

The user agent shall supply in the request header fields as required in Table 9.5.1-2.

Table 9.5.1-2. Request Header Fields

Name

Values

Usage

Description

User Agent

Origin Server

Accept

media-type

M

M

The Acceptable Media Types for the response payload

Accept-Charset

charset

O

M

List of one or more character sets


The Acceptable Media Types shall contain only Rendered Media Types. See Section 8.7.4.

9.5.1.4 Request Payload

The request message has no payload.

9.5.2 Behavior

A success response shall contain the Target Resource in an Acceptable Rendered Media Type. See Section 8.7.4.

The Target Resource shall be rendered and returned as specified in the Query Parameters. Presentation State transformations are applied using the appropriate rendering pipeline specified in Section N.2 “Pixel Transformation Sequence” in PS3.4. Any Source Image Region parameters are applied after any Presentation State parameters. Any Viewport parameters are applied after any Source Image Region.

Even if the output of the image is defined in P-Values (grayscale values intended for display on a device calibrated to the DICOM Grayscale Standard Display Function PS3.14), or contains an ICC profile, the grayscale or color space for the rendered image is not defined by this Standard.

9.5.2.1 Frame Number

If this Query Parameter is supported and is present in the request,the origin server shall use the specified frame as the Target Resource.

However, if any of the following are true:

  • the Target Resource is not a multi-frame image or video,

  • the number of parameter values is not equal to one, or

  • the parameter value is not a positive integer less than or equal to the number of frames in the Instance

the origin server shall return a 400 (Bad Request) responseand may include a payload containing an appropriate error message.

9.5.2.2 Windowing

If these Query Parameters are supported and are present in the request, the origin server shall use them as described in Section 8.3.5.1.4.

However, if any of the following are true:

  • only one of the parameters is present,

  • either of the parameter values is not a decimal number, or

  • the Presentation Series UID or the Presentation UID Query Parameters are present

then the origin server shall return a 400 (Bad Request) response and may include a payload containing an appropriate error message.

9.5.2.3 Presentation State

If the Target Resource is a Presentation State and If the Presentation Size Mode is SCALE TO FIT or TRUE SIZE, then the displayed area specified in the Presentation State shall be scaled, maintaining the aspect ratio, to fit the size specified by the rows and columns parameters if present, otherwise the displayed area selected in the presentation state will be returned without scaling.

Note

  1. The intent of the TRUE SIZE mode in the presentation state cannot be satisfied, since the physical size of the pixels displayed by the web browser is unlikely to be known. If the Presentation Size Mode in the presentation state is MAGNIFY, then the displayed area specified in the presentation shall be magnified (scaled) as specified in the presentation state. It will then be cropped to fit the size specified by the viewport parameters, if present.

  2. Any Displayed Area relative annotations specified in the presentation state are rendered relative to the Specified Displayed Area within the presentation state, not the size of the returned image.

Though the output of the presentation state is defined in DICOM to be in P-Values (grayscale values intended for display on a device calibrated to the DICOM Grayscale Standard Display Function PS3.14), the grayscale or color space for the images returned by the request is not defined by this standard.

However, if any of the following are true:

  • the Frame Number, or Windowing parameters are present,

  • the Presentation Series UID does not correspond to an existing Presentation Series on the origin server, or

  • the Presentation UID does not correspond to an existing Presentation Instance on the origin server

the origin server shall return a 400 (Bad Request) response and may include a payload containing an appropriate error message.

9.5.2.4 Source Image Region

If this Query Parameter is supported and present:

  • An image matrix corresponding to the region specified by Source Image Region shall be returned with its size corresponding to the specified normalized coordinate values.

  • If the Presentation UID parameter is present, the region shall be selected after the corresponding presentation state has been applied on the images.

However, if any of the following are true:

  • the Query Parameter specifies an ill-defined region,

  • there are greater or fewer than four parameter values present, or

  • any of the parameters do not conform to the requirements specified in Section 9.5.1.2.5

the origin server shall return a 400 (Bad Request) response and may include a payload containing an appropriate error message.

9.5.2.5 Viewport

Viewport parameters are applied to the region specified by the Presentation State and/or Source Image Region, if present; otherwise, the Viewport Query Parameters are applied to the full original image.

If both rows and columns Query Parameters are specified, then each shall be interpreted as a maximum, and a size will be chosen for the returned image within these constraints, maintaining the aspect ratio of the selected region.

If the rows Query Parameter is absent and the columns Query Parameter is present, the number of rows in the returned image shall be chosen to maintain the aspect ratio of the selected region.

If the columns Query Parameter is absent and the rows Query Parameter is present, the number of columns in the returned image shall be chosen to maintain the aspect ratio of the selected region.

If both Query Parameters are absent, the image (or selected region) is returned with its original size (or the size of the presentation state applied to the image), resulting in one pixel in the returned image for each pixel in the original image.

9.5.3 Response

version SP status-code SP reason-phrase
[Content-Type: rendered-media-type CRLF]
[(Content-Length: uint / Content-Encoding: encoding) CRLF]
[Content-Location: url CRLF]
*(header-field CRLF)
CRLF
[payload / status-report]

9.5.3.1 Status Codes

Table 9.5.3-1 shows some common status codes corresponding to this transaction. See also Section 8.5 for additional status codes.

Table 9.5.3-1. Status Code Meaning

Status

Code

Meaning

Success

200 (OK)

All Instances were successfully rendered and retrieved.

Failure

400 (Bad Request)

There was a problem with the request.


9.5.3.2 Response Header Fields

The origin server shall support header fields as required in Table 9.5.3-2.

Table 9.5.3-2. Response Header Fields

Name

Value

Origin Server Usage

Description

Content-Type

media-type

C

Shall be present if the response contains a payload. See Section 8.4.3.

Content-Encoding

encoding

C

Shall be present if the response payload has a content encoding. See Section 8.4.3.

Content-Length

uint

C

Shall be present if the response payload does not have a content encoding. See Section 8.4.3.

Content-Location

url

C

Shall be present if the response has a payload containing a resource. See Section 8.4.3.


See also Section 8.4.

9.5.3.3 Response Payload

A success response shall contain a single rendered image encoded in the Selected Media Type.

A failure response payload may contain a Status Report describing any failures, warnings, or other useful information.

10 Studies Service and Resources

10.1 Overview

The Studies Resource enables a user agent to store, retrieve, update, and search an origin server for DICOM Studies, Series, and Instances, along with their /metadata, /rendered, and /thumbnail variants; as well as Frames and Bulkdata.

The Retrieve transaction of this Service is also known as WADO-RS. The Store transaction of this Service is also known as STOW-RS. The Search transaction of this Service is also known as QIDO-RS. See Section 10.3.