DICOM PS3.18 2015x4c - Web ServicesDICOMweb Page

Supplement 183: Part 18 Re-Documentation

Editor: Jim PhilbinVersion: 0.2

Date: 13 January 2015TODO:

1. All message templates should use ABNF except target URI should be URI template2. DICOM Media Type Annex 3. Rendered Media Type Annex4. Other Media Types Annex5. Verify Status Code Sections are similarly formatted

a. Success responsei. Most common success codes

b. Error responsei. Most common success codes

c. all status code tables should have the same formatd. all status code sections should reference the larger status table in either 6.2 or 9.2 or both

6. Add Media Type Table or References to all media type sectionsa. Make sure there are references to the appropriate Section or Annex b. Make sure the Annexes are in the form of a Media Type registration followed by format details

7. Make sure all resource sections in chapters 7, 9, 10 - 12 have the same format including tables.8. Make sure all URI Templates are correct (Whitby help)9. Update Open / Closed issues10. Update Section 3 with all references in Part 1811. Update Section 412. Update Section 513. Have Larry Tarbox review chapter 8.

a. Add WS Retrieve Rendered Presentation State transaction to chapter 9.b. Make sure bullets and numbering are correct.

14. Verify that all sections that should be structurally equivalent are.

TODO final

1. Finish all TODOs in document2. Add links to all references in document (most are highlighted in yellow)3. Make sure all section, table, and figure numbering is correct.

Correction CPs Needed1. Add media type application/dicom+json

a. Change the application/dicom+json encoding to have “Value” goes to “value” in tag structure.2. Adding Status Details to Error or Warning response payloads3. Media Type text/xml is required for all three protocols.4.

Closed General Issues# Issues

-- Draft:20140113 V0.44 ---

5

10

15

20

25

30

35

40

DICOM PS3.18 2015x - Web Services Page

Open General Issues# Issues Status

Can a rendered presentation state be rendered in a different media type than its transfer syntax?Yes, but only if the origin server supports the media type.You get what you get.Transfer syntax should not be specified in the rendered media types.

Closed

Should Error responses payloads require a Status Details payload? Leaning toward Yes for RS – No for URI, WS.

Needs a CP.

Editorial Questions# Issues Status

What is the proper way to refer to Part 18 of the DICOM Standard? The DICOMweb Standard? This Part of the Standard? PS3.18? All three?Decision: PS3.18What is the best way to handle status codes sections?Proposal: Only include the most relevant status codes for the particular transaction and a reference to the general status code section.How should we handle hyperlinks?

Include the reference and hyperlink it? Just add a hyperlink to the word or phrase

Decision: Include the reference in a hyperlink.

Closed

Should we define suggested or required DICOM reason phrases?Should hyperlinks point to our References section or to the standard itself?Proposal: They should point to the referenced standard, i.e. RFC xxx

Editorial Decisions# Issues Status

Since URI template varspecs are case insensitive all template variable are lowercase with word separated by ‘_’Yes.

- Draft -

45

DICOM PS3.18 2015x - Web Services Page

{attributeID} -> {attribute}, because templates are case insensitive. ClosedClosed

Should “user agent” and “Origin server” be lowercase without the hyphen, i.e. “user agent” and “origin server”? Yes, That is the way they are written in the standard.

Closed

“Bulkdata” or “Bulk Data”: leaning toward “Bulkdata”, which denotes a DICOM object, whereas, “Bulk Data” is generic large data.Decision: Bulkdata.

Closed

Should we replace {+svc} with “/” (the relative URL that is the root of the service?Yes. This makes it simpler, shorter, and clearer

Closed

Editor’s Notes1. Terminology and StructureThroughout this document I have endeavored to use the following terminology to structure the document:

Protocol A protocol defines a set of related services and resources, typically on top of a technology framework, such as WS* web services or Restful web services.

Service A service defines a set of related transactions on a resource or resource group

Transaction A transaction is a request/response message pair using a specific HTTP method on a resource or resource group

Resource A resource is an concept that refers to a thing. The thing might be abstract like an idea. In the DICOMweb Standard it typically refers to a DICOM Information Object. Resources can more than one representation.

Resource Group A collection of related resources.

Target Resource A target resource is the resource that is the focus of the transaction. It is referenced by a target URI in the request message of a transaction.

Target URI The URI in the first line of a request message. It references the target resource.

Representation A data format that contains an encoding of a resource. The format of a representation is identified by it media type.

Media Type The name, possibly parameterized, of a specific encoding of a representation.

2. Document Structurea. 3 Protocols: URI, WS, RS

b. URI has one service, Retrieve, with three Transactions:

1. DICOM Instance2. Rendered Instance3. Rendered Presentation State Instance

c. WS has one service, Retrieve, with four transactions

1. Document Set2. Rendered Document Set3. Rendered Presentation State

- Draft -

50

55

60

65

70

75

DICOM PS3.18 2015x - Web Services Page

4. Document Set Metadata

d. RS protocol has two services:

1. The Storage service which has X transactions:a. Retrieve DICOMb. Retrieve Rendered c. Retrieve Rendered Presentation Statesd. Store DICOMe. Searchf. Capabilities

2. The Worklist service has 12 transactionsa. Create Work Itemb. Retrieve Work Itemc. Update Work Itemd. Change Work Item Statee. Request Work Item Cancellationf. Search for Work Itemg. Create Subscriptionh. Delete Subscriptioni. Open Event Channelj. Close Event Channelk. Send Event Reportl. Capabilities

**** All Content Above this line is editorial and should be deleted before Final Text****

- Draft -

80

85

90

95

100

DICOM PS3.18 2015x - Web Services Page

PS3.18DICOM PS3.18 2015x – Web Services

- Draft -

105

DICOM PS3.18 2015x - Web Services Page

PS3.18: DICOM PS3.18 2015x – DICOMwebCopyright 2015 NEMA

- Draft -

DICOM PS3.18 2015x - Web Services Page

Contents1 Scope 192 Conformance 203 Normative References 224 Terms and Definitions 23

4.1 DICOM Terms 234.2 DICOMweb Terms and Definitions 234.3 HTTP Terms and Definitions 244.4 Other Terms 26

5 Symbols and Abbreviated Terms 276 DICOMweb Overview 28

6.1 DICOMweb Protocols, Services, and Transactions 286.2 DICOMweb Uses HTTP (Informative) 296.3 Resources 296.4 DICOMweb Transactions 30

6.4.1 Message Syntax 306.4.1.1 Target Resource Syntax 306.4.1.2 Target Resource Syntax 306.4.1.3 SOP Instances 306.4.1.4 Metadata, and Bulkdata Resources 306.4.1.5 Studies and Series Resources 31

6.4.2 DICOMweb Message Format Syntax 316.4.2.1 Standard Syntax Variable Names 316.4.2.2 Standard URI Template Variable Names 32

6.4.3 Request Message Format 326.4.3.1 Methods 326.4.3.2 Target Resources 346.4.3.3 Query Parameters (Normative) 34

6.4.3.3.1 Syntax of Query Parameters 346.4.3.3.2 Query Parameter Specifications 35

6.4.3.4 Request Header Fields (Informative) 366.4.3.4.1 Content Negotiation Header Fields 366.4.3.4.2 Content Representation 376.4.3.4.3 Transfer Syntax Parameters for Content Negotiation and -Representation Header Fields 38

6.4.3.5 Request Payload 386.4.4 Behavior 386.4.5 Response Message Format 38

6.4.5.1 Status Codes (Informative) 396.4.5.2 Response Header Fields 436.4.5.3 Response Payload 43

6.4.5.3.1 Status Details Payload for Responses with Issues 436.4.6 Payloads 44

6.4.6.1 Payload Header Fields 446.4.6.2 Payload Format 44

6.4.6.2.1 Single Part Payload 446.4.6.2.2 Multi-Part Payload 44

6.4.7 Representations and Media Types 466.4.7.1 Representation Categories 46

- Draft -

110

115

120

125

130

135

140

145

150

155

DICOM PS3.18 2015x - Web Services Page

6.4.7.2 Media Type Syntax 476.5 Security 486.6 DICOMweb Service Descriptions 48

7 URI Protocol (WADO-URI) 497.1 URI Service 50

7.1.1 Request 507.1.1.1 Object Identification Parameters 51

7.1.1.1.1 Request Type 517.1.1.1.2 Unique Identifier of the Study 517.1.1.1.3 Unique Identifier of the Series 517.1.1.1.4 Unique Identifier of the Instance 52

7.1.1.2 Other Query Parameters 527.1.1.2.1 Unique Identifier of the Presentation Series 527.1.1.2.2 Unique Identifier of the Presentation Object 527.1.1.2.3 MIME Type of the Response (Retired) 527.1.1.2.4 Transfer Syntax UID (Retired) 527.1.1.2.5 Charset of the Response (Retired) 52

7.1.1.3 Header Fields 527.1.1.4 Request Payload 52

7.1.2 Behavior 527.1.3 Response 52

7.1.3.1 Status Codes 537.1.3.2 Header Fields 537.1.3.3 Payload 53

7.1.4 Media Types 537.1.4.1 Acceptable Media Type 54

7.2 Retrieve DICOM Instance Transaction 547.2.1 Request 54

7.2.1.1 Resource 547.2.1.2 Query Parameters 54

7.2.1.2.1 Anonymize 547.2.1.3 Header Fields 557.2.1.4 Payload 55

7.2.2 Behavior 557.2.3 Response 55

7.2.3.1 Status Codes 557.2.3.2 Header Fields 557.2.3.3 Payload 55

7.2.4 Media Type 557.3 URI Retrieve Rendered Instance Transaction 56

7.3.1 Request 567.3.1.1 Target Resource 567.3.1.2 Query Parameters 56

7.3.1.2.1 Annotation on the Object 577.3.1.2.2 Frame Number 577.3.1.2.3 Image Quality 577.3.1.2.4 Pixel Rows in Rendered Image 577.3.1.2.5 Pixel Columns in Rendered Image 577.3.1.2.6 Region of Target Resource 577.3.1.2.7 Window Center of the Rendered Image 58

- Draft -

160

165

170

175

180

185

190

195

200

205

DICOM PS3.18 2015x - Web Services Page

7.3.1.2.8 Window Width of the Rendered Image 587.3.1.3 Header Fields 587.3.1.4 Payload 58

7.3.2 Behavior 587.3.3 Response 58

7.3.3.1 Status Codes 597.3.3.2 Header Fields 597.3.3.3 Payload 59

7.3.4 Media Types 597.4 URI Retrieve Rendered Presentation State Transaction 59

7.4.1 Request 597.4.1.1 Query Parameters 59

7.4.1.1.1 Pixel Rows in Rendered Image 607.4.1.1.2 Pixel Columns in Rendered Image 607.4.1.1.3 Image Annotation 607.4.1.1.4 Image Quality 60

7.4.1.2 Header Fields 607.4.1.3 Payload 60

7.4.2 Behavior 607.4.3 Response 61

7.4.3.1 Status Code 617.4.3.2 Header Fields 617.4.3.3 Payload 61

8 WS* Web Services Protocol (WS) 618.1 Transactions 62

8.1.1 Acceptable Media Type 638.2 Retrieve Imaging Document Set 63

8.2.1 Request 638.2.2 Response 64

8.2.2.1 Form of the Response 648.2.2.2 JPIP 66

8.3 Retrieve Rendered Imaging Document Set 668.3.1 Request 66

8.3.1.1 Parameters 678.3.1.1.1 Pixel Rows in Rendered Image 688.3.1.1.2 Pixel Columns in Rendered Image 688.3.1.1.3 Region Rendered 688.3.1.1.4 Window Center of the Rendered Image 698.3.1.1.5 Window Width of the Rendered Image 698.3.1.1.6 Frame Number 698.3.1.1.7 Image Quality 69

8.3.2 Response 698.4 Retrieve Rendered Presentation State Request 718.5 Retrieve Imaging Document Set Metadata Request 718.5.1 Request 718.5.2 Response 72

8.6 WS Media Types 748.7 Error Codes 74

9 Restful Web Services Protocol (RS) 759.1 RS Services Overview 769.2 Target Resources 77

- Draft -

210

215

220

225

230

235

240

245

250

255

DICOM PS3.18 2015x - Web Services Page

9.3 Transaction Overview 779.3.1 Request Message Format 77

9.3.1.1 Resources 789.3.1.2 Query Parameters 789.3.1.3 Header Fields 789.3.1.4 Payload 78

9.3.2 Behavior 789.3.3 Response 78

9.3.3.1 Status Codes 789.3.3.2 Header Fields 80

9.3.4 Response Payload 819.3.5 Payload 819.3.6 RS Media Types 81

9.3.6.1 Acceptable Media Type 829.3.6.2 Multipart Related Media Type 829.3.6.3 Imaging Media Types and Transfer Syntax 82

9.4 Retrieve Capabilities Transaction 839.4.1 Request 83

9.4.1.1 Resources 839.4.1.2 Query Parameters 839.4.1.3 Header Fields 839.4.1.4 Payload 83

9.4.2 Behavior 839.4.3 Response 83

9.4.3.1 Status Codes 849.4.3.2 Header Fields 849.4.3.3 Payload 84

9.4.4 Media Types 849.5 Notification Subservice 84

9.5.1 Deletion Locks 849.5.2 Filters 849.5.3 Resources 84

9.5.3.1 Service Events 859.5.4 Transactions 859.5.5 Open Event Channel Transaction 85

9.5.5.1 Request 859.5.5.1.1 Query Parameters 859.5.5.1.2 Header Fields 869.5.5.1.3 Payload 86

9.5.5.2 Behavior 869.5.5.3 Response 86

9.5.5.3.1 Status Codes 869.5.5.3.2 Header Fields 869.5.5.3.3 Payload 87

9.5.5.4 Media Types 879.5.6 Send Event Report Transaction 87

9.5.6.1 Request 879.5.6.1.1 Payload 87

9.5.6.2 Behavior 879.5.6.3 Response 87

9.5.7 Create Subscription Transaction 87

- Draft -

260

265

270

275

280

285

290

295

300

305

DICOM PS3.18 2015x - Web Services Page

9.5.7.1 Request 889.5.7.1.1 Header Fields 889.5.7.1.2 Payload 88

9.5.7.2 Behavior 889.5.7.3 Response 88

9.5.7.3.1 Status Codes 899.5.7.3.2 Header Fields 899.5.7.3.3 Payload 89

9.5.7.4 Media Types 899.5.8 Delete Subscription 89

9.5.8.1 Request 899.5.8.1.1 Query Parameters 899.5.8.1.2 Header Fields 899.5.8.1.3 Payload 90

9.5.8.2 Behavior 909.5.8.3 Response 90

9.5.8.3.1 Status Codes 909.5.8.3.2 Header Fields 90

9.5.8.4 Payload 909.5.9 Media Types 90

10 Restful Studies Service 9010.1 Resources 9110.2 Transactions 9310.3 Retrieve DICOM Transaction 94

10.3.1 Request 9410.3.1.1 Resources 9410.3.1.2 Query Parameters 95

10.3.1.2.1 De-Identification 9510.3.1.3 Header Fields 9510.3.1.4 Payload 95

10.3.2 Behavior 9510.3.3 Response 95

10.3.3.1 Status Codes 9510.3.3.2 Header Fields 9610.3.3.3 Payload 96

10.3.4 Media Types 9610.4 RS Retrieve Rendered Transaction 102

10.4.1 Request 10210.4.1.1 Target Resources 10210.4.1.2 Query Parameters 102

10.4.1.2.1 Annotation on the Image 10310.4.1.2.2 De-Identification 10410.4.1.2.3 Flip Image 10410.4.1.2.4 Order of Rendered Images 10410.4.1.2.5 Quality of the Image 10510.4.1.2.6 Region of the Image 10510.4.1.2.7 Rotate the Image 10510.4.1.2.8 Window Level Image 10510.4.1.2.9 View Port on the User Agent 106

- Draft -

310

315

320

325

330

335

340

345

350

355

DICOM PS3.18 2015x - Web Services Page

10.4.1.3 Header Fields 10610.4.1.4 Payload 106

10.4.2 Behavior 10610.4.3 Response 106

10.4.3.1 Status Codes 10610.4.3.2 Header Fields 10710.4.3.3 Payload 107

10.4.4 Media Types 10710.5 Retrieve Rendered Presentation States Instance Transaction 107

10.5.1 Request 10710.5.1.1 Target Resource 10710.5.1.2 Query Parameters 107

10.5.1.2.1 Annotations on the Image 10810.5.1.2.2 De-Identification 10810.5.1.2.3 Volume of Interest Lookup Table (VOI LUT) 10810.5.1.2.4 Quality of the Image 10810.5.1.2.5 View Port on the User Agent 108

10.5.1.3 Header Fields 10810.5.1.4 Payload 108

10.5.2 Behavior 10810.5.3 Response 109

10.5.3.1 Status Codes 10910.5.3.2 Header Fields 10910.5.3.3 Payload 109

10.5.4 Media Types 10910.6 Store Service 109

10.6.1 Request 11010.6.1.1 Resources 11010.6.1.2 Query Parameters 11010.6.1.3 Header Fields 11010.6.1.4 Payload 110

10.6.2 Behavior 11110.6.3 Response 111

10.6.3.1 Status Codes 11110.6.3.2 Header Fields 11210.6.3.3 Payload 112

10.6.3.3.1 Failure Reason 11310.6.3.3.2 Warning Reason 114

10.6.4 Media Types 11410.7 Search Transaction 115

10.7.1 Request 11510.7.1.1 Resources 11510.7.1.2 Search Query Parameters 115

10.7.1.2.1 Encoding Rules for {attribute} and {value} 11710.7.1.2.2 ABNF Grammar for Search Query Parameters 11710.7.1.2.3 Fuzzy Matching 11810.7.1.2.4 Offset, Limit and Number of Results Returned 118

10.7.1.3 Header Fields 11810.7.1.4 Payload 118

10.7.2 Behavior 118

- Draft -

360

365

370

375

380

385

390

395

400

405

DICOM PS3.18 2015x - Web Services Page

10.7.2.1 Matching 11810.7.2.1.1 Required Query Parameters 11810.7.2.1.2 Fuzzy Matching 119

10.7.2.2 Pagination using Offset and Limit 11910.7.3 Response 120

10.7.3.1 Status Codes 12010.7.3.2 Header Fields 12010.7.3.3 Payload 120

10.7.3.3.1 Response Payload of Search for Study 12010.7.3.3.2 Response Payload of Search for Series 12110.7.3.3.3 Response Payload of Search for Instance 122

10.7.4 Media Types 12311 Retrieve Capabilities Transaction 123

11.1.1 WADL Document Format 12311.1.1.1 Methods 124

11.1.1.1.1 Retrieve Methods 12411.1.1.1.2 Store Methods 12511.1.1.1.3 Search Methods 12611.1.1.1.4 Update Methods 12811.1.1.1.5 Subscribe Methods 128

12 Unified Workflow and Procedure Step (UPS Worklist) Service 12912.1 Overview 130

12.1.1 Transactions 13012.1.2 UPS Requests Overview 131

12.1.2.1 Resources 13212.1.2.2 Query Parameters 13212.1.2.3 Header Fields 13212.1.2.4 Payload 132

12.1.3 Behavior Overview 13212.1.4 Response Overview 133

12.1.4.1 Status Codes 13312.1.5 Media Types 133

12.2 Basic Transactions 13312.2.1 Create Work Item Transaction 133

12.2.1.1 Request 13312.2.1.2 Resources 13412.2.1.3 Query Parameters 13412.2.1.4 Header Fields 13412.2.1.5 Payload 13412.2.1.6 Behavior 13412.2.1.7 Response 13412.2.1.8 Status Codes 13412.2.1.9 Header Fields 13412.2.1.10 Payload 135

12.2.2 Retrieve Work Item 13512.2.2.1 Request 13512.2.2.2 Header Fields 13512.2.2.3 Payload 13512.2.2.4 Behavior 13512.2.2.5 Response 135

- Draft -

410

415

420

425

430

435

440

445

450

455

DICOM PS3.18 2015x - Web Services Page

12.2.2.6 Status Codes 13612.2.2.7 Header Fields 13612.2.2.8 Payload 13612.2.2.9 Media Types 136

12.2.3 Update Work Item Transaction 13612.2.3.1 Request 13612.2.3.2 Query Parameters 13612.2.3.3 Header Fields 13712.2.3.4 Payload 13712.2.3.5 Behavior 13712.2.3.6 Response 13712.2.3.7 Status Codes 13712.2.3.8 Header Fields 13712.2.3.9 Payload 137

12.2.4 Change Work Item State Transaction 13712.2.4.1 Request 13712.2.4.2 Header Fields 13812.2.4.3 Payload 13812.2.4.4 Behavior 13812.2.4.5 Response 13812.2.4.6 Status Codes 13812.2.4.7 Header Fields 13812.2.4.8 Payload 13912.2.4.9 Media Types 139

12.2.5 Request Cancellation 13912.2.5.1 Request 13912.2.5.2 Header Fields 13912.2.5.3 Payload 13912.2.5.4 Behavior 13912.2.5.5 Response 13912.2.5.6 Status Codes 14012.2.5.7 Header Fields 14012.2.5.8 Payload 14012.2.5.9 Media Types 140

12.2.6 Search for Work Items Transaction 14012.2.6.1 Request 14012.2.6.2 Query Parameters 14012.2.6.3 Header Fields 14112.2.6.4 Payload 14112.2.6.5 Behavior 14112.2.6.6 Response 14112.2.6.7 Status Codes 14112.2.6.8 Header Fields 14112.2.6.9 Payload 14212.2.6.10 Media Types 142

12.3 Subscriptions 14212.3.1 Deletion Locks 14212.3.2 Filters 14212.3.3 Resources 142

- Draft -

460

465

470

475

480

485

490

495

500

505

DICOM PS3.18 2015x - Web Services Page

12.3.4 Create Subscription Transaction 14312.3.4.1 Request 14312.3.4.2 Header Fields 14412.3.4.3 Payload 14412.3.4.4 Behavior 14412.3.4.5 Response 14412.3.4.6 Status Codes 14412.3.4.7 Header Fields 14512.3.4.8 Payload 14512.3.4.9 Media Types 145

12.3.5 Delete Subscription 14512.3.5.1 Request 14512.3.5.2 Header Fields 14612.3.5.3 Payload 14612.3.5.4 Behavior 14612.3.5.5 Response 14612.3.5.6 Status Codes 14612.3.5.7 Header Fields 14612.3.5.8 Payload 14612.3.5.9 Media Types 146

12.3.6 Open Event Channel Transaction 14712.3.6.1 Request 14712.3.6.2 Header Fields 14712.3.6.3 Payload 14712.3.6.4 Behavior 14812.3.6.5 Response 14812.3.6.6 Status Codes 14812.3.6.7 Header Fields 14812.3.6.8 Payload 14812.3.6.9 Media Types 148

12.3.7 Send Event Report 14912.3.7.1 Request 14912.3.7.2 Payload 14912.3.7.3 Behavior 14912.3.7.4 Response 149

Annex A DICOM Media Types 149A.1 application/dicom 150A.1 application/dicom+json, application/json 150

12.3.7.5 JSON Search Results 150A.1.1 application/dicom+xml 150

12.3.7.6 XML Search Results 15012.3.8 XML Status Details Document 151

12.3.8.1 Status Details Example 151Annex B Rendered Media Types 152Annex C Other Media Types 152C.1 WADL Document Format - application/vnd.sun.wadl+xml 152C.1.1 IANA Registration 152C.1.2 Definition 153

12.3.8.2 Methods 154

- Draft -

510

515

520

525

530

535

540

545

550

555

DICOM PS3.18 2015x - Web Services Page

12.3.8.2.1 Retrieve Methods 15412.3.8.2.2 Store Methods 15512.3.8.2.3 Search Methods 15612.3.8.2.4 Update Methods 15712.3.8.2.5 Subscribe Methods 158

Annex D Status Details 159Annex E HTTP Status Codes (Informative) 160Annex F DICOM Media Types 161F.1 application/dicom 161F.2 application/dicom+xml 162F.3 Application/dicom+json or application/json 162F.4 application/dicom+bulkdata 162

- Draft -

560

565

570

DICOM PS3.18 2015x - Web Services Page

Notice and DisclaimerThe 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.

- Draft -

575

580

585

590

595

DICOM PS3.18 2014c - Web Services Page

ForewordThis 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 [Ref Biblio ISO Directives]...

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

.

- Draft -

600

DICOM PS3.18 2014c - Web Services Page

1 ScopeThis standard specifies web-based protocols, based on HTTP/HTTPS, for transmitting and receiving DICOM (Digital Imaging and Communications in Medicine) resources (e.g., images, medical imaging reports). It is intended to be used for distribution medical imaging related information. It provides simple mechanisms for creating, retrieving, updating, deleting, and searching for DICOM resources. Data may be transmitted in native DICOM representations or in “rendered” representations (e.g., JPEG or GIF). This standard relates only to composite DICOM objects (not to other DICOM objects). Authentication, authorization and auditing security mechanisms are outside the scope of this standard.

- Draft -

605

2 ConformanceSystems claiming conformance to this standard shall function in accordance with all its mandatory sections.

610

3 Normative ReferencesThe 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.

ebRS ebXML Registry Service

HL7 CDA Health Level Seven, Clinical Document Architecture (CDA)

IETF RFC 822 Standard for ARPA Internet Text Messages http://tools.ietf.org/html/rfc822

IETF RFC 2045 and followings MIME Multipurpose Internet Mail Extension http://tools.ietf.org/html/rfc2045

IETF RFC 3240 Application/dicom MIME Sub-type Registration http://tools.ietf.org/html/rfc3240

IETF RFC 3986 Uniform Resource Identifiers (URI): Generic Syntax http://tools.ietf.org/html/rfc3986

IETF RFC 4627 The application/json Media Type for JavaScript Object Notation (JSON) http://tools.ietf.org/html/rfc4627

IETF RFC 6455 The WebSocket Protocol http://tools.ietf.org/html/rfc6455

IETF RFC 6570 URI Template http://tools.ietf.org/html/rfc6570

IETF RFC 7230 Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing http://tools.ietf.org/html/rfc7230

IETF RFC 7231 Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content http://tools.ietf.org/html/rfc7231

IETF RFC 7232 Hypertext Transfer Protocol (HTTP/1.1): Conditional Requests http://tools.ietf.org/html/rfc7232

IETF RFC 7233 Hypertext Transfer Protocol (HTTP/1.1): Range Requests http://tools.ietf.org/html/rfc7233

IETF RFC 7234 Hypertext Transfer Protocol (HTTP/1.1): Caching http://tools.ietf.org/html/rfc7234

IETF RFC 7235 Hypertext Transfer Protocol (HTTP/1.1): Authentication http://tools.ietf.org/html/rfc7235

IETF RFC 7236 Initial Hypertext Transfer Protocol (HTTP) Authentication Scheme Registrations http://tools.ietf.org/html/rfc7236

IETF RFC 7237 Initial Hypertext Transfer Protocol (HTTP) Method Registrations http://tools.ietf.org/html/rfc7237

ISO/IEC 10918 JPEG Standard for digital compression and encoding of continuous-tone still images

IHE ITI TF-2x: Appendix V IHE IT Infrastructure Technical Framework, Volume 2x, Appendix V (Web Services for IHE Transactions)

SUBM-wadl-20090831 Web Application Description Language (WADL), W3C Member Submission 31 August 2009 http://www.w3.org/Submission/wadl/)

The Unicode Standard, "Chapter 2. General Structure". The Unicode Standard (6.0 ed.). Mountain View, California, USA: The Unicode Consortium. ISBN 978-1-936213-01-6.http://www.unicode.org/versions/Unicode7.0.0/

615

620

625

630

635

640

645

DICOM PS3.18 2014c - Web Services Page

4 Terms and DefinitionsFor the purposes of this part of DICOM, the following terms and definitions apply.

4.1 DICOM TermsAttributeData ElementInformation EntityInstanceInstanceUIDObjectObjectIDSeriesSeriesUIDSop InstanceStudyStudyUIDTagUID

4.2 DICOMweb Terms and DefinitionsThe following terms are used throughout this part of the standard; but they are, in general, not used in the rest of this standard

Study or Study InstanceSeries or Series InstanceInstance or SOP Instance

A composite SOP Instance, as defined in PS3.3, that has been allocated a DICOM unique identifier..

DICOMweb

The set of protocols defined in PS3.18.

User Agent

A user agent that understands and can processes responses from a DICOMweb origin server.

DICOMweb Origin ServerA program that can originate authoritative responses for DICOMweb target resources.

- Draft -

650

655

660

665

670

675

DICOM PS3.18 2014c - Web Services Page

4.3 HTTP Terms and DefinitionsThe DICOMweb Standard uses the following HTTP terminology extensively. In order to understand the DICOMweb Standard, it is important to understand these terms.

Absolute-URI ReferenceAbsolute-Path

A relative URI reference that begins with a single slash character ‘/’.

Content CodingAn encoding transformation that can be applied to a representation. Content encodings are primarily used to allow a representation to be compressed or otherwise transformed without losing the identity of its underlying media type and without loss of information. See [rfc7231, Section 3.1.2.1< https://tools.ietf.org/html/rfc7231#section-3.1.2.1 >] for details.

Effective Request URIFor a user agent, the effective request URI is the target URI.

Header Field

Media TypeA media type is an identifier, possibly with parameters, that is used to identify the format and/or encoding of a representation. The media type contained in the Content-Type header field tells the receiver how to parse or decode the message payload.

Message Body

Method

Network-PathA relative URI reference that begins with two slash characters ‘//’.

Origin Server The term "origin server" refers to the program that can originate authoritative responses for a given target resource. See [RFC7230 Section 2.1 Client/Server Messaging].

Payload, Payload BodyReason PhraseRelative-Path

A relative URI reference that does not begin with a slash character.

RepresentationWhen used in the DICOMweb Standard the term representation means the representation of a resource.

“For the purposes of HTTP, a "representation" is information that is intended to reflect a past, current, or desired state of a given resource, in a format that can be readily communicated via the protocol, and that consists of a set of representation metadata and a potentially unbounded stream of representation data.” [RFC7231]

Each representation is encoded in a format that is identified by its media type.

Resource

- Draft -

680

685

690

695

700

705

710

715

DICOM PS3.18 2014c - Web Services Page

In the most general sense a resource is something that is addressable by a URI. [RFC3986] says the following about resources:

“This specification does not limit the scope of what might be a resource; rather, the term "resource" is used in a general sense for whatever might be identified by a URI. Familiar examples include an electronic document, an image, a source of information with a consistent purpose (e.g., "today's weather report for Los Angeles"), a service (e.g., an HTTP-to-SMS gateway), and a collection of other resources. A resource is not necessarily accessible via the Internet; e.g., human beings, corporations, and bound books in a library can also be resources. Likewise, abstract concepts can be resources, such as the operators and operands of a mathematical equation, the types of a relationship (e.g., "parent" or "employee"), or numeric values (e.g., zero, one, and infinity).” [RFC3986]

Resource GroupA resource group is a collection of resources that may or may not have structure.

Request TargetIn a direct request to an origin server this is the Absolute-Path and Query Components of the Target-URI. For a more detailed description see [RFC7230, Section 5.3]< https://tools.ietf.org/html/rfc7230#section-5.3 >].

Target URIThe absolute form of the URI reference in a request. It is typically used as an identifier for the “Target Resource”. The Target URI excludes the fragment component.

A URI reference (Section 2.7) is typically used as an identifier for the "target resource", which a user agent would resolve to its absolute form in order to obtain the "target URI".

Target ResourceA resource located on an origin server that is the Target of a request. A URI reference is typically used as an identifier for the “target resource”, that is the resource(s) that is referenced in the URI of an HTTP request.

Target URIThe absolute form of the URI in an HTTP request.

Status Code

Uniform Resource IdentifiersThe HTTP standard uses Uniform Resource Identifiers (URIs) to reference or address resources accessible on the World Wide Web (WWW). The syntax of URIs is defined in [RFC3986]. A URI is composed of the following components:

Absolute-URI= <absolute-URI, see [RFC3986], Section 4.3>

Relative-part <relative-part, see [RFC3986], Section 4.2>

Scheme = <scheme, see [RFC3986], Section 3.1>

Authority = <authority, see [RFC3986], Section 3.2>

Uri-host = <host, see [RFC3986], Section 3.2.2>

Port = <port, see [RFC3986], Section 3.2.3>

Path-Abempty = <path-abempty, see [RFC3986], Section 3.3>

Segment = <segment, see [RFC3986], Section 3.3>

Query = <query, see [RFC3986], Section 3.4>

Fragment = <fragment, see [RFC3986], Section 3.5>

- Draft -

720

725

730

735

740

745

750

755

DICOM PS3.18 2014c - Web Services Page

Absolute-path = 1*( "/" segment ) <https://tools.ietf.org/html/rfc7230#section-2.7>

Partial-URI = relative-part [ "?" query ] < https://tools.ietf.org/html/rfc7230#section-2.7 >

URI-reference See [RFC3986, Section 4.1].

User AgentAny of the various client programs that initiate a request, including (but not limited to) browsers, spiders (web-based robots), command-line tools, custom applications, and mobile apps.

See RFC-7230 Section 2.1 Client/Server Messaging.

4.4 Other TermsUTF-8 The Unicode Standard, "Chapter 2. General Structure". The Unicode Standard (6.0 ed.). Mountain View, California, USA: The Unicode Consortium. ISBN 978-1-936213-01-6.http://www.unicode.org/versions/Unicode7.0.0/

- Draft -

760

765

770

DICOM PS3.18 2014c - Web Services Page

5 Symbols and Abbreviated TermsDICOM Digital Imaging and Communications in MedicineHL7 Health Level SevenHTML HyperText Markup LanguageHTTP HyperText Transfer ProtocolHTTP/1.1 Version 1.1 of the HyperText Transfer ProtocolHTTP/2 Version 2 of the HyperText Transfer ProtocolHTTPS HyperText Transfer Protocol SecureHTTPS/1.1 Version 1.1 of the HyperText Transfer ProtocolHTTPS/2 Version 2 of the HyperText Transfer Protocol

IHE Integrating the Healthcare EnterpriseMIME Multipurpose Internet Mail ExtensionsMTOM Message Transmission Optimization MechanismQIDO-RS Query based on ID for DICOM Objects by RESTful ServicesREST Representational State TransferRESTful A w RESTful Web service is RESTful if it is a Web service implemented using the REST architecture and

principles. and HTTP (see http://www.ics.uci.edu/~fielding/pubs/dissertation/fielding_dissertation.pdf)RS Protocol The RESTful web service protocol defined in Section 9 of this document.SOAP Simple Object Access Protocol (SOAP12 for SOAP version 1.2)SOP Service Object PairSTOW-RS STore Over the Web by RESTful Services. This term is retired. This is now called the RS Store Transaction.UID Unique (DICOM) IdentifierUPS-RS The RS Unified Procedure Step by RESTful ServiceURI/URL Uniform Resource Identifier / LocatorURI Protocol The protocol defined in Section 7 of this document.WADL Web Application Description LanguageWADO-RS Web Access to DICOM Objects by RESTful ServicesWADO-URI Web Access to DICOM Objects by URIWADO-WS Web Access to DICOM Objects by Web Services (WS*)WS Protocol The protocol defined in Section 8 of this documentWSDL Web Services Description LanguageXML eXtensible Markup LanguageXOP XML-binary Optimized Packaging

- Draft -

775

780

785

790

795

800

805

6 DICOMweb Overview

Closed Issues# Issues

Open Issues# Issues Status

Should we define our own DICOMweb “reason phrases”? Open

Editorial Issues# Issues Status

It seems to be common practice to use relative URI (starting with ‘/’) to describe resource templates. This would eliminate {+svc} everywhere. Should we make this change?

Open

What should the format of the Status Code table be? Is it enough to include it here?Yes

Closed

[add a statement about the goals and history of DICOMweb]

[6.1] DICOMweb Use ofs HTTP (Informative)When used in this document the term HTTP and HTTP Standard 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.

The DICOMweb Standard is defined on top of the HTTP and DICOMweb transactions are defined in terms of HTTP messages. The HTTP standards are normative for all aspects of message content and transmission. In there are any conflicts between the DICOMweb Standard and the HTTP standards the HTTP standards are normative.

810

815

6.1[6.2] DICOMweb Protocols, Services, and TransactionsThe DICOMweb protocols are all built on top of the HTTP and HTTPS protocols. Throughout this document the term ‘HTTP’ will be used to denote either HTTP or HTTPS along with any version of these protocol supported by DICOMweb protocols.

The DICOMweb Standard defines three different web protocols: URI, WS, and RS. Each protocol is named for the type of web services protocol that it uses in its implementation. Each protocol defines one or more services. Each service operates on a set of well-defined resources, called a resource group. Each service defines a set of transactions that operate on its resources.

The URI protocol is the oldest protocol. It first became part of the Standard in 20XX. The URI protocol gets its name from the fact that its transactions are all based on the query component of the URI in its request messages. The URI protocol implements one eponymous service that retrieves representations of its resources, which are all DICOM SOP Instance. The URI service defines three transactions that retrieve 1) DICOM representations, 2) rendered representations, and 3) rendered representations of presentation state SOP instances.

The WS protocol is a much newer protocol. It first became part of the Standard in 20XX. The WS protocol gets its name from the fact that its transactions are all based on the WS-I Web Services Interoperability stack and in particular on the Simple Object Access Protocol (SOAP). The WS protocol was created to provide a DICOM interface to the IHE XDS-I.b medical imaging standard. The WS protocol also implements one eponymous service that retrieves representations of its resources, which are DICOM Studies and their substructure. The WS service defines three transactions 1) Retrieve Document Set, 2) Retrieve Rendered Document Set, and 3) Retrieve Document Set Metadata.

The RS protocol is the newest protocol. Its first service became part of the Standard in 2012. The RS protocol endeavors to define RESTful Services, hence its name. The RS protocol currently defines a Storage Service and a Worklist Service. Each of these services have numerous transactions. The Storage Service not only defines retrieve transactions, but also store, search, and capabilities transactions. The Worklist Service also defines an extensive set of transactions.

6.2[6.3] ResourcesThis Part of the Standard does not limit the scope of resources; rather, the term "resource" is used in a general sense for whatever might be identified by a URI. Most of the resources defined by this Part of the Standard are either DICOMweb services or Information Objects defined by the DICOM Information Model. See PS3.3, Section 6. A resource may contain sub-resources.

In this standard, as with HTTP in general, resources are referenced by URIs.

DICOMweb services are focused on two principle resources: studies and work lists.

The studies resource is collection of DICOM studies, where each study contains one or more series and each series contains one or more instances. An instance resource might be a single or multi-frame image, a presentation state, a structured report, etc.

A worklist resource contains work item resources.

6.2.1[6.3.1] Studies,

6.2.2 Series, Instance, and Frame List Resources

6.3[6.4] RepresentationsResources are encoded as representations. A representation is a concrete data object that contains…

DICOMweb defines three different types of representations: SOP Instances, Metadata, and Bulkdata.

820

825

830

835

840

845

850

855

860

6.3.1[6.4.1] SOP InstancesThe DICOMweb unit of communication is the Composite SOP Instance, which is a concrete occurrence of an Information Object. Throughout Part 18 the term instance means Composite SOP Instance unless stated otherwise. Instances can be stored and retrieved. See PS3.3.

Each instance contains attributes from the patient, study, series, and instance level. For example, if a series resource contains 12 instances, then a transaction that retrieves that series will contain the representations of 12 instances, and each instance will contain patient, study, series, and instance level attributes.

An Attribute is an abstract concept that has a 1) Semantic Identifier, which defines its semantic meaning, 2) a Type, which defines rules for whether the attribute is required in an Information Object, 3) a Value Representation, which defines the data type of the values, and a Value Multiplicity, which defines the number of value(s) that an Attribute Representation may contain.

A Data Element is a concrete representation of an attribute. Data Elements have a Tag that is an encoding of the Semantic Identifier, possibly a Value Representation Code, and a value (See PS3.5

Each attribute has a Tag, which defines the semantic meaning of the attribute, a Value Representation, which defines its data type, and a value, which is an octet stream, that is a sequence of bytes.

6.3.2[6.4.2] Normalized SOP Instance

6.3.3 Composite SOP Instance

6.3.4 Metadata, and

6.3.5 Bulkdata ResourcesMost attribute values are small, but some, such as images or video, can be quite large. In order to improve communication efficiency an Instance can be decomposed into metadata and bulkdata.

Metadata A metadata instance contains all the attributes of the Instance, except that for certain value representations, any values that are larger than an origin server defined threshold, may be moved into a bulkdata object, with the attribute value being replaced by a URI that references it, called the BulkdataURL. The Bulkdata URI references the associated bulkdata value.

The value representations whose values can be moved to bulkdata are: FL, FD, IS, LT, OB, OD, OF, OW, SL, SS, ST, UL, UN, US, and UT.

Bulkdata A bulkdata instance contains all the bulkdata, i.e., large values, that have been removed from the related metadata instance.

The metadata should be consistent with the characteristics of the bulkdata on the server. If bulkdata is requested using specific transfer syntaxes or media types, it is possible that the bulkdata retrieved may be inconsistent with the metadata. For example, a request to retrieve a Study whose Tag (0028,2110) "Lossy Image Compression" is set to "00", indicating no lossy compression, with a lossy compression media type will provide pixel data that is inconsistent with the metadata. It is the responsibility of the client to deal with these inconsistencies appropriately.

Note

1. The server is not required to replace any attribute with a BulkdataURL.

2. For media types that do not allow binary values, binary values are Base64 encoded.

3. Some DICOM instances, such as work items, may not allow bulkdata conversion.

865

870

875

880

885

890

895

4. While metadata and bulkdata are currently defined as resources, they are more appropriately media types and are expected to be define as such in the near future.

6.4[6.5] DICOMweb Transactions and SyntaxDICOMweb transactions are defined in terms of HTTP request/response message pairs.

Messages are defined using the ABNF Grammar defined in [RFC7230, Section 1.2]. This includes the list extension ‘#’ defined in [RFC7230, Section 7], that allows for compact definition of comma-separated lists using a '#' operator (similar to the '*' operator that indicates repetition).

6.4.1[6.5.1] Request and Response Message FormatAll DICOMweb request messages have the following format:

method SP {/resource}{?query*} SP version CRLF*header-field↲ CRLF↲ CRLF[payload]

Method ∎ {/resource}{?query*} ∎ version ↲*header-field ↲↲[payload]

And all response messages have the following format:

version ∎ status-code ∎ reason-phrase↲*header-field ↲↲[payload]

Where,

method is the HTTP method (such as GET, POST, etc.);

resource is relative URI that specifies the path to the target resource, where the base URI is the absolute URI of the service;

query is the query component, which specifies zero or more query parameters (see [ref]);

version is the version of the HTTP protocol being used.

header-field specifies the header-fields, separated by CRLF.

[payload] is the, possibly empty, payload.

version is the version of the HTTP protocol being used.

status-code is a 3 digit integer encoding the type of the response.

reason-phrase is a short description of the response status.

The terms defined above will be used throughout the rest of this standard when specifying request message formats.

1. Syntactic variables are lowercase. 2. Literal characters in the format are in bold face, parameters are specified using URI Templates. The symbol ‘∎’

stands for the US-ASCII space (0x20) literal character, and ’↲’ stands for the ASCII carriage return (0xD) and line feed (0xA) literal characters.

3. Resource targets are specified as URI Templates4.

900

905

910

915

920

925

930

935

940

5. None of the protocols or services defined by the DICOMweb Standard use the Fragment Component of the request URI.

Target URI format:

Absolute: {scheme}://{server}{/service}{/resource}{?query}{&more}

Relative: / or {/resource}{?query}{&more}

[6.5.2] Request MessagesThe syntax of request messages is:

version ∎ status-code ∎ reason-phrase↲*header-field ↲↲[payload]

The following sections explain the parts of the request message in detail.

6.4.1.1[6.5.2.1] MethodsThe request method is one of the HTTP methods, such as GET, POST, etc.

6.4.1.2[6.5.2.2] Target-URI SyntaxIn this standard, as with HTTP in general, resources are referenced by URIs. Their structure is defined using URI Templates as defined in [RFC6570]. Each service defines the resources it manages and URI templates used to reference them.

Each request contains a Target-URI. The following URI template variables are used throughout the standard when describing the target URI of a request message:

{/resource} The path to the resource

?{query} One or more required query parameters

{?query} / {?query*} Zero or more query parameters

[6.5.2.3] Query Parameters and Their Syntax (Normative)DICOMweb requests may use the query component of the target-URI to specify parameters. Parameters are ‘name=value’ pairs. The ‘name’ start with an alphabetic or underscore character, followed by zero or more alphanumeric or underscore ‘_’ characters. The parameter may have one or more comma-separated values. Values are composed of any legal query character as defined by [RFC3986], except equal ‘=’, ampersand ‘&’ and comma ‘,’.

For example:

?deidentify&cols=512&region=10,10,500,500

The following grammar defines the general syntax of parameters contained in the query component of the URI. Specific HTTP transactions defined elsewhere in this standard may further refine the legal <name> and/or <value> rules.

query = parameter [ *("&" parameter) ]parameter = name "=" #value / attribute “=” #attribute-valuename = 1*(ALPHA / “_” ) *( ALPHA / DIGIT / "_")value = *vchar [ *(“,” *vchar) ]attribute = keyword [ *( “.” attribute ) ] / tag [ *( “.” attribute) ]

keyword = Data Element Keyword from PS3.6, Table 6-1tag = Data Element Tag from PS3.6, Table 6-1

vchar = unreserved / pct-encoded / vspecial / ":" / "@"

945

950

955

960

965

970

975

980

vspecial = "!" / "$" / "'" / "(" / ")" / "*" / "+" / ";" / “/” / “?”

Where these rules are from [RFC3986]:

unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~"pct-encoded = "%" HEXDIG HEXDIG

And these rules are from [RFC5234]:

ALPHA = %x41-5A / %x61-7A ; A-Z / a-zDIGIT = %x30-39 ; 0-9HEXDIG = DIGIT / "A" / "B" / "C" / "D" / "E" / "F"

Each query parameter is composed of either a <name> and one or more <values> or an <attribute> and one or more <attribute-values>.

<name>s start with a letter or underscore ‘_’, followed by zero or more letters, digits, or underscores. If a parameter has multiple values they are separated by a comma. Multiple parameters are separated by the ampersand ‘&’ character.

The encoding of the <value> above shall be defined by the media type.

Note

1. No whitespace is permitted in URIs. Whitespace around line breaks and the line breaks themselves should be stripped before parsing the URI (See RFC 3986 Appendix C).

2. RFC 3986 does not permit an empty query component, i.e. if the "?" appears in the URI then there must be some legal query parameters in the URI.

3. The <vchar> rule (value characters rule) defined above is the <query> rule of RFC 3986, which defines the legal character for the query component, except for the equal ‘=’, comma ‘,’ and ampersand ‘&’ characters.

6.4.1.2.1[6.5.2.3.1] Query Parameter SpecificationsAll query parameters are strings. Their format is <name>=<values>, where value is specified using a URI template. For example, the “viewport” parameter is specified as:

viewport = {rows, columns} where rows and columns are positive integers

Here rows and columns in the URI template are variable names for parameter values.

The parameter definition should include:

The type of value the string represents, how it is parsed, and what characters are legal The minimum and maximum length of the string How many values the parameter may have The range of the value(s)

Their format is specified using URI templates.

Table 6.3-X defines standard names for parameter value types. Parameter definitions use these names to specify the constraints on the value type.

Table 6.3-X: Query Parameter Value TypesValue Type Constraint Description# type, length A comma-separated list containing <type> values, with max length.attribute See the ABNF for attribute parameters below.binary length A Base64 encoded string

985

990

995

1000

1005

1010

1015

1020

decimal range A string specifying a decimal number, with maximum length 64.integer range A string specifying an integer, with a maximum length 12keyword See below.tag valid tag See below.name charset, length A token, as defined by HTTP, used to specify the type of a uid Valid, length A string containing a valid UID, with maximum length 64uuid Valid A string containing a valid uuid [ref]32 lowercase hexadecimal

digits, displayed in 5 groups separated by hyphens in the form (8-4-4-4-12). For example: 123a4567-b89b-98c7-d654-3210fedcba98

All parameters and their values must be strings; however, the values represented are not necessarily strings. Table X.Y-z contains the conversion rules for non-string data types.

Data Type Encoding Rule Decoding Rule

Binary attribute values: OB, OD, OF, OW, UN

Query parameter values shall not be padded to an even length with a NULL character.

[6.5.2.4] Request Header Fields (Informative)This section describes the header-fields that are typically used by DICOMweb messages.

6.4.1.2.2[6.5.2.4.1] Content Negotiation Header FieldsAll DICOMweb requests that expect to receive a response containing a payload shallshould provide an Accept header field [ref https://tools.ietf.org/html/rfc7231#section-5.3].

AcceptUser agents use the Accept header field to specify a list of media types that are acceptable in the response payload. See [RFC7231, Section 5.3.2]. Any request that expects a response should shall specify an Accept header field with one or more media types.

The media types in the Accept header can be given a priority ordering by using Quality Values. See [RFC7231, Section 5.3.1].

DICOMweb has extended this header field for DICOM media types to include an optional transfer syntax parameter. See [ref media types].

Accept-Encoding

1025

1030

1035

The Accept-Encoding header field is used by user agents to specify a list of content encodings [RFC7231, Section 3.1.2.1< https://tools.ietf.org/html/rfc7231#section-3.1.2.1>] that are acceptable in the response payload.

User agents use the Accept-Charset header field to specify a list of character set names that are acceptable in the response payload. See [RFC7231, Section 5.3.3].

Character set names are case-insensitive. The user agent shall use IANA Character Set Names if defined in the [IANA Character Sets registry].

Annex XX lists DICOM character sets with links to their corresponding names in the IANA Character Set registry.

Note

1. Since most media types, including application/dicom+xml, and application/json have a default character set of UTF-8, the Accept-Charset header field is rarely used.

2. Many media types specify a ‘Charset’ parameter that can be used to specify the character set used with the media type.

6.4.1.2.2.1[6.5.2.4.1.1] Content Negotiation Header ParametersAll DICOMweb requests that expect to receive a response containing a payload might also provide one or more of the following content negotiation header parameters.

Quality Valueq={x} where 0.0 < X <= 1.0

Many of the request header fields for proactive negotiation use a common parameter, named "q" (case-insensitive), to assign a relative "weight" to the preference for that associated kind of content. This weight is referred to as a "quality value" (or "qvalue") because the same parameter name is often used within server configurations to assign a weight to the relative quality of the various representations that can be selected for a resource. See [RFC7231, Section 5.3.1].

CharsetMany media types, especially text/* types, define a Charset parameter that specifies the character set for the representation.

6.4.1.2.3[6.5.2.4.2] Content RepresentationThe header fields described in are used to specify the representations contained in the payload of a message.

All messages that contain a payload should include the following header fields:

Content-TypeThe Content-Type header field is used to specify the media type of the payload. If a DICOMweb message has a payload it shall have a Content-Type header field. Depending on the media type this header field may not fully specify the contents of the payload. See [RFC7231, Section 3.1.1.5]].

The following header field should be included…

Content-LocationThe Content-Location header field contains a URI reference to the resource that corresponds to the representation in the payload. See [RFC7231, Section 3.1.4.2].

The following header field shall be present when the message contains a payload and does not have a Transfer-Encoding header field.

Content-LengthThe Content-Length header field specifies the length of the payload or of an anticipated payload as a decimal number of octets. It shall be included when a message does not have a Transfer-Encoding header field. [ref]

1040

1045

1050

1055

1060

1065

1070

1075

1080

For messages that do not include a payload body, the Content-Length indicates the size of the selected representation. See [RFC7231, Section 3].

The following optional header fields are used to specify information about the encoding of the payload:

Content-EncodingThe "Content-Encoding" header field indicates what transfer encodings have been applied to the representation contained in the payload, beyond those inherent in the media type, and thus specify what decoding mechanisms have to be applied in order to obtain data in the media type referenced by the Content-Type header field. Content-Encoding is primarily used to allow a representation's data to be compressed without losing the identity of its underlying media type. See [RFC7231, Section 3.1.2.2].

Content-LanguageThe "Content-Language" header field describes the natural language(s) of the intended audience for the representation. It is recommended that any message with a payload include this header field. See [RFC7231, Section 3.1.3.2 ] . For example,

Content-Language: en-US

There are no requirements for language negotiation in DICOM.

6.4.1.2.4[6.5.2.4.3] Transfer Syntax Parameters for Content Negotiation and -Representation Header FieldsOrigin servers that implement the RS protocol shall be prepared to handle transfer syntax parameters for all imaging media types. The syntax is:

media-type; transfer-syntax={transfer-syntax}

For example, an Accept header field might look as follows:

Accept: application/dicom; transfer-syntax=1.2.840.10008.1.2.4.70

6.4.1.3[6.5.2.5] Request PayloadThe message body (if any) of an HTTP message is used to carry the payload body or payload of that message. The message body is identical to the payload unless a transfer coding has been applied, as described in [RFC7230, Section 3.3.1]. This standard uses the terms payload, payload body, and message payload interchangeably to denote the message body before any transfer coding has been applied to it.

All messages have payloads, but the payload may be empty, i.e. length = zero.

The rules for when a payload is allowed in a message differ for requests and responses.

The presence of a message body in a request is signaled by a Content-Length or Transfer-Encoding header field.

The presence of a message body in a response depends on both the request method to which it is responding and the response (status code)< https://tools.ietf.org/html/rfc7230#section-3.1.2 >.

6.4.2[6.5.3] BehaviorEach DICOMweb transaction definition includes a Behavior Section that describes processing that occurs on the origin server based on the format and contents of the request message, including the method, parameters, and especially the target resource(s). It also describes the format and representation(s) contained in the response message.

The origin server shall return an error response if it cannot satisfy the request.

6.4.3[6.5.4] Response Message FormatThe syntax of a response message is:

1085

1090

1095

1100

1105

1110

1115

1120

version ∎ status-code ∎ reason-phrase↲*header-field ↲↲[payload]

Where the syntactic variables are defined in Section X.Y.

The following sections explain the response message components in detail.

6.4.3.1[6.5.4.1] Status Codes (Informative)A status-code is a three-digit integer that encodes the result of the origin server’s attempt to understand and satisfy the request. The HTTP/1.1 Standard says:

“HTTP status codes are extensible. …The reason phrases listed here are only recommendations -- they can be replaced by local equivalents without affecting the protocol.” [RFC7231]

The first digit of the status-code defines the class of the response. Table 6.4-1 shows the five classes that have been defined.

Table 6.4-x: Status Code ClassesClass Meaning1xx: Informational Request received, continuing process2xx: Success The action was successfully received, understood, and accepted3xx: Redirection Further action must be taken in order to complete the request4xx: Client Error The request contains bad syntax or cannot be fulfilled5xx: Server Error The server failed to fulfill an apparently valid request

The following table, which contains the status codes defined by the HTTP Standard, is informative. It is copied from the IANA HTTP Status Code Registry, which is normative.

Table 6.4-1: HTTP Status Codes Used by PS3.18Value  Description  C R U D Q O Reference 100 Continue X [RFC7231, Section 6.2.1]101 Switching Protocols X [RFC7231, Section 6.2.2]102 Processing [RFC2518]103-199 Unassigned200 OK X X X [RFC7231, Section 6.3.1]201 Created X [RFC7231, Section 6.3.2]202 Accepted X X [RFC7231, Section 6.3.3]203 Non-Authoritative Information [RFC7231, Section 6.3.4]204 No Content X [RFC7231, Section 6.3.5]205 Reset Content [RFC7231, Section 6.3.6]206 Partial Content X X X X [RFC7233, Section 4.1]207 Multi-Status [RFC4918]208 Already Reported [RFC5842]209-225 Unassigned226 IM Used [RFC3229]227-299 Unassigned300 Multiple Choices [RFC7231, Section 6.4.1]

1125

1130

1135

1140

Value  Description  C R U D Q O Reference 301 Moved Permanently X X X X [RFC7231, Section 6.4.2]302 Found [RFC7231, Section 6.4.3]303 See Other [RFC7231, Section 6.4.4]304 Not Modified [RFC7232, Section 4.1]305 Use Proxy [RFC7231, Section 6.4.5]306 (Unused) [RFC7231, Section 6.4.6]307 Temporary Redirect [RFC7231, Section 6.4.7]308 Permanent Redirect [RFC7238]309-399 Unassigned400 Bad Request X X X X X X [RFC7231, Section 6.5.1]401 Unauthorized X X X X X X [RFC7235, Section 3.1]402 Payment Required [RFC7231, Section 6.5.2]403 Forbidden X X X X X X [RFC7231, Section 6.5.3]404 Not Found [RFC7231, Section 6.5.4]405 Method Not Allowed X X X X X X [RFC7231, Section 6.5.5]406 Not Acceptable X X X X X X [RFC7231, Section 6.5.6]407 Proxy Authentication Required X X X X X X [RFC7235, Section 3.2]408 Request Timeout X X X X X X [RFC7231, Section 6.5.7]409 Conflict [RFC7231, Section 6.5.8]410 Gone X X X ? X [RFC7231, Section 6.5.9]411 Length Required X X ? [RFC7231, Section 6.5.10]412 Precondition Failed [RFC7232, Section 4.2]413 Payload Too Large X X [RFC7231, Section 6.5.11]414 URI Too Long X X X X X X [RFC7231, Section 6.5.12]415 Unsupported Media Type X X X X X X [RFC7231, Section 6.5.13]416 Range Not Satisfiable [RFC7233, Section 4.4]417 Expectation Failed [RFC7231, Section 6.5.14]418-421 Unassigned422 Unprocessable Entity [RFC4918]423 Locked X X X X X X [RFC4918]424 Failed Dependency [RFC4918]425 Unassigned426 Upgrade Required [RFC7231, Section 6.5.15]427 Unassigned428 Precondition Required ? [RFC6585]429 Too Many Requests X X X X X X [RFC6585]430 Unassigned431 Request Header Fields Too Large X X X X X X [RFC6585]432-499 Unassigned500 Internal Server Error X X X X X X [RFC7231, Section 6.6.1]

Value  Description  C R U D Q O Reference 501 Not Implemented X X X X X X [RFC7231, Section 6.6.2]502 Bad Gateway ? [RFC7231, Section 6.6.3]503 Service Unavailable X X X X X X [RFC7231, Section 6.6.4]504 Gateway Timeout X X X X X X [RFC7231, Section 6.6.5]505 HTTP Version Not Supported X X X X X X [RFC7231, Section 6.6.6]506 Variant Also Negotiates [RFC2295]507 Insufficient Storage X X X X X X [RFC4918]508 Loop Detected [RFC5842]509 Unassigned510 Not Extended [RFC2774]511 Network Authentication Required [RFC6585]512-599 Unassigned

Keys to abbreviated column heading in Table x.y above:

Code

Transaction Type

C Create new resourcesR Retrieve resourcesU Update existing resourcesD Delete resourcesQ Search for resourcesO Other (Change State, Upgrade)

The most common HTTP status codes used by RS services are listed in Table 9.4-1. IANA maintains the HTTP Status Code Registry, which contains a complete list of registered status codes.

Table 9.4-X: Response Status CodesCode Phrase Description

Success – the 2xx class of status codes indicates that the client's request was successfully received, understood, and accepted.

200 OK Indicates that all target resource representations are contained in the payload.

201 Created Indicates that the request has been fulfilled and has resulted in one or more new resources being created.

202 Accepted Indicates that the request has been accepted for processing, but the processing has not been completed. The user agent can use a

203 Non-Authoritative Information

Indicates that 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.

204 No-Content Indicates that the server has successfully fulfilled the request and that 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.

1145

205 Reset Content Indicates that 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. This code could be returned in response to a Worklist Service Create Work Item request.

206 Partial Content Indicates that some, but not all, of the target resource representations are contained in the payload.This could be because the origin server does not support the media types, transfer syntaxes for some but not all requested content.

The 4xx (Client Error) class of status code indicates that the client seems to have erred. Except when responding to a HEAD request, the server SHOULD send a representation containing an explanation of the error situation, and whether it is a temporary or permanent condition.

400 Bad Request Indicates that 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 …). Also indicates that no instances were stored due to bad message syntax.

401 Unauthorized Indicates that the request has not been applied because it lacks valid authentication credentials for the target resource. The server generating a 401 response MUST send a WWW-Authenticate header field (Section 4.1) containing at least one challenge applicable to the target resourse.

403 Forbidden Indicates that 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.

404 Not Found Indicates that 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 is preferred over 404.

405 Method Not Allowed Indicates that the method received in the request-line is known by the origin server but not supported by the target resource. The origin server MUST generate an Allow header field in a 405 response containing a list of the target resource's currently supported methods.

406 Not Acceptable Indicates that the target resource does not have a representation that would be acceptable to the user agent, according to the content negotiation header fields in the request, and the server is unwilling to supply a default representation.The server SHOULD generate a payload containing a list of available representation characteristics (media types) and corresponding resource identifiers from which the user or user agent can choose the one most appropriate.

409 Conflict Indicates that 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 might be able to resolve the conflict and resubmit the request. The server SHOULD generate a payload that includes enough information for a user to recognize the source of the conflict.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 SOP Instance mismatch).I

410 Gone Indicates that access to the target resource is no longer available at the origin server and that this condition is likely to be permanent. If the origin server does not know, or has no facility to determine, whether or not the condition is permanent, the status code 404 (Not Found) ought to be used instead.

411 Length Required Indicates that the server refuses to accept the request without a defined Content-Length.

413 Payload Too Large Indicates that the server is refusing to process a request because the request payload is larger than the server is willing or able to process.

414 URI Too Long Indicates that the server is refusing to service the request because the request-target (Section 5.3 of [RFC7230]) is longer than the server is willing to interpret.

415 Unsupported Media Type

Indicates that the origin server does not support the Content-Type in the request payload.

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. Except when responding to a HEAD request, the server SHOULD send a representation containing an explanation of the error situation, and whether it is a temporary or permanent condition.

500 Internal Server Error

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

501 Not Implemented Indicates that the server does not support the functionality required to fulfill the request.

503 Service Unavailable Indicates that the 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

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

6.4.3.2[6.5.4.2] Response Header FieldsThis part of the service descriptions defines the header fields that are required, conditionally required, or optional in the response.

If the response has a payload some or all of the Representation Metadata header fields (see [ref]) should be present.

General with Payload

Content-Type

Content-Location

Content-Length

6.4.3.3[6.5.4.3] Response PayloadThe presence of a payload in a response depends on both the request method to which it is responding and the response (status code)< https://tools.ietf.org/html/rfc7230#section-3.1.2 >.

1150

1155

6.4.3.3.1[6.5.4.3.1] Status Details Payload for Responses with IssuesWe need a general mechanism for sending Status Details for the case where a transaction is either partially successful or has failed. We propose to use the ideas in “Status Details for HTTP APIs [See https://tools.ietf.org/html/draft-nottingham-http-problem-07].

The format of this payload should be defined by the media type.

We should define JSON, XML, and HTML versions. HTML would be the default if not defined by the media type

For example, a HTTP response carrying JSON Status Details:

HTTP/1.1 403 Forbidden

Content-Type: application/problem+json

Content-Language: en

{ "type": "http://example.com/probs/out-of-credit", "title": "You do not have enough credit.", "detail": "Your current balance is 30, but that costs 50.", "instance": "http://example.net/account/12345/msgs/abc", "balance": 30, "accounts": ["http://example.net/account/12345", "http://example.net/account/67890"]}

6.4.4[6.5.5] PayloadsBoth requests and responses can have payloads. Messages that have a payload typically have Payload-Related Header Fields

[6.5.5.1] Payload- Related Header FieldsContent-LengthContent-RangeTrailerTransfer-Encoding

Content-Type and Content-Location header fields. There are two basic payload structures: single part and multi-part.

6.4.4.1[6.5.5.2] Payload Format

6.4.4.1.1[6.5.5.2.1] Single Part PayloadA single part payload contains one representation that is described by the content header fields, i.e., Content-Type, Content-Length, Content-Location, etc. The Content-Type header field shall have a single part media-type. [ref]

6.4.4.1.2[6.5.5.2.2] Multi-Part PayloadA multi- part payload contains one or more representations, the first representation is described by the content header fields of the message. The Content-Type header field shall have a multi-part media-type such as:

content-type: multipart/related; type={root-media-type}; boundary=“---boundary---”

Where,

1160

1165

1170

1175

1180

1185

1190

1195

multipart/related is a media type defined by [RFC2387 <https://tools.ietf.org/html/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.

Each part starts with the boundary followed by a carriage return and line feed (↲).

Each part in a multi-part payload contains one or more header fields followed by a representation in the media type specified by the Content-Type header. Each part in a multi-part payload shall start with a boundary string, followed by Content-Type and Content-Location header fields, followed by either a Content-Length or a Transfer-Encoding header field, optionally followed by a Content-Description header field.

The syntax of a multipart payload is defined as follows:

Message Header Fields:

Content-Type: Multipart/Related; type=”application/dicom”; boundary={---boundary---}↲Content-Location: {service}/studies/012}/series/345/instance/678↲

Note:

The type parameter is either a token or a quoted-string; however, if the type parameter contains any non-token characters it must be a quoted-string. Since type parameters typically contain a slash ‘/’, they are almost always quoted-strings.

Multipart Payload Format:

{---boundary---}↲Content-Type: “application/dicom”↲Content-Location: {service}/studies/012}/series/345/instance/678↲Content-Description: PS3.10 SOP Instance↲↲{payload}↲{---boundary---}↲Content-Type: “application/dicom”↲. . .

1200

1205

1210

1215

1220

1225

Figure 9.2-1: Mapping between IOD and Multi-Part Payload

6.4.5[6.5.6] Representations and Media TypesDICOM Instances, whether SOP, metadata or bulkdata can be represented using binary, XML, or JSON.

Each Protocol and/or Service defines the representations and media types that are required and recommended. They may also defined the default media type.

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 RS Protocol. See Section 9.4.4.2.

Internet media types [RFC2046] are the basis for both content negotiation and data typing of message payloads. A media describes the format of a representation of a resource. Each DICOMweb service has a set of media types that it supports.

HTTP uses the Content-Type [RFC 7231, Section 3.1.1.5] and Accept [RFC7231, Section 5.3.2] header fields, for content negotiation and data typing.

6.4.5.1[6.5.6.1] Representation CategoriesA media type identifies the format of a representation of a resource. Media types are the values of the Accept header field and the Content-Type header field.

The media types in the Accept header field(s) define the media types that are acceptable to the user agent 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 payload of that message or part.

1230

1235

1240

1245

This standard categorizes media types based on the SOP classes in PS3.3. A target resource’s category depends on its SOP class. The categories are:

Non-RenderedNative DICOM InstancesComposite nstances

The Native category corresponds to all composite SOP classes encoded as defined by this Standard. These media types are used for representations of Information Entities defined by this Standard. Any DICOM resource can have a DICOM representation using a DICOM media type. The DICOM media types are defined in Annex X.

DICOM Normalize InstancesDICOM encapsulated CDACDA encapsulated DICOMCDA Non services are defined for these at this time.

RenderedSingle Frame Image Pixel Datas

The single frame image resource category corresponds to SOP classes defined in PS3.3 that consist of a single image frame, instances of multi-frame SOP Classes that contain only one frame, or consist of single frame accessed using a Frame Number parameter.

These media types are used for rendered representations that contain a single image.

Multi-Frame Image Pixel DataThe multi-frame image resource category corresponds to SOP classes defined in PS3.3 that are multi-frame or video image instances. These instances may have representations in either a DICOM media type or in one of the rendered multi-frame media types.

Non-DICOM DocumentsThe textual resource category includes all SOP classes defined in PS3.3 that include the SR Document Content Module. This includes documents, such as narrative text or unencapsulated PDF., structured reports, CAD, measurement reports and key object selection documents.

Implementers are strongly encouraged to support a textual media type that is in conformance with HL7 CDA R2, e.g., text/xml.

Non-Image DiCOM InstancesOther

The Other resource category includes all Composite SOP Classes that are not included in the categories above. Only DICOM media types are required for this category. Any appropriate media type may be used for rendered representations of these resources.

The origin server shall support all default and required media types for a particular protocol, i.e., URI, WS or RS. The origin server may also support other media types not listed here.

6.4.5.2[6.5.6.2] Media Type SyntaxThe syntax of media types is as follows:

Name Rulemedia-type = type "/" subtype *( OWS ";" OWS parameter )type = tokensubtype = tokenparameter = name “=” valuename = token

1250

1255

1260

1265

1270

1275

1280

value = (token / quoted-string)

Where, the parameters are optional and are typically defined by the media <type/subtype>. The type, subtype, and parameter name tokens are case-insensitive. Parameter values may or may not be case-sensitive, depending on the semantics of the parameter name.

Note: Unlike some similar constructs in other header fields, media type parameters do not allow whitespace (even "bad" whitespace) around the "=" character

See [RFC7231, Section 3.1.1.1] for more information of HTTP use of media types. See Annex XX for detailed explanations of DICOMweb media types.

6.5[6.6] Standard Transaction TypesThe format of a transaction’s request and response message can be characterized by the transaction’s type. The following Transaction Types are typical of the services defined in this Part of the Standard. Whether a request or response has a payload depends on the type of transaction, including the request method, target resource, and parameters. Table X.Y-Z below defines the methods and payloads used by the various services and their transactions. The response payload column is for successful responses only.

Table X.Y-Z: Transaction PayloadsTransaction Type Method

RequestPayload

Response Payload Description

Create POST Representation(s)Empty or SDD Creates a new resource from the

representation in the request payload.Retrieve GET Empty Representation(s)

or SDDRetrieves a representation of a resource, contained in the response payload.

Update PUT Representation(s) Empty or SDD Updates a resource using the representation contained in the request payload.

Delete DELETE Empty SDD deletes a resourceSearch GET Empty or

ParametersRepresentation(s)

or SDDSearches a resource using the search criteria in the request and returns zero or more representations of matches.

Capabilities Subservice TransactionCapabilities OPTIONS Empty Capabilities

Descriptionor SDD

Retrieves a Capabilities Description Document from a service.

Notification Subservice NotificationsOpen Channel GET SDDSend Event ?Create Subscription

POST ? SDD

Delete Subscription

DELTETE SDD

The term ‘SDD’ in the Response Payload column refers to the Status Details Document that should be returned in all error responses. See Section X.Y.

6.6[6.7] SecurityThis standard does not introduce any security-related requirements. It is likely that the information contained within DICOM objects identifies the patient. HTTPS can be used to protect information in transit.

1285

1290

1295

1300

The underlying DICOM implementation decides whether or not to grant access to a particular DICOM object based on whatever security policy or mechanism it has in place. A server is unlikely to fulfill a request from an unknown user (e.g., accessed via the HTTP protocol) unless it is certain that the data requested has no Personally Identifying Information [ref] within it and has been approved for public viewing.

6.7[6.8] DICOMweb Service DescriptionsEach service defined in this standard is described according to the following structure:

1. Service

A general description of the service

2. Resources

A description of the resources that can get the target of this transaction along with URI-templates.

3. Transactions

An overview of the transactions defined by the service.

4. One or more Transaction Descriptions

One or more Transaction Descriptions in the following format:

a. Transaction Overview

b. Target resources for this transaction

c. The request:

i. Resource path

ii. Query parameters

iii. Header fields

iv. Request payload

A descriptions of the request payload, if any

d. The behavior of the origin server on receiving the request; processing it and creating the response.

e. The response:

i. Status codes

ii. Header fields

iii. Response Payload

f. Media types

A brief description of media types supported by this transaction, along with references to the appropriate Annex.

A brief description of any media types that

5. Media types supported by this service

A brief description of media types supported by this service, along with references to the appropriate Annex.

7 URI Protocol (WADO-URI)

1305

1310

1315

1320

1325

1330

1335

Closed Issues# Issues

Open Issues# Issues Status

What should the maximum value for ‘rows’ and ‘columns’ parameters be?What should the range of ‘windowCenter’ and windowWidth be? refStatus codes for URI have not been defined in the past. Should they be? If so, does it need a CP?

Have browsers advanced enough that we can specify the grayscale and color space?

Should blending PSes be permitted. Yes, since they were not previously specified to not be included?.

Problems with current: 1) if you get an image without specifying the window and level you do not know what the windowing is and therefore you can apply adjustments. Potential solutions return the image and information about how it was rendered, i.e. a json presentation state in a multipart payload. 2) Want multiples images in a payload. The request and return would need to handle presentation states for each image. Can we use a Content-Disposition header? Number, time, location, phase.Am I working at the image level or at the frame level?

Editorial Issues# Issues Status

Should Content-Location be optional for this service? Yes, If the Target URI is the same as the target resource URI, then the Content-Location header field should be omitted; otherwise, the Content-Location header field should be included.

Closed

What are the bounds on Window Center and Width values?Should the URI Media Types table be included in 7.2.4? This would mean including the same table in section 8.2.4.Yes, then when URI is retired no change will need to be made to WS

Closed

For region, would xMin, yMin, xMax, yMax be better names?If the region specified by the parameter is ill defined should it be an error or should the original image size be returned, i.e. as if there were no region argument.URI: return original image size;WS: return original image size,RS: return an error.

Closed

What order should the rendering parameters be presented in? Pipeline? Alphabetic?Suggest pipeline order, first, then alphabetical.Should we use and {object-id} query parameter instead of {requestType=WADL, study_uid, series_uid, object_uid}?No, Use all four parameters.

Closed

1340

Table X.Y-Z: Query Parameters by Transaction

Parameter

Retrieve InstanceDICOM Rendered Presentation

Stateanonymize XframeNumber Xregion Xrows X Xcolumns X XwindowCenter XwindowWidth Xannotation X XimageQuality X X

7.1 URI Service[explain why it is called URI and give some history]

Include references

The URI Protocol is composed of one service with three transactions.

Table 7.2-1: URI Service Transactions

TransactionTarget Resource

Media Types

RequestPayload

ResponsePayload Description

Retrieve DICOM Instance

SOP Instance

DICOM Empty Representationor Emptyor PD

Returns a single DICOM instance by retrieving the resource in the ‘application/dicom’ media type.

Retrieve Rendered Instance

SOP Instance

Rendered Empty Representationor Empty or PD

Returns a single image by rendering the resource in an acceptable media type. Target resource may shall not be a presentation state instance

Retrieve Presentation State Instance

Presentation State SOP Instance

Rendered Empty Representationor Emptyor PD

Returns a single image by rendering the presentation state specified by the resource in an acceptable media-type. Target resource must shall be a presentation state instance

7.1.1 RequestAll URI Services have the following request message format.

GET∎/?{requestType=WADO,study_uid,series_uid,object_uid}{&params*}∎HTTP/1.1 ↲

1345

1350

Accept: dicom-media-type ↲*header-field ↲↲

Where,

/ is the base URI of the Retrieve Service;

requestType=WADO Identifies this as a URI (previously WADO) request;

study_uid is a valid DICOM Study Instance UID;

series_uid is a valid DICOM Series Instance UID; and

objectID is a valid DICOM SOP Instance UID; and

&params* specifies that zero or more additional query parameters may be specified. See each transaction for details.

The request should always include one or more Accept header fields that specify the media types that are acceptable to the user agent making the request.

All URI Service request messages have the following characteristics:

They use the HTTP/1.1 protocol. They use the GET method. The target resource is always a DICOM SOP Instance. The object identification query parameters (see 7.2.1.2.1 below) are required on each request, They use the standard content negotiation header fields (see RFC7231, Section 3.4),

7.1.1.1 Object Identification ParametersUser agents shall include all parameters in this section in all URI requests. The origin server shall support all parameters in this section.

Table 7.2-X: Object Identification ParametersName VR DescriptionrequestType UI URI request typestudy_uid UI Study Instance UIDseries_uid UI Series Instance UIDobject_uid UI SOP Instance UID

The value of the “requestType” parameter must be ‘WADO’.

7.1.1.1.1 Request TyperequestType = WADO

The “requestType” specifies that this is a URI (WADO) request. Its value shall be "WADO".

7.1.1.1.2 Unique Identifier of the Studystudy_uid = Study Instance UID

The “study_uid” parameter identifies the study that contains the target resource. Its value shall be a Study Instance UID.

7.1.1.1.3 Unique Identifier of the Seriesseries_uid = Series Instance UID

The “series_uid” parameter identifies the series that contains the target resource. Its value shall be a Series Instance UID. This parameter is only used by the Retrieve DICOM Instance and Retrieve Rendered Instance transactions.

1355

1360

1365

1370

1375

1380

1385

7.1.1.1.4 Unique Identifier of the Instanceobject_uid = SOP Instance UDI

The “object_uid” parameter identifies the instance that contains the target resource. Its value shall be a SOP Instance UID. This parameter is only used by the Retrieve DICOM Instance and Retrieve Rendered Instance transactions.

7.1.1.2 Other Query Parameters

7.1.1.2.1 Unique Identifier of the Presentation SeriesThis section was previously defined in DICOM. It is now retired. See PS 3.18-2014c, Section 8.1.9.

The Unique Identifier of the Series parameter, “series_uid”, should be used instead. See Section 7.2.1.1.3.

7.1.1.2.2 Unique Identifier of the Presentation ObjectThis section was previously defined in DICOM. It is now retired. See PS 3.18-2014c, Section 8.1.10.

The Unique Identifier of the Instance parameter, “object_uid”, should be used instead. See Section 7.2.1.1.4.

7.1.1.2.3 MIME Type of the Response (Retired)This section was previously defined in DICOM. It is now retired. See PS 3.18-2014c, Section 8.1.5.

Media types are specified using the Accept header field. See Section 6.4.2.4.1.

7.1.1.2.4 Transfer Syntax UID (Retired)This section was previously defined in DICOM. It is now retired. See PS 3.18-2014c, Section 8.2.11.

Transfer syntax is specified as a media type parameter in the Accept or Content-Type header fields as appropriate. See Section

7.1.1.2.5 Charset of the Response (Retired)This section was previously defined in DICOM. It is now retired. See PS 3.18-2014b, Section 8.1.6.

Character set is specified using the Accept-Charset header field. See Section

7.1.1.3 Header FieldsRequired: Accept

This transaction uses the standard header fields. See Section 6.3.2.3.

7.1.1.4 Request PayloadURI Services have an empty request payload.

7.1.2 BehaviorThe Origen-Server uses the object identification query parameters to specify the SOP Instance that is the target resource of the request. The processing of that instance and the response are specified in the individual URI services define below.

7.1.3 ResponseURI responses have the following format:

HTTP/1.1∎status-code ∎reason-phrase↲Content-Type: application/dicom ↲

1390

1395

1400

1405

1410

1415

1420

*header-field↲↲[payload]

Where, a successful response <payload> contains the requested instance representation.

7.1.3.1 Status CodesA success response shall have a status code of 200 (OK).

An error response will have one of the status codes from Section X.Y.Z.

7.1.3.2 Header FieldsThe following response header field requirements are pertinent to all URI transactions.

Required:

Content-Type

Recommended if there is no Transfer-Encoding header field:

Content-Length

Optional:

Content-LocationContent-Encoding

See Section 6.3.2.4

7.1.3.3 PayloadAll successful URI responses have a payload that contains a representation of the target resource in an acceptable media type.

All failure responses may have an empty payload.

7.1.4 Media TypesTable 7.6-1 contains default, required, recommended, and optional media types for the URI service. The service shall support all default and required media types.

Table 6.3-1: URI and WS Media TypesResource Category Media Type Requirement ReferenceDICOM application/dicom default RFC3240

Single Frame Images image/jpeg default ISO/IEC 10918image/gif requiredimage/png requiredimage/jp2 required

Multi-Frame Images image/gif recommendedvideo/mpeg recommended

Text Objects text/html requiredtext/plain requiredtext/rtf recommendedtext/xml recommendedapplication/pdf recommended

Other Objects application/dicom required RFC3240

1425

1430

1435

1440

1445

other media types optional

All requests should specify the acceptable media types using the Accept header field. If no media type is specified, the response payload shall contain a representation in the default media type for the target resource’s category. If the resource category, of the target resource, has no default media type then the response shall use the application/dicom media type.

When an image/jpeg representation is returned, it shall be encoded using the JPEG baseline lossy 8 bit Huffman encoded non-hierarchical non-sequential process ISO/IEC 10918. [ref]

It is recommended that the Server also support a "CDA" media type, in conformance to HL7 CDA R2, e.g., text/xml.

The origin server may support other media types. All media types supported should be included in the conformance statement and the response from the Capabilities Service.

The media types supported by the origin server shall be included in the conformance statement.

7.1.4.1 Acceptable Media TypeThe phrase “in an acceptable media type” when used with respect to the URI protocol means:

One of the media types contained in the Accept header field(s) of a request; or One of the media types contained in the “contentType” query parameter; or The default media type for the service or transaction, if defined.

7.2 Retrieve DICOM Instance TransactionThe Retrieve DICOM Instance request specifies a target resource that is a single DICOM SOP Instance using the object identification query parameters, and a successful response contains a representation of that resource in the application/dicom media type.

7.2.1 RequestThe request has the following format:

GET∎/?{requestType=WADO}{&study_uid,series_uid,instanceUID}{&anonymize}∎HTTP/1.1 ↲Accept: application/dicom↲*header-field ↲↲

The request has the following characteristics:

The target resource path “/” is a URI Reference to the Retrieve Service. The object identification query parameters are required. The Accept header is required and its value must be ‘application/dicom’. The request has no payload.

7.2.1.1 Resource”/” specifies the base URI of this service.

7.2.1.2 Query ParametersThis service requires the object identification query parameters (see 7.2.1.2.1), but it also supports the following parameter.

7.2.1.2.1 Anonymizeanonymize = yes

1450

1455

1460

1465

1470

1475

1480

1485

The “anonymize” parameter is optional, and specifies that the target resource shall have all Personally Identifiable Information (PII) removed. This includes removing or "blanking out" any annotation area(s) containing PII burned into the pixels or in overlays. This process is called de-identification and is sometimes referred to as anonymization; although, the latter term is discouraged. See PS3.15 Section E. Attribute Confidentiality Profiles.

De-identification is the responsibility of the origin server. De-identified objects shall have a new SOP Instance UID that is different from that of the original identified objects. The Server may return an error if either it cannot or refuses to de-identify the requested objects.

7.2.1.3 Header FieldsRequired: Accept: application/dicom

See Section 6.3.1.3.

7.2.1.4 PayloadThe request payload is empty.

7.2.2 BehaviorThe origin server retrieves the SOP Instance specified by the target resource and returns it in the response payload.

7.2.3 ResponseThe response has the following format:

HTTP/1.1∎status-code∎reason-phrase↲Content-Type: application/dicom ↲*header-field↲↲[payload]

A success response contains a status code of 200 (OK) and a single part payload containing the target resource in the application/dicom media type.

7.2.3.1 Status CodesA success response shall have a status code of 200 (OK).

A failure response will have a failure status code from Table X.Y-Z.

7.2.3.2 Header FieldsRequired: Content-Type

See Sections 7.2.3.2 and 6.3.1.3.2.

7.2.3.3 PayloadA success payload contains a representation of the target resource in the application/dicom media type.

A failure response may have an empty payload; however, it is recommended that it contains a Status Details document. See Section 7.2.3.3.

7.2.4 Media TypeThe Retrieve DICOM Instance service only supports the ‘application/dicom’ media type. See Section 7.2.4 and Annex X for details.

1490

1495

1500

1505

1510

1515

1520

7.3 URI Retrieve Rendered Instance TransactionThe Retrieve Rendered Instance request specifies a target resource that is a single DICOM SOP Instance using the object identification query parameters. A successful response shall contain a representation of that resource in an acceptable rendered media type. See Section x.y-Z.

7.3.1 RequestThe request has the following format:

GET∎/?{requestType=WADO,study_uid,series_uid,instanceUID}{&rendering*}∎HTTP/1.1↲Accept: rendered-media-types ↲*header-field*↲↲

Where,

rendering = {&annotation,rows,columns,region,windowCenter,windowWidth,frameNumber,imageQu

ality}

rendered-media-types is one or more of the media types defined in Table x.y-z.

The request has the following characteristics:

1. The target resource may not be a presentation state series or instance.2. Only rendered media types shall be specified in the Accept header field. The application/dicom media type

shall not be specified.3. This transaction provides additional query parameters that specify how the origin server should render the

target resource.

7.3.1.1 Target ResourceThe resource path component of the URI is “/”, this specifies the base URI of the service.

7.3.1.2 Query ParametersThis service requires the object identification query parameters specified in Section 7.2.1.2.1, but it also supports additional query parameters that specify how the target resource is rendered.

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

1. All parameters in this section are optional for the user agent and required for the origin server.2. The parameters only apply to image and video media types, as defined in Section X.X.3. The data types of the parameter values are defined in Section 6.3.1.2.2.4. Unless the “rows” or “columns” parameter is specified the returned image (or selected region) shall be in its

original size.

The following table contains a synopsis of the available rendering parameters:

Table 7.4-X: Retrieve Rendered Instance Query ParametersName Data Type Value DescriptionframeNumber integer The number of the frame to retrieveregion decimal Four decimal numbers that specify the regionrows integer The number of rows in returned imagecolumns integer The number of columns in returned imagewindowCenter decimal The luminosity of the image

1525

1530

1535

1540

1545

1550

1555

windowWidth decimal The contrast of the imageannotation keyword Annotations to be applied to imageimageQuality integer The quality of the lossy compression

7.3.1.2.1 Annotation on the Objectannotation = patient / technique

The “annotation” parameter specifies that annotations should be applied to the returned image. Its value shall be a non-empty, comma-separated list of one or more of the following items:

patient – displays patient information (e.g., patient name, birth date, etc.)

technique – displays technique information (e.g., image number, study date, image position, etc.).

When used in conjunction with the region parameter, it shall be applied after the selection of the region.

The exact nature and presentation of the annotation is determined by the origin server.

7.3.1.2.2 Frame NumberframeNumber = {integer} where 1 <= integer <= total number of frames

The “frameNumber” parameter specifies the frame number of an image within the multi-frame instance specified by the target resource. It shall be ignored for all objects other than multi-frame objects.

7.3.1.2.3 Image QualityimageQuality = {integer} where 1 <= integer <= 100

The “imageQuality” parameter controls the relative quality of lossy compressed images. Its value is an Integer string that ranges from 1 to 100 inclusive, 100 having the best quality.

Note

The meaning of this parameter depends on the media type and is determined by the origin server.

7.3.1.2.4 Pixel Rows in Rendered Imagerows = {integer} where 0 <= integer

The “rows” parameter specifies the height in pixels of the rendered image. The returned image shall have the same aspect ratio as the original image.

N.B: The user agent may specify “rows” or “columns”, but should not specify both. If both are specified, then the origin server shall scale the returned images, maintaining their original aspect ratio, until either the image width is the same as the viewport width or the image depth is the same as the viewport depth, whichever comes first. In other words, viewport scaling makes the image(s) as large as possible without overflowing the viewport area.

7.3.1.2.5 Pixel Columns in Rendered Imagecolumns = {integer} where 0 <= integer

The “columns” parameter specifies the width in pixels of the rendered image. The returned image shall have the same aspect ratio as the original image.

See N.B. in 7.4.1.2.2.

7.3.1.2.6 Region of Target Resourceregion = {xMin,yMin,xMax,yMax} where range = 0.0 <= xMin < xMax <= 1.0, and

0.0 <= yMin < yMax <= 1.0

1560

1565

1570

1575

1580

1585

1590

The “region” parameter specifies a rectangular region of the target resource. Its value shall be a list of four comma separated, positive decimal strings, representing in the following order:

xMin the top row of the region, yMin the left column of the region, xMax the bottom row of the region, yMax the right column of the region,

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

0.0 corresponds to the top row and left column of the image, and1.0 corresponds to the bottom row and right column of the image.

If this parameter is supported, an image corresponding to the specified region shall be returned in the response.

If this parameter specifies an ill-defined region, the origin server shall …

Note:

The origin server may not support this parameter. If this parameter is supported, an image corresponding to the specified region shall be returned with size corresponding to the specified normalized coordinates.

7.3.1.2.7 Window Center of the Rendered ImagewindowCenter={decimal} where ???

The “windowCenter” parameter controls the luminosity of the returned images, as defined in PS3.3. If the “windowWidth” parameter is present, this parameter shall also be present.

7.3.1.2.8 Window Width of the Rendered ImagewindowWidth={decimal} where???

The “windowWidth” parameter controls the contrast of the returned images, as defined in PS3.3. If the “windowCenter” parameter is present, this parameter shall also be present.

7.3.1.3 Header FieldsRequired: Accept

See Section 6.3.1.3

7.3.1.4 PayloadThe request payload shall be empty.

7.3.2 BehaviorThe origin server will render the target resource in an acceptable media type, and return it in the response payload.

7.3.3 ResponseThe response has the following format:

HTTP/1.1∎status-code∎reason-phrase↲Content-Type: rendered-media-type↲*header-field↲↲[payload]

1595

1600

1605

1610

1615

1620

1625

1630

A success response contains a status code of 200 (OK) and a single part payload containing the target resource in the rendered media type.

A failure response will contain a failure status code and possibly a Status Details payload.

7.3.3.1 Status CodesA success response shall have a status code of 200 (OK).

A failure response will have a failure status code from Table X.Y-Z.

7.3.3.2 Header FieldsRequired: Content-Type

See Section 6.3.1.3.2

7.3.3.3 PayloadA success payload contains a representation of the target resource in an acceptable media type.

A failure response may have an empty payload; however, it is recommended that it contains a Status Details document. See Section 7.2.3.3.

7.3.4 Media TypesSee Section 7.6 for the rendered media types supported by the URI service.

7.4 URI Retrieve Rendered Presentation State TransactionIn the URI Retrieve Rendered Presentation State (Rendered PS) Transaction, the user agent requests that the origin server render the target resource, which must be a presentation state instance, in an acceptable media type as specified by the presentation state and query parameters. The rendered representation is returned in the response.

7.4.1 RequestThe URI Retrieve Rendered Presentation State request message has the following format:

GET∎/?{requestType=WADO,study_uid,series_uid,object_uid}{&query*}∎HTTP/1.1 ↲Accept: rendered-media-type ↲*header-field ↲↲

The request has the following characteristics:

1. The target resource shall be a presentation state instance.2. Only rendered media types shall be specified in the Accept header field. The application/dicom media type

shall not be specified.3. This transaction provides additional query parameters that specify how the origin server should render the

target resource.

7.4.1.1 Query ParametersThis service requires the object identification query parameters specified in Section 7.2.1.2.1, but it also supports additional query parameters that specify how the target resource is rendered.

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

1. All parameters in this section are optional for the user agent and required for the origin server.2. The parameters only apply to image and video media types, as defined in Section X.X.

1635

1640

1645

1650

1655

1660

1665

3. The data types of the parameter values are defined in Section 6.3.1.2.2.4. Unless the “rows” or “columns” parameter is specified the returned image (or selected region) shall be in its

original size.

The following table contains a synopsis of the available rendering parameters:

Table 7.5-1: Retrieve Presentation State ParametersName Data Type Value Descriptionrows integer The number of rows in returned imagecolumns integer The number of columns in returned imageannotation keyword Annotations to be applied to imageimageQuality integer The quality of the lossy compression

7.4.1.1.1 Pixel Rows in Rendered Imagerows = {integer} where, range = 1 <= rows

See 7.4.1.2.2.

7.4.1.1.2 Pixel Columns in Rendered Imagecolumns = {integer} where, range = 0 <= columns

See 7.4.1.2.2.

7.4.1.1.3 Image Annotationannotation = {patient | technique}

See Section 7.4.1.2.1.

7.4.1.1.4 Image Qualityquality = {integer} where, range = 1 <= quality <= 100

See Section 7.4.1.2.8.

7.4.1.2 Header FieldsRequired: Accept

See Section 6.3.1.3.2.

7.4.1.3 PayloadThe request payload shall be empty.

7.4.2 BehaviorThe origin server will render the target presentation state instance in an acceptable media type, using the appropriate presentation state pipeline as specified in PS3.3, Section xxx.

If the annotation parameter is present, the specified annotations will be applied to the image after it has been rendered using the target presentation state, and before it has been encoded in an acceptable media type. The annotations may be applied as an overlay or they may be “burned in”.

1670

1675

1680

1685

1690

1695

If the Presentation Size Mode in the presentation state is SCALE TO FIT or TRUE SIZE, then the displayed area specified in the presentation shall be scaled to fit the size specified by the rows and/or columns parameters if present, otherwise the displayed area selected in the presentation state will be returned without scaling.

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 shall then be cropped to fit the size specified by the rows and/or columns parameters, if present.

Any Displayed Area relative annotations specified in the presentation state shall be 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.

Note: As specified in DICOM, the Presentation State will be in the same study as the images it applies to.

7.4.3 ResponseThe response has the following format:

HTTP/1.1∎status-code ∎reason-phrase ↲Content-Type: rendered-media-type ↲*header-field↲↲[payload]

A success response contains a status code of 200 (OK) and a single part payload containing the target resource in the rendered media type.

A failure response will contain a failure status code and possibly a Status Details payload.

7.4.3.1 Status CodeA success response shall have a status code of 200 (OK). A failure response shall have an appropriate failure status code from Table x.y.z.

7.4.3.2 Header FieldsRequired: Content-Type

See Section 6.3.1.3.2

7.4.3.3 PayloadA success payload shall have a single part that contains a representation of the target resource in an acceptable media type.

A failure response may have an empty payload; however, it is recommended that it contains a Status Details document. See Section 7.2.3.3.

8 WS* Web Services Protocol (WS)

Closed Issues# Issues

1700

1705

1710

1715

1720

1725

1730

Open Issues# Issues

Editorial Issues# Issues

Should we add message format to this section?

8.1 Transactions

Transaction MethodRequestPayload

ResponsePayload Description

RetrieveDocumentSet

GET Empty instance(s)or PD

This action retrieves a set of DICOM instances and other objects. This action corresponds to the IHE XDS-I.b transaction RAD-69. The DICOM instances are formatted in accordance with PS3.10, and encapsulated in a Web Services response.

RetrieveRenderedDocumentSet

GET Empty Renderedinstance(s)or PD

This action retrieves a set of DICOM instances that have been rendered into the requested format. For example, if rendering into JPEG was requested, these will be the JPEG renderings of the requested set of DICOM objects.

RetrievePresentationState

GET Empty 1 rendered PS instance

1735

1740

Retrieve Document Set Metadata

GET Empty Metadata instance(s)

This action retrieves a set of DICOM instances presented as an Infoset with the bulkdata removed. This service can retrieve either the full metadata, or a subset selected by XPath arguments. The XML encoding for the DICOM attributes is defined in PS3.19.

TODO

1. add parameters section to Retrieve Rendered Document Set2. Add Retrieve Rendered Presentation State3. Talk to Larry T. about other potential modifications

The DICOM Web Service defines several action types. An implementation shall support at least one of these actions. The three action types are:

1. Retrieve Imaging Document Set

This action retrieves a set of DICOM instances and other objects. This action corresponds to the IHE XDS-I.b transaction RAD-69. The DICOM instances are formatted in accordance with PS3.10, and encapsulated in a Web Services response.

2. Retrieve Rendered Imaging Document Set

This action retrieves a set of DICOM instances that have been rendered into the requested format. For example, if rendering into JPEG was requested, these will be the JPEG renderings of the requested set of DICOM objects.

3. Retrieve Imaging Document Set Metadata

This action retrieves a set of DICOM instances presented as an Infoset with the bulkdata removed. This service can retrieve either the full metadata, or a subset selected by XPath arguments. The XML encoding for the DICOM attributes is defined in PS3.19.

The Web Services actions shall be fully compliant with the Basic Profile of WS-I as defined in IHE IT Infrastructure Technical Framework Vol 2x Annex V. All <wsa:Action> elements shall have the mustUnderstand attribute set (mustUnderstand="1").

8.1.1 Acceptable Media TypeThe phrase “in an acceptable media type” when used with respect to the URI protocol means:

One of the media types contained in the Accept header field(s) of a request; One of the media types contained in the “ContentType” query parameter; or The default media type, if defined.

8.2 Retrieve Imaging Document Set

8.2.1 RequestThe specific Web Services parameters to be used for the Retrieve Imaging Document Set action shall be as follows, in the order that they would appear in the WSDL definition:

• The following types shall be imported (xsd:import) in the /definitions/types section:

• namespace="urn:ihe:rad:xdsi-b:2009", schema="XDSI.b_ImagingDocumentSource.xsd"

• The baseline XDS.b schema (namespace="urn:ihe:iti:xds-b:2007", schema="XDS.b_DocumentRepository.xsd")

• The baseline DICOM WADO-WS schema (namespace="urn:dicom:wado:ws:2011", schema="dicom.wado.ws.2011.xsd")

1745

1750

1755

1760

1765

1770

• The /definitions/message/part/@element attribute of the Retrieve Imaging Document Set Request message shall be an "iherad:RetrieveImagingDocumentSetRequest" as defined below.

• The /definitions/message/part/@element attribute of the Retrieve Imaging Document Set Response message shall be an "ihe:RetrieveDocumentSetResponse" as defined below.

• The /definitions/portType/operation/input/@wsaw:Action attribute for the Retrieve Imaging Document Set Request message shall be "urn:ihe:rad:2009:RetrieveImagingDocumentSet".

• The /definitions/portType/operation/output/@wsaw:Action attribute for the Retrieve Imaging Document Set Response message shall be "urn:ihe:iti:2007:RetrieveDocumentSetResponse".

• The /definitions/binding/operation/soap12:operation/@soapAction attribute shall be "urn:ihe:rad:2009:RetrieveImagingDocumentSet".

The <iherad:RetrieveImagingDocumentSetRequest/> element for use with the Retrieve Imaging Document Set Request Message is defined as:

• One or more <iherad:StudyRequest/> elements each of which includes a "studyInstanceUID" attribute identifying the study associated with the DICOM images/ objects being retrieved. Each <iherad:StudyRequest/> element shall contain:

• One or more <iherad:SeriesRequest/> elements each of which includes a "seriesInstanceUID" attribute identifying the series associated with the DICOM images/ objects being retrieved. Each <iherad:SeriesRequest/> element shall contain:

• One or more <ihe:DocumentRequest/> elements, each one representing an individual document that the requestor wants to retrieve from the Web Server. Each <ihe:DocumentRequest/> element contains:

• An optional <ihe:RepositoryUniqueId/> element that identifies the Web Server from which the document is to be retrieved. This value corresponds to XDSDocumentEntry.repositoryUniqueId. The RepositoryUniqueID is similar to a DICOM AETitle, but is a uniqueID assigned to the WADO-WS Web Server rather than a locally assigned string identifier. There will be a separate RepositoryUniqueID for each web service end point.

• A required <ihe:DocumentUniqueId/> element that identifies the document within the source. For example, this value could be a SOP Instance UID obtained from a Key Object Selection (KOS) instance.

• An optional <ihe:HomeCommunityId/> element. See the IHE Profiles for the definition and possible uses of this element.

• An optional <wado:Anonymize/> element.

• An optional <wado:FrameNumber/> element.

• A required <iherad:TransferSyntaxUIDList/> element that contains a list of one or more <ihe:TransferSyntaxUID> elements. Each of the <iherad:TransferSyntaxUID> elements represent one of the transfer syntax encodings that the Imaging Document Consumer is capable of processing.

8.2.2 ResponseA Web Server shall provide the document(s) indicated in the request. The Web Server shall return the document(s) or an error code when the document could not be returned. The pixel data shall be encoded using one of the DICOM transfer syntaxes included in the Retrieve Imaging Document Set Request Message. If the Imaging Document Source cannot encode the pixel data using any of the requested transfer syntaxes then an error status shall be returned.

8.2.2.1 Form of the ResponseThe <ihe:RetrieveDocumentResponse/> element for use with the Retrieve Imaging Document Set Response Message is defined as:

• A required /ihe:RetrieveDocumentSetResponse/rs:RegistryResponse element

• An optional sequence of <ihe:DocumentResponse/> elements containing

1775

1780

1785

1790

1795

1800

1805

1810

• An optional <ihe:HomeCommunityId/> element. The value of this element shall be the same as the value of the /RetrieveImagingDocumentSetRequest/StudyRequest/SeriesRequest/DocumentRequest/HomeCommunityId element in the Retrieve Document Set Request Message. If the <ihe:HomeCommunityId/> element is not present in the Retrieve Document Set Request Message, this value shall not be present.

• An optional <ihe:RepositoryUniqueId/> that identifies the Imaging Document Source from which the document is to be retrieved. The value of this element shall be the same as the value of the /RetrieveImagingDocumentSetRequest/StudyRequest/SeriesRequest/DocumentRequest/RepositoryUniqueId element in the original Retrieve Imaging Document Set Request Message. This value corresponds to XDSDocumentEntry.repositoryUniqueId.

• A required <ihe:DocumentUniqueId/> that identifies the document within the Imaging Document Source. The value of this element shall be the same as the value of the /RetrieveImagingDocumentSetRequest/StudyRequest/SeriesRequest/DocumentRequest/DocumentUniqueId element in the original Retrieve Imaging Document Set Request Message. This value corresponds to the SOP Instance UID in the Retrieve Document Request.

• A conditional <wado:FrameNumber/> that identifies the frame within the source document. It shall be present if and only if <wado:FrameNumber/> was in the request

• A required <ihe:Document/> element that contains the retrieved document as an XOP Infoset.

• A required <ihe:mimeType/> element that indicates the media type of the retrieved document.

The /RetrieveDocumentSetResponse/rs:RegistryResponse/@status attributes provides the overall status of the request: It shall contain one of the following values:

• urn:oasis:names:tc:ebxml-regrep:ResponseStatusType:Success

• urn:ihe:iti:2007:ResponseStatusType:PartialSuccess

• urn:oasis:names:tc:ebxml-regrep:ResponseStatusType:Failure

See ITI TF-2a: 4.1.13 Error Reporting for the interpretation of these values.

For each document requested in a /RetrieveImagingDocumentSetRequest/StudyRequest/SeriesRequest/DocumentRequest element:

• If the document is successfully retrieved (without warning) then no /RetrieveDocumentSetResponse/rs:RegistryResponse/rs:RegistryErrorList/ rs:RegistryError element shall be present and a /RetrieveDocumentSetResponse/DocumentResponse/Document element shall be returned containing the document as base64binary encoded data.

• If a warning is reported when retrieving the document, then a /RetrieveDocumentSetResponse/rs:RegistryResponse/rs:RegistryErrorList/ rs:RegistryError element shall be returned with:

• @severity is urn:oasis:names:tc:ebxml-regrep:ErrorSeverityType:Warning

• @errorCode is specified

• @codeContext contains the warning message

• @location contains the DocumentUniqueId of the document requested

• The document shall be returned in an instance of /RetrieveDocumentSetResponse/DocumentResponse/Document as base64binary encoded data. The returned document and warning are correlated via the DocumentUniqueId.

• If an error is reported when retrieving a document, then a /RetrieveDocumentSetResponse/rs:RegistryResponse/rs:RegistryErrorList/ rs:RegistryError element shall be returned with:

• @severity is urn:oasis:names:tc:ebxml-regrep:ErrorSeverityType:Error

1815

1820

1825

1830

1835

1840

1845

1850

• @errorCode is specified

• @codeContext contains the error message

• @location contains the DocumentUniqueId of the document requested

• No corresponding RetrieveDocumentSetResponse/DocumentResponse element shall be returned

The error conditions for failures and associated error codes are given below in section 6.4.4. These errors shall be detected and the associated errorCode returned if that error occurs. Additional errors defined in the ebRS standard, in ITI TF-2: 4.1.13 "Error Reporting", and defined by the implementer may be returned.

8.2.2.2 JPIPIf the Web Client specifies a transfer syntax field of 1.2.840.10008.1.2.4.94 (DICOM JPIP Referenced Transfer Syntax) or 1.2.840.10008.1.2.4.95 (DICOM JPIP Referenced Deflate Transfer Syntax), and the Web Server supports the requested transfer syntax the following behavior is expected:

• If the DICOM Image Object(s) already have the same JPIP transfer syntax as the one indicated in the request, the Retrieve Imaging Document Set Response shall include the DICOM Image Objects unchanged.

• If the DICOM Image Object(s) have a transfer syntax that differs from that of the request, the Retrieve Imaging Document Set Response shall include the DICOM image with the transfer syntax changed to the requested transfer syntax. In addition, the pixel data Attribute (7FE0,0010 tag) will have been removed and replaced with a Pixel Data Provider URL (0028,7FE0 tag). The URL represents the JPIP request and will include the specific target information.

• Upon receipt of this Retrieve Imaging Document Set Response, the Imaging Document Consumer may request the pixel data from the pixel data provider using the supplied URL. Additional parameters required by the application may be appended to the URL when accessing the pixel data provider.

• For example, a JPIP request for a 200 by 200 pixel rendition of the entire image can be constructed from the Pixel Data Provider URL as follows:

• Pixel Data Provider URL (0028,7FE0) = https://server.xxx/jpipserver.cgi?target=imgxyz.jp2,

• URL Generated by the application = https://server.xxx/jpipserver.cgi?target=imgxyz.jp2&fsiz=200,200

8.3 Retrieve Rendered Imaging Document Set

8.3.1 RequestThe specific Web Services parameters to be used for the Retrieve Rendered Imaging Document Set action shall be as follows, in the order that they would appear in the WSDL definition:

• The following types shall be imported (xsd:import) in the /definitions/types section:

• namespace="urn:ihe:rad:xdsi-b:2009", schema="XDSI.b_ImagingDocumentSource.xsd"

• The baseline XDS.b schema (namespace="urn:ihe:iti:xds-b:2007", schema="XDS.b_DocumentRepository.xsd")

• The baseline DICOM WADO-WS schema (namespace="urn:dicom:wado:ws:2011", schema="dicom.wado.ws.2011.xsd")

• The /definitions/message/part/@element attribute of the Retrieve Rendered Imaging Document Set Request message shall be a "wado:RetrieveRenderedImagingDocumentSetRequest" as defined below.

• The /definitions/message/part/@element attribute of the Retrieve Rendered Imaging Document Set Response message shall be a "wado:RetrieveRenderedImagingDocumentSetResponse" as defined below.

• The /definitions/portType/operation/input/@wsaw:Action attribute for the Retrieve Rendered Imaging Document Set Request message shall be "urn:dicom:ws:wado:2011:RetrieveRenderedImagingDocumentSet".

1855

1860

1865

1870

1875

1880

1885

1890

• The /definitions/portType/operation/output/@wsaw:Action attribute for the Retrieve Imaging Document Set Response message shall be "urn:dicom:ws:wado:2011:RetrieveRenderedImagingDocumentSetResponse".

• The /definitions/binding/operation/soap12:operation/@soapAction attribute shall be "urn:dicom:ws:wado:2011:RetrieveRenderedImagingDocumentSet".

The <wado:RetrieveRenderedImagingDocumentSetRequest/> element for use with the Retrieve Imaging Document Set Request Message is defined as:

• One or more <wado:StudyRequest/> elements each of which includes a Study Instance UID" attribute identifying the study associated with the DICOM images/ objects being retrieved. Each <iherad:StudyRequest/> element shall contain:

• One or more <wado:SeriesRequest/> elements each of which includes a Series Instance UID attribute identifying the series associated with the DICOM images/ objects being retrieved. Each <iherad:SeriesRequest/> element shall contain:

• One or more <wado:RenderedDocumentRequest/> elements, each one representing an individual document that the requestor wants to retrieve from the Web Server. Each <wado:DocumentRequest/> element contains:

• An optional <ihe:RepositoryUniqueId/> element that identifies the Web Server from which the document is to be retrieved. This value corresponds to XDSDocumentEntry.repositoryUniqueId. The RepositoryUniqueID is similar to a DICOM AETitle, but is a uniqueID assigned to the WADO-WS Web Server rather than a locally assigned string identifier. There will be a separate RepositoryUniqueID for each web service end point.

• A required <ihe:DocumentUniqueId/> element that identifies the document within the source. This value corresponds to the SOP Instance UID referenced within the DICOM manifest.

• An optional <ihe:HomeCommunityId/> element that corresponds to the home attribute of the Identifiable class in ebRIM.

• An optional <wado:Annotation/> element.

• An optional <wado:Rows/> element.

• An optional <wado:Columns/> element.

• An optional <wado:Region/> element.

• An optional <wado:WindowCenter/> element.

• An optional <wado:WindowWidth/> element.

• An optional <wado:ImageQuality/> element.

• An optional <wado:PresentationUID/> element.

• An optional <wado:PresentationSeriesUID/> element.

• An optional <wado:Anonymize/> element

• An optional <wado:FrameNumber/> element.

• A required <wado:ContentTypeList/> element that contains a list of one or more <wado:ContentType> elements.

• An optional <wado:CharsetList/> element that contains a list of one or more <wado:Charset> elements.

8.3.1.1 ParametersThis service requires the object identification query parameters specified in Section 7.2.1.2.1, but it also supports additional query parameters that specify how the target resource is rendered.

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

5. All parameters in this section are optional for the user agent and required for the origin server.6. The parameters only apply to image and video media types, as defined in Section X.X.

1895

1900

1905

1910

1915

1920

1925

1930

7. The data types of the parameter values are defined in Section 6.3.1.2.2<#6.3.1.2.2>.8. Unless the “rows” or “columns” parameter is specified the returned image (or selected region) shall be in its

original size.

The following table contains a synopsis of the available rendering parameters:

Table 8.2-X: Rendering Query ParametersName Data Type Value DescriptionFrameNumber integer The number of the frame to retrieveRegion decimal Four decimal numbers that specify the regionRows integer The number of rows in returned imageColumns integer The number of columns in returned imageWindowCenter decimal The luminosity of the imageWindowWidth decimal The contrast of the imageAnnotation keyword Annotations to be applied to imageImageQuality integer The quality of the lossy compression

Annotation on the Object

Annotation = {patient / technique}

The “Annotation” parameter specifies that annotations should be applied to the returned image. Its value shall be a non-empty, comma-separated list of one or more of the following items:

patient – displays patient information (e.g., patient name, birth date, etc.)

technique – displays technique information (e.g., image number, study date, image position, etc.).

When used in conjunction with the region parameter, it shall be applied after the selection of the region.

The exact nature and presentation of the annotation is determined by the origin server.

8.3.1.1.1 Pixel Rows in Rendered ImageRows = {integer} where 0 <= Rows

The “Rows” parameter specifies the height in pixels of the rendered image. The returned image shall have the same aspect ratio as the original image.

N.B: The user agent may specify “rows” or “columns”, but should not specify both. If both are specified, then the origin server shall scale the returned images, maintaining their original aspect ratio, until either the image width is the same as the viewport width or the image depth is the same as the viewport depth, whichever comes first. In other words, viewport scaling makes the image(s) as large as possible without overflowing the viewport area.

8.3.1.1.2 Pixel Columns in Rendered ImageColumns = {integer} where 0 <= Columns

The “columns” parameter specifies the width in pixels of the rendered image. The returned image shall have the same aspect ratio as the original image.

See N.B. in 7.4.1.2.2.

8.3.1.1.3 Region RenderedRegion = {xMin,yMin,xMax,yMax} where 0.0 <= top < bottom <= 1.0, and

0.0 <= left < right <= 1.0.

The “Region” parameter specifies a rectangular region of the target resource. Its value shall be a list of four comma separated, positive decimal strings, representing in the following order:

1935

1940

1945

1950

1955

1960

xMIN the top row of the region, Ymin the left column of the region, xMAX the bottom row of the region, YmAX the right column of the region,

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

0.0 corresponds to the top row and left column of the image,1.0 corresponds to the bottom row and right column of the image, and

If this parameter is supported, an image corresponding to the specified region shall be returned in the response.

If this parameter specifies an ill-defined region, the origin server shall …

Note:

The origin server may not support this parameter. If this parameter is supported, an image corresponding to the specified region shall be returned with size corresponding to the specified normalized coordinates.

8.3.1.1.4 Window Center of the Rendered ImageWindowCenter={decimal} where ???

The “WindowCenter” parameter controls the luminosity of the returned images, as defined in PS3.3. If the “WindowWidth” parameter is present, this parameter shall also be present.

8.3.1.1.5 Window Width of the Rendered ImageWindowWidth={decimal} where???

The “WindowWidth” parameter controls the contrast of the returned images, as defined in PS3.3. If the “WindowCenter” parameter is present, this parameter shall also be present.

8.3.1.1.6 Frame NumberFrameNumber = {integer} where 0 <= integer <= total number of frames

The “FrameNumber” parameter specifies the frame number of an image within the multi-frame instance specified by the target resource. It shall be ignored for all objects other than multi-frame objects.

8.3.1.1.7 Image QualityImageQuality = {integer} where 1 <= integer <= 100

The “ImageQuality” parameter controls the relative quality of lossy compressed images. Its value is an Integer string that ranges from 1 to 100 inclusive, 100 having the best quality.

Note

The meaning of this parameter depends on the media type and is determined by the origin server.

8.3.2 ResponseAn Web Server shall render and then provide the document(s) indicated in the request. The Web Server shall return the rendered documents or an error code when the document could not be returned. The rendered forms shall be the subset specified, and in the format requested. If the Imaging Document Source cannot render the pixel data in that manner then an error status shall be returned.

The <wado:RetrieveRenderedImagingDocumentResponse/> element for use with the Retrieve Imaging Document Set Response Message, Retrieve Rendered Imaging Document Set Response Message and Retrieve Imaging Document Set Metadata Response Message is defined as:

1965

1970

1975

1980

1985

1990

1995

2000

• A required /ihe:RetrieveDocumentSetResponse/rs:RegistryResponse element

• An optional sequence of <wado:RenderedDocumentResponse/> elements containing:

• A <ihe:HomeCommunityId/> element. The value of this element shall be the same as the value of the StudyRequest/SeriesRequest/DocumentRequest/HomeCommunityId element in the Request Message. If the <ihe:HomeCommunityId/> element is not present in the Request Message, this value shall not be present.

• A required <ihe:RepositoryUniqueId/> that identifies the Imaging Document Source from which the document was retrieved. The value of this element shall be the same as the value of the StudyRequest/SeriesRequest/DocumentRequest/RepositoryUniqueId element in the original Request Message.

• A required <wado:SourceDocumentUniqueId/> that identifies the source document. The value of this element shall be the same as the value of the StudyRequest/SeriesRequest/DocumentRequest/DocumentUniqueId element in the original Request Message. This value identifies the source, and is not an ID for the resulting rendered document.

• A conditional <wado:FrameNumber/> that identifies the frame within the source document. It shall be present if and only if <wado:FrameNumber/> was in the request.

• A required <wado:Annotation/> element that contains the actual value used.

• A required <wado:Rows/> element that contains the actual value used.

• A required <wado:Columns/> element that contains the actual value used.

• A required <wado:Region/> element that contains the actual value used.

• A required <wado:WindowCenter/> element that contains the actual value used.

• A required <wado:WindowWidth/> element that contains the actual value used.

• A required <wado:ImageQuality/> element that contains the actual value used.

• A required <wado:PresentationUID/> element that contains the actual value used if a PresentationUID was used.

• A required <wado:PresentationSeriesUID/> element that contains the actual value used if a PresentationSeriesUID was used.

• An optional <wado:Anonymize/> element that shall be present if the rendered instance was anonymized.

• A required <ihe:Document/> element that contains the rendered document encoded as an XOP Infoset.

• A required <ihe:mimeType/> element that indicates the media type of the retrieved document.

The /RetrieveDocumentSetResponse/rs:RegistryResponse/@status attributes provides the overall status of the request: It shall contain one of the following values:

• urn:oasis:names:tc:ebxml-regrep:ResponseStatusType:Success

• urn:ihe:iti:2007:ResponseStatusType:PartialSuccess

• urn:oasis:names:tc:ebxml-regrep:ResponseStatusType:Failure

For each document requested in a /RetrieveRenderedImagingDocumentSetRequest/StudyRequest/SeriesRequest/DocumentRequest element:

• If the document is successfully rendered (without warning) then no /RetrieveRenderedImagingDocumentSetResponse/rs:RegistryResponse/rs:RegistryErrorList/ rs:RegistryError element shall be present and a /RetrieveRenderedImagingDocumentSetResponse/DocumentResponse/Document element shall be returned containing the rendered document as base64binary encoded data.

• If a warning is reported when retrieving the document, then a /RetrieveRenderedImagingDocumentSetResponse/rs:RegistryResponse/rs:RegistryErrorList/ rs:RegistryError element shall be returned with:

2005

2010

2015

2020

2025

2030

2035

• @severity is urn:oasis:names:tc:ebxml-regrep:ErrorSeverityType:Warning

• @errorCode is specified

• @codeContext contains the warning message

• @location contains the DocumentUniqueId of the document requested

• The rendered document shall be returned in an instance of /RetrieveRenderedImagingDocumentSetResponse/DocumentResponse/Document as base64binary encoded data. The returned document and warning are correlated via the DocumentUniqueId.

• If an error is reported when retrieving a document, then a /RetrieveRenderedImagingDocumentSetResponse/rs:RegistryResponse/rs:RegistryErrorList/ rs:RegistryError element shall be returned with:

• @severity is urn:oasis:names:tc:ebxml-regrep:ErrorSeverityType:Error

• @errorCode is specified

• @codeContext contains the error message

• @location contains the DocumentUniqueId of the document requested

• No corresponding RetrieveRenderedImagingDocumentSetResponse/DocumentResponse element shall be returned

The error conditions for failures and associated error codes are given below in section 6.4.4. These errors shall be detected and the associated errorCode returned if that error occurs. Additional errors defined in the ebRS standard, in ITI TF-2: 4.1.13 "Error Reporting", and defined by the implementer may be returned.

8.4 Retrieve Rendered Presentation State RequestTODO

8.5 Retrieve Imaging Document Set Metadata Request

8.5.1 RequestThe specific Web Services parameters to be used for the Retrieve Imaging Document Set Metadata action shall be as follows, in the order that they would appear in the WSDL definition:

• The following types shall be imported (xsd:import) in the /definitions/types section:

• namespace="urn:ihe:rad:xdsi-b:2009", schema="XDSI.b_ImagingDocumentSource.xsd"

• The baseline XDS.b schema (namespace="urn:ihe:iti:xds-b:2007", schema="XDS.b_DocumentRepository.xsd")

• The baseline DICOM WADO-WS schema (namespace="urn:dicom:wado:ws:2011", schema="dicom.wado.ws.2011.xsd")

• The /definitions/message/part/@element attribute of the Retrieve Imaging Document Information Set Request message shall be defined an "wado:RetrieveImagingDocumentSetInformationRequest" as defined below.

• The /definitions/message/part/@element attribute of the Retrieve Imaging Document Set Information Response message shall be defined an "wado:RetrieveImagingDocumentSetInformationResponse" as defined below.

• The /definitions/portType/operation/input/@wsaw:Action attribute for the Retrieve Imaging Document Set Information Request message shall be "urn:wado:2011:RetrieveImagingDocumentSetInformation".

2040

2045

2050

2055

2060

2065

2070

• The /definitions/portType/operation/output/@wsaw:Action attribute for the Retrieve Imaging Document Set Information Response message shall be "urn:wado:2011:RetrieveImagingDocumentSetInformationResponse".

• The /definitions/binding/operation/soap12:operation/@soapAction attribute shall be "urn:wado:2011:RetrieveImagingDocumentSetInformation".

The <wado:RetrieveImagingDocumentSetInformationRequest/> element for use with the Retrieve Imaging Document Set Request Message is defined as:

• One or more <wado:StudyRequest/> elements each of which includes a "studyInstanceUID" attribute identifying the study associated with the DICOM images/objects being retrieved. Each <iherad:StudyRequest/> element shall contain:

• One or more <wado:SeriesRequest/> elements each of which includes a "seriesInstanceUID" attribute identifying the series associated with the DICOM images/objects being retrieved. Each <iherad:SeriesRequest/> element shall contain:

• One or more <wado:DocumentInformationRequest/> elements, each one representing an individual document that the requestor wants to retrieve from the Web Server. Each < wado:DocumentInformationRequest /> element contains:

• · An required <ihe:RepositoryUniqueId/> element that identifies the Web Server from which the document is to be retrieved. This value corresponds to XDSDocumentEntry.repositoryUniqueId. The RepositoryUniqueID is similar to a DICOM AE Title, but is a uniqueID assigned to the WADO-WS Web Server rather than a locally assigned string identifier. There will be a separate RepositoryUniqueID for each web service end point.

• A required <ihe:DocumentUniqueId/> element that identifies the document within the source. For example, this value could be a SOP Instance UID obtained from a Key Object Selection (KOS) instance.

• An optional <ihe:HomeCommunityId/> element. See the IHE Profiles for the definition and possible uses of this element.

• An optional <wado:Anonymize/> element

• A required <wado:XPath/> that contains the text corresponding to the XPath "filter" applied to the Native DICOM Model transposition of the object, as defined in PS3.19.

Note

If the requested filter is "/", then all of the metadata is requested.

8.5.2 ResponseA Web Server shall extract information from each document specified in a Document Set Information Request. This shall be done by the logical equivalent of:

1. convert the non-pixel data for each of the requested data into an XML encoded form

2. apply each of the wado:XPath elements to this XML encoded form

3. provide the XPath response as part of the Document Set Information Response.

See PS3.19 for details on conversion to XML encoded form.

The Web Server shall return the XPath results or an error code when the document could not be processed.

The <wado:RetrieveImagingDocumentSetInformationResponse/> element for use with the Retrieve Imaging Document Set Response Message is additionally defined as:

• A required /wado:RetrieveImagingDocumentSetInformationResponse/rs:RegistryResponse element

• An optional sequence of <wado:DocumentInformationResponse/> elements containing:

• A <ihe:HomeCommunityId/> element. The value of this element shall be the same as the value of the StudyRequest/SeriesRequest/DocumentRequest/HomeCommunityId element in the Request Message. If the <ihe:HomeCommunityId/> element is not present in the Request Message, this value shall not be present.

2075

2080

2085

2090

2095

2100

2105

2110

• A required <ihe:DocumentUniqueId/> that identifies the document within the Web Server. The value of this element shall be the same as the value of the StudyRequest/SeriesRequest/DocumentRequest/DocumentUniqueId element in the original Request Message. This value corresponds to the SOP Instance UID.

• A conditional <wado:FrameNumber/> that identifies the frame within the source document. It shall be present if and only if <wado:FrameNumber/> was in the request.

• One <wado:XPathResponseList/> containing:

• A required <wado:XPathResponse> that contains the XPath results for each <wado:XPath/> elements, in the same order as in the request encoded as an XOP Infoset. The response element shall be empty if there was no XPath match.

The /RetrieveImagingDocumentSetInformationResponse/rs:RegistryResponse/@status attributes provides the overall status of the request: It shall contain one of the following values:

• urn:oasis:names:tc:ebxml-regrep:ResponseStatusType:Success

• urn:ihe:iti:2007:ResponseStatusType:PartialSuccess

• urn:oasis:names:tc:ebxml-regrep:ResponseStatusType:Failure

For each document requested in a /RetrieveImagingDocumentSetInformationRequest/StudyRequest/SeriesRequest/DocumentRequest element:

• If the document is successfully retrieved (without warning) then no /RetrieveImagingDocumentSetInformationResponse/rs:RegistryResponse/rs:RegistryErrorList/ rs:RegistryError element shall be present and a /RetrieveImagingDocumentSetInformationResponse/DocumentResponse/Document element shall be returned containing the document as base64binary encoded data.

• If a warning is reported when retrieving the document, then a /RetrieveImagingDocumentSetInformationResponse/rs:RegistryResponse/rs:RegistryErrorList/ rs:RegistryError element shall be returned with:

• @severity is urn:oasis:names:tc:ebxml-regrep:ErrorSeverityType:Warning

• @errorCode is specified

• @codeContext contains the warning message

• @location contains the DocumentUniqueId of the document requested

• The document shall be returned in an instance of /RetrieveDocumentSetResponse/DocumentResponse/Document as base64binary encoded data. The returned document and warning are correlated via the DocumentUniqueId.

• If an error is reported when retrieving a document, then a /RetrieveImagingDocumentSetInformationResponse/rs:RegistryResponse/rs:RegistryErrorList/ rs:RegistryError element shall be returned with:

• @severity is urn:oasis:names:tc:ebxml-regrep:ErrorSeverityType:Error

• @errorCode is specified

• @codeContext contains the error message

• @location contains the DocumentUniqueId of the document requested

• No corresponding RetrieveDocumentSetResponse/DocumentResponse element shall be returned

The error conditions for failures and associated error codes are given below in section 6.4.4. These errors shall be detected and the associated errorCode returned if that error occurs. Additional errors defined in the ebRS standard, in ITI TF-2: 4.1.13 "Error Reporting", and defined by the implementer may be returned.

2115

2120

2125

2130

2135

2140

2145

2150

8.6 WS Media TypesTable 8.6-1 contains default, required, recommended, and optional media types for the WS service. The default and required media types shall be supported by an implementation of this service.

Table 8.6-1: URI and WS Media TypesResource Category Media Type Requirement ReferenceDICOM application/dicom default RFC3240

Single Frame Image image/jpeg default ISO/IEC 10918image/gif requiredimage/png requiredimage/jp2 required

Multi-Frame ImageVideo

image/gif recommendedvideo/mpeg recommended

Text Objects text/html requiredtext/plain requiredtext/rtf recommendedtext/xml recommendedapplication/pdf recommended

Other Objects application/dicom required RFC3240

other media types

optional

All requests should specify the acceptable media types using the Accept header field. If no media type is specified, the response payload shall contain a representation in the default media type for the target resource’s category. If the resource category, of the target resource, has no default media type then the response shall use the application/dicom media type.

When an image/jpeg representation is returned, it shall be encoded using the JPEG baseline lossy 8 bit Huffman encoded non-hierarchical non-sequential process ISO/IEC 10918. [ref]

It is recommended that the Server also support a "CDA" media type, in conformance to HL7 CDA R2, e.g., text/xml.

The origin server may support other media types. All media types supported should be included in the conformance statement and the response from the Capabilities Service.

The media types supported by the origin server should be included in the conformance statement, and in the Retrieve Capabilities response.

8.7 Error CodesThe following errorCodes are defined and shall be used to report any of the associated error and warning situations. Other errorCodes may be present for other error and warning situations.

Table 8.4-1. Error CodesError Code Error Situation

urn:dicom:wado:0001 Unable to anonymize the requested instance(s).

urn:dicom:wado:0002 Web Server does not support anonymization.

urn:dicom:wado:0003 The requested instance(s) are not immediately available, but can be made available by manual request.

urn:dicom:wado:0004 Instance is no longer available, e.g., document retention rules have caused it to be removed

2155

2160

2165

2170

Error Code Error Situation

or relocated.

urn:dicom:wado:0005 The requested instance(s) cannot be returned because the size or count exceeds resource limits.

urn:dicom:wado:0006 Web Server does not support the requested format or transfer syntax.

urn:dicom:wado:0007 The requested instance(s) cannot be provided in the requested format or transfer syntax.

urn:dicom:wado:0008 Single image format is not available for multi-frame images.

urn:dicom:wado:0009 Identifier does not match SOP Class (see PS3.7 C-MOVE)

urn:dicom:wado:0010 Inconsistent identifiers, e.g., Study and Series are correct but Series is in a different Study (see PS3.7 C-MOVE)

urn:dicom:wado:0011 SOP Class not supported (see PS3.7 C-MOVE)

urn:dicom:wado:0012 Invalid parameter value in request (see PS3.7 C-MOVE)

urn:dicom:wado:0013 Unsupported parameter in request (see PS3.7 C-MOVE)

urn:dicom:wado:0014 Processing Failure (see PS3.7 C-MOVE)

urn:dicom:wado:0015 Study Instance UID not known

urn:dicom:wado:0016 Series Instance UID not known

urn:dicom:wado:0017 Document UID not known

urn:dicom:wado:0018 Out of range Frame number

urn:dicom:wado:0019 Presentation UID not known

urn:dicom:wado:0020 Presentation Series UID not known

9 Restful Web Services Protocol (RS)Closed Issues

# Issues

Open Issues# Issues1 Should the capabilities service be redefined as a transaction that each service must implement? There are

currently two services: 1) studies and 2) worklistShould we generalize the Worklist subscriptions into a general set of notification transactions that can be implemented for each service?

2175

Should we define a de-identification transaction for the RS Storage service?Should we define a de-identification transaction for the RS Worklist service?Should the origin server be required to return an error status if there is no acceptable media type as well as a payload describing the supported media types?Should we defined the media type */* to mean that the origin server can return any media type it likes or the default media type for the resource category, or should we define other default media types. If media types are specified and no acceptable media type is available then error no acceptable media type.

Proposed CPs# Issues

The Store transactions for both Storage and Worklist services should be update to return the following status codes:

200 OK: The target payload was successfully stored and there is a non-empty response payload201 Created: The target payload did not exist and was successfully stored, Content-Length or

Content-Encoding tells whether there is a payload or not202 Accepted: The target payload was successfully receive, but has not been or only partially

processed. The payload should contain a Status Details document describing the current status. The user agent can use a Retrieve at a later time to determine the status

204 No Content: The target payload was successfully stored and the payload is empty.206 Partial Success: The target payload was partially successfully stored and there may be a Status

Details payload

Editorial Issues# Issues

9.1 RS Services OverviewThe RS Protocol is composed of the following services:

Table 9.2-X: RS Protocol ServicesService Name Description

2180

Studies Returns one or more DICOM objects specified by the target resource in an acceptable media types.

Worklist Returns one or more rendered images specified by the target resource in an acceptable media type.

9.2 Target ResourcesThe target resources of the RS Protocol are typically DICOM Information Entities; but they may be other entities. The general format of resource URI templates is:

/resource-type/{resource-id]/resource-subtype/{resource-id}/…{?query}

Where,

resource-type is a literal string, for example “studies”, and

resource-id is a variable that identifies a specific resource

9.3 Transaction OverviewEach transaction is composed of a request message and a response message, sometimes referred to as a request/response pair.

9.3.1 Request Message FormatAll RS Protocol request messages have the following format:

method∎{/resource }{?query}∎version↲*header-field↲↲[payload]

Where,

method The method used by the transaction.

{/resource} A relative URI that specifies the path to the target resource. The base URI is the absolute URI of the service.

{?query} The part of the URI that specifies optional query parameters;

version The HTTP version, either ‘HTTP/1.1’, ‘HTTPS/1.1’, ‘HTTP/2’ or ‘HTTPS/2’.

*header-field A list of request header fields, one per line.

[payload] An optional payload, containing a sequence of octets, which is defined by the transaction.

Note

1. The ‘∎’ in the message above indicates a space character.

2. The ’↲’ in the message above indicate an ASCII carriage-return followed by a linefeed character.

2. HTTP/2 has the same high level syntax as HTTP/1.1. The principle difference is in how the data is framed and transported between the client and server. See [refs < http://en.wikipedia.org/wiki/HTTP/2>, and <https://datatracker.ietf.org/doc/draft-ietf-httpbis-http2>].

2185

2190

2195

2200

2205

2210

9.3.1.1 Resources

9.3.1.2 Query ParametersEach service specifies the query parameters that it supports.

9.3.1.3 Header Fields Required: Accept

See Section 6.3.1.3Payload

9.3.1.4 PayloadWhether or not a request has a payload depends on the method,

9.3.2 BehaviorThe specific behavior of the origin server is defined by each transaction. The behavior section should include information about the target resource, such as how it is retrieved or modified; how the representation is decided or transformed; the criteria for success or error in the response; and whether or not the response has a payload.

9.3.3 ResponseAll RS Protocol response messages have the following format:

version∎status-code∎reason-phrase↲*header-field↲↲[payload]

Where,

version specifies the HTTP version,;

status-code is a three digit code describing the result of the request;

reason-phrase exists for the sole purpose of associating a textual description with the status code;

*header-field↲ a list of request header fields, one per line;

[payload] an optional payload, which is a sequence of octets, that is defined by the transaction.

Note

See the notes in Section 9.4.1.

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

Table 9.4-X: Response Status CodesStatus Code Phrase Description

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

200 Success Indicates that all target resource representations are contained in the payload.

2215

2220

2225

2230

2235

2240

2245

201 Created Indicates that the request has been fulfilled and has resulted in one or more new resources being created.

202 Accepted Indicates that the request has been accepted for processing, but the processing has not been completed. The user agent can use a

203 Non-Authoritative Information

Indicates that 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.

204 No-Content Indicates that the server has successfully fulfilled the request and that 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.

205 Reset Content Indicates that 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. This code could be returned in response to a Worklist Service Create Work Item request.

Warning 206 Partial Content Indicates that some, but not all, of the target resource representations are contained in the payload.This could be because the origin server does not support the media types, transfer syntaxes for some but not all requested content.

Client Error

The 4xx (Client Error) class of status code indicates that the client seems to have erred. Except when responding to a HEAD request, the server SHOULD send a representation containing an explanation of the error situation, and whether it is a temporary or permanent condition.

400 Bad Request Indicates that 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 …). Also indicates that no instances were stored due to bad message syntax.

401 Unauthorized Indicates that the request has not been applied because it lacks valid authentication credentials for the target resource. The server generating a 401 response MUST send a WWW-Authenticate header field (Section 4.1) containing at least one challenge applicable to the target resourse.

403 Forbidden Indicates that 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.

404 Not Found Indicates that 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 is preferred over 404.

405 Method Not Allowed Indicates that the method received in the request-line is known by the origin server but not supported by the target resource. The origin server MUST generate an Allow header field in a 405 response containing a list of the target resource's currently supported methods.

406 Not Acceptable Indicates that the target resource does not have a representation that would be acceptable to the user agent, according to the content negotiation header fields in the request, and the server is unwilling to supply a default representation.The server SHOULD generate a payload containing a list of available representation characteristics (media types) and corresponding resource identifiers from which the user or user agent can choose the one most appropriate.

409 Conflict Indicates that 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 might be able to resolve the conflict and resubmit the request. The server SHOULD generate a payload that includes enough information for a user to recognize the source of the conflict.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 SOP Instance mismatch).I

410 Gone Indicates that access to the target resource is no longer available at the origin server and that this condition is likely to be permanent. If the origin server does not know, or has no facility to determine, whether or not the condition is permanent, the status code 404 (Not Found) ought to be used instead.

411 Length Required Indicates that the server refuses to accept the request without a defined Content-Length.

413 Payload Too Large Indicates that the server is refusing to process a request because the request payload is larger than the server is willing or able to process.

414 URI Too Long Indicates that the server is refusing to service the request because the request-target (Section 5.3 of [RFC7230]) is longer than the server is willing to interpret.

415 Unsupported Media Type

Indicates that the origin server does not support the Content-Type in the request payload.

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. Except when responding to a HEAD request, the server SHOULD send a representation containing an explanation of the error situation, and whether it is a temporary or permanent condition.

500 Internal Server Error

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

501 Not Implemented Indicates that the server does not support the functionality required to fulfill the request.

503 Service Unavailable Indicates that the 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

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

9.3.3.2 Header FieldsRequired:

Content-Type

Required if there is no Transfer-Encoding header field:

Content-Length

Required if a new resource has been created:

Location

Optional:

Content-LocationContent-EncodingWarning

See Section 6.3.1.3.2

9.3.4 Response Payload

9.3.5 PayloadBoth requests and responses can have payloads. Messages that have a payload typically have Representation and Payload Header Fields. The RS protocol can have single part or multipart payloads depending on the media type. See Section 6 for details.

Content-Type and Content-Location header fields. There are two basic payload structures: single part and multi-part.

Each part in a multi-part payload shall start with a boundary string, followed by Content-Type and Content-Location header fields, followed by either a Content-Length or a Transfer-Encoding header field, optionally followed by a Content-Description header field.

9.3.6 RS Media TypesTable 6.3-2 contains default, required, recommended, and optional media types for the URI service. The RS protocol does not have any default media types. The origin server determines the media type of the response based on the Accept header field and the target resource. If no Accept header field is contained in the request, the media type of the response payload, if any, shall be the default media subtype. If not default media type is defined for the resource’s category then the origin server shall return a 4zz error and should include a Status Details document that describes the media types available for the resource type.

Table 9.3-x: RS Media TypesResource Category Media Type Requirement ReferenceDICOM application/dicom default RFC3240

application/dicom+json requiredapplication/dicom+xml requiredapplication/json required

Image (single frame) image/jpeg default ISO/IEC 10918Image/dicom recommendedImage/dicom+jpg recommendedImage/dicom+jpg-ls recommendedimage/jp2 requiredimage/gif required

2250

2255

2260

2265

2270

2275

image/png requiredImage (multi-frame) image/dicom+jpx recommended

Image/gif recommendedVideo video/mpeg recommended

Video/mp4 recommendedText Objects text/html required

text/plain requiredtext/rtf recommendedtext/xml recommendedapplication/pdf recommended

Other Objects application/dicom required RFC3240

other media types optional

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

Note

The media types supported by the origin server should be included in the conformance statement and in the Capabilities Description document.

The media type defines the format of the representation(s) contained in the payload

9.3.6.1 Acceptable Media TypeThe term “acceptable media type” is used throughout this part of the Standard. It means:

a media type that is contained in the Accept header field of the request; or, if the request has no Accept header field it means the default media type for the target resource.

If no default subtype is defined then the media type will be determined by the origin server. If the origin server supports no acceptable media type it shall return an error response. If there is no default subtype then the origin server should return an error status code of 415 (Unsupported Media Type).

The phrase “an acceptable media type” is used throughout the RS protocol to mean:

One of the media types contained in the Accept header field(s) of a request; or If the request does not contain a request header, the default media type for the resource, if defined.

Some resources contain more than one type of object, for example studies typically have images and reports (text base objects). The user agent should include image, muli-frame image and text base media types in the accept header.

9.3.6.2 Multipart Related Media Type

9.3.6.3 Imaging Media Types and Transfer SyntaxOrigin servers implement the RS protocol shall be prepared to handle transfer syntax parameters for all imaging media types. The syntax is:

*(media-type *(“;” “transfer-syntax” “=” {transfer-syntax} ) )

For example, an Accept header field might look as follows:

Accept: application/dicom; transfer-syntax=1.2.840.10008.1.2.4.70, ; transfer-syntax=1.2.840.10008.1.2.4.71

2280

2285

2290

2295

2300

2305

9.4 Retrieve Capabilities TransactionThe Retrieve Capabilities transaction requests that the request target, which shall be an RS service, returns a Capabilities Description document, which is machine readable. The Capabilities Description document describes the transactions, resources, representations, etc. supported by the service.

All RS origin servers shall support the Retrieve Capabilities transaction. The Capabilities Description document shall describe the service in as much detail as possible.

The Retrieve Capabilities transaction supports the transaction in Table 9.8-1.

Table 9.4-1: Retrieve Capabilities TransactionTransaction URI Template DescriptionRetrieve Capabilities / Retrieve a Capabilities Description document from the service in an

acceptable media type.

9.4.1 RequestThe Retrieve Capabilities request uses the OPTIONS method and has the following format:

OPTIONS∎/∎version↲*header-field↲↲

9.4.1.1 ResourcesThe only target-resource supported by this transaction is the service itself. The target-URI, ‘/’, is the base URL for the service. See Section 9.2.1 for details

9.4.1.2 Query ParametersThis transaction has no defined query parameters.

9.4.1.3 Header FieldsRequired: Accept

Recommended: Content Negotiation Header Fields

See Section 6.3.1.3.

9.4.1.4 PayloadThe request has no payload.

9.4.2 BehaviorThe origin server will return a machine readable description of its capabilities in an acceptable media type.

9.4.3 ResponseThe format of the response is as follows:

version∎status-code∎reason-phrase↲Content-Type: media-type↲*header-field↲↲[payload]

2310

2315

2320

2325

2330

2335

2340

A success response shall have a payload containing a Capabilities Description document encoded in a media type consistent with the Accept header of the request.

9.4.3.1 Status CodesA success response will have a status code of 200 (OK). A failure response shall have a status code from Table X.Y-Z, and should include a Status Details document.

9.4.3.2 Header FieldsRequired: Content-Type

See Section 6.3.1.3.2.

9.4.3.3 PayloadA success payload contains a Capabilities Description document in an acceptable media type.

A failure response may have an empty payload; however, it is recommended that it contains a Status Details document. See Section 7.2.3.3.

9.4.4 Media TypesThe Retrieve Capabilities service supports the following media types:

application/vnd.sun.wadl+xml

See Annex X, Y-z.

9.5 Notification Subservice An RS service may implement a Notification Subservice. This subservice enables user agents to be notified of events associated with resources managed by the Service. If a Service defines a Notification Subservice, user agents may open a notification channel to an origin server implementing the Service. Such user agents are called subscribers.

A Service may offer different types of subscriptions. The Service defines the types of subscriptions that it supports and each implementation of the Services shall maintain a list a subscribers for each type of subscription it offers. Subscribers receive notifications of events associated with the resource(s) to which they have subscribed

A subscriber to a resource should be able to receive all notifications and possibly filtered notifications. The Service defines any filters that can be applied to a stream of notifications.

Upon receipt of the Create Subscription, Suspend Global Subscription or Delete Subscription request, the origin server shall attempt to update the appropriate subscription state Global Subscription State, Filtered Global Subscription and/or Work Item Subscription State of the specified Application Entity with respect to the specified SOP Instance UID as described in Table CC.2.3-2 in PS3.4 and then return an appropriate response.

9.5.1 Deletion Locks

9.5.2 Filters

9.5.3 ResourcesEach service defines the resources to which user agents may subscribe.

2345

2350

2355

2360

2365

2370

9.5.3.1 Service EventsHowever, any RS service is itself a resource, and there are some standard event types defined for all services. All origin servers who implement the Notification Subservice should provide the following service related event notifications:

Server shutting down Server load increasing? Server low on resources? Server problem?

9.5.4 TransactionsAny service that supports the Notification Subservice must support the following transactions:

A user agent can subscribe to the three types of resources in the following table:

Table 12.2-1: Notification Subsystem TransactionsName Target URI DescriptionOpen Channel / The user agent requests that the origin server upgrade the connection to

a Notification Channel using a WebSocket.Send Event / The origin server sends an Event Report to a subscriber (a user agent). Create Subscription / Receive event notifications for any Work Item in the Worklist that passes

a specified subscription filter.Delete Subscription /

9.5.5 Open Event Channel TransactionThe Open Event Channel transaction is only define in this section. This transaction may not be defined by the service implementing the Notification Subservice. It is the same for all services.

This transaction opens a WebSocket channel that will be used to send Event Reports to the client. The WebSocket connection can use the same TCP port as the HTTP connection, but they are separate connections.

See RFC-6455 for details of the WebSocket protocol.

9.5.5.1 RequestThe request shall have the following format:

GET∎/∎version↲Host: server.example.com↲Upgrade: websocket↲Connection: Upgrade↲Sec-WebSocket-Key: {key}↲Sec-WebSocket-Protocol: {protocols}↲Sec-WebSocket-Version: {ws-version}↲*header-field↲↲

9.5.5.1.1 Query ParametersThere are no query parameters defined, but the service defining this transaction may define query parameters.

2375

2380

2385

2390

2395

2400

2405

9.5.5.1.2 Header FieldsRequired: Upgrade: websocket

Connection: UpgradeSec-WebSocket-KeySec-WebSocket-ProtocolSec-WebSocket-Version

9.5.5.1.3 PayloadTypically the request has no payload, but the actual payload is defined by the service.

9.5.5.2 BehaviorThe origin server upgrades the HTTP connection to a WebSocket connection and records the association between the user agent and the WebSocket. In the future the origin server will use this WebSocket connection to send Event Reports for any Work Items that have subscriptions from the user agent.

The origin server opens and maintains the active WebSocket connection to the user agent and uses it to send Event Report messages for Work Items that have subscriptions from the user agent. See Section 6.9.7.2, “Behavior”).

The connection shall remain open and may be used by the server to send Event messages (see Section 6.9.11, “SendEventReport”).

If the WebSocket connection is lost at any point the user agent can re-establish it by repeating the request.

The state of a WebSocket connection does not affect subscriptions and an origin server is not required to queue messages when the connection is down.

Note

A user agent will only receive the initial state of a newly-subscribed Work Item if the WebSocket connection was initiated prior to creating the subscription.

9.5.5.3 ResponseThe response shall have the following format:

version∎status-code∎reason-phrase↲Upgrade: websocket↲Connection: Upgrade↲Sec-WebSocket-Accept: response-key↲Sec-WebSocket-Protocol: protocol↲*header-field↲↲

9.5.5.3.1 Status CodesA success response will contain a status code of 101 (Switching Protocols), which indicates that the origin server has opened the connection.

A failure response will contain an appropriate status code from Table .

9.5.5.3.2 Header FieldsRequired: Upgrade: websocket

Connection: UpgradeSec-WebSocket-AcceptSec-WebSocket-Protocol

2410

2415

2420

2425

2430

2435

2440

2445

9.5.5.3.3 PayloadThe payload is defined by the service. An error payload should contain a Status Details document.

9.5.5.4 Media TypesThis transaction shall specify no media types in the request or response.

9.5.6 Send Event Report TransactionThis transaction sends Event Reports from the origin server to a user agent over an established WebSocket connection.

9.5.6.1 RequestThe request will use the WebSocket Data Frame transmission protocol.

9.5.6.1.1 PayloadThe Event Report shall contain all mandatory attributes described in Table CC.2.4-1 in PS3.4 and Table 10.3-1 in PS3.7 for the event type.

9.5.6.1.1.1 Event Report FormatEvents Reports are encoded as WebSocket data frames with an opcode of "%x1" (text).

The frame payload data shall be a DICOM JSON dataset containing the attributes of the Event Report.

The following is an example WebSocket payload:

{"00000002": [ "1.2.840.10008.5.1.4.34.6.4" ],"00000100": [ 256 ],"00000110": [ 23 ],"00001000": [ "1.2.840.10008.5.1.4.34.6.4.2.3.44.22231" ],"00001001": [ 1 ],"00741238": [ "SCHEDULED" ],"00744041": [ "READY" ]

}↲The WebSocket protocol does not allow content negotiation so it is not possible to support both XML and JSON encoding of Event Report messages without extending the protocol.

9.5.6.2 BehaviorPS3.4, Section CC.2.4.3 describes the scenarios in which an origin server sends Event Reports to a subscriber, as well as the content of the Event Report messages.

9.5.6.3 ResponseThere is no response.

9.5.7 Create Subscription TransactionThis transaction records subscribers to whom future events associated with the specified resources will be reported.

2450

2455

2460

2465

2470

2475

2480

9.5.7.1 RequestThe request shall be formatted as follows:

POST∎/{+resources}{?deletionlock,filter}∎version↲Content-Length: 0↲*header-field↲↲

Where,

resources is defined by the service.

deletionlock = true / false

If present, shall have a value of ‘true’ or ‘false’, indicating whether or not the user agent is requesting a Deletion Lock.

filter = *{attribute-value-pair}

If present, specifies the attribute-value pairs describing the filter parameters.

See Section 6.7.1.1 for {attribute} and {value} encoding rules.

9.5.7.1.1 Header FieldsRequired: Content-Length: 0

See Section 6.3.1.3

9.5.7.1.2 PayloadTypically the request has no payload, but the actual payload is defined by the service.

9.5.7.2 BehaviorThe origin server shall create a subscription to the target resource for the user agent.

The origin server shall support the management of subscriptions as specified by the SCP behavior in PS3.4, Section CC.2.3.3.

Upon receipt of the Create Subscription, Suspend Global Subscription or Delete Subscription request, the origin server shall attempt to update the Global Subscription State, Filtered Global Subscription and/or Work Item Subscription State of the specified Application Entity with respect to the specified SOP Instance UID as described in PS3.4, Table CC.2.3-2 and then return the appropriate response.

9.5.7.3 ResponseThe response shall have the following format:

version ∎status-code ∎reason-phrase↲Location: {+web-socket}↲Content-Length: 0↲{*header-field↲}↲[payload]

Where,

{+web-socket} is the base URL for the WebSocket service. This shall include the WebSocket protocol (either WS or WSS) and may include a combination of authority and path.

2485

2490

2500

2505

2510

2515

2520

9.5.7.3.1 Status CodesA success response shall contain a status code of 201 (Created).

A failure response shall contain a status code from Table .

9.5.7.3.2 Header FieldsRequired: Location

Required if the Create Subscription request was accepted but the Deletion Lock was not, the response shall include the following Warning header field:

Warning: 299 {+service}: Deletion Lock not granted.

Required if the request was rejected with a status code of 403, because Filtered Global Subscriptions are not supported, the response message shall include the following Warning header field:

Warning: 299 {+SERVICE}: The origin server does not support Global Subscription Filtering.

9.5.7.3.3 PayloadThe payload is defined by the service. An error payload should contain a Status Details document.

9.5.7.4 Media TypesThe service shall define all media-types supported.

9.5.8 Delete SubscriptionThe target resource must be a resource to which the user agent has subscribed. If the “suspend” query parameter is “true” any current subscription are left in place, but no more subscriptions shall be created for the target resource. If the “suspend” parameter is “false” all current subscriptions to the target resource are deleted and no more will be created. If the “suspend” parameter is not present, it’s value is “false”.

If the target resource is the Worklist and the “suspend” query parameter is “true” then all future subscriptions to Work Items are cancelled. If the “suspend” query parameter is either “false” or not present, the all current and future subscriptions are cancelled.

9.5.8.1 RequestThe request shall be formatted as follows:

DELETE∎ /{+subscription}{?suspend}∎version↲Content-Length: 0↲*header-field↲↲

9.5.8.1.1 Query Parameterssubscription a URI referencing the subscription.

?suspend =true / false

If present and its value is “true”, it indicates that the subscription should be suspended, i.e. current subscriptions should not be deleted, but no future subscriptions shall be created. If it is not present or its value is “false” all current subscriptions to the resource are deleted and no future subscriptions shall be created.

2525

2530

2535

2540

2545

2550

2555

2560

9.5.8.1.2 Header FieldsRequired: Content-Length: 0

9.5.8.1.3 PayloadTypically the request has no payload, but the actual payload is defined by the service.

9.5.8.2 BehaviorIf the “suspend” query parameter is “true” the origin server shall no longer automatically subscribe the user agent to newly-created Work Items; however, this does not delete existing subscriptions to Work Items. If the “suspend” query parameter is “false” or not present the origin server shall remove any of the user agent’s existing subscriptions to the target resource.

The origin server shall conform to the behavior described in Section 12.1.8.4, “Behavior”.

9.5.8.3 ResponseThe response shall have the following format:

version∎status-code∎reason-phrase↲Content-Length: 0↲*header-field↲↲

9.5.8.3.1 Status CodesA success response shall contain a status code of 200 (OK), indicating that the target subscription(s) have been suspended or deleted.

A failure response will contain an appropriate status code from Table 12.2-A.

9.5.8.3.2 Header FieldsRequired: Content-Length: 0

9.5.8.4 PayloadThe payload is defined by the service. An error payload should contain an Status Details document.

9.5.9 Media TypesUnless specified otherwise in the transaction definition, the Notification Subsystem supports the following media types:

application/json application/dicom+json

10 Restful Studies Service

Closed Issues# Issues

2565

2570

2575

2580

2585

2590

Open Issues# Issue Status

Can the ‘deidentify’ parameter be used with the Retrieve DICOM service? Needs a CP

Editorial Issues# Issue Status

Changed URI template variables to be lowercase with ‘_’ separating words (snake case) Closed

The RS Storage Service defines a set of transactions that enable a user agent to store, retrieve, and search an origin server for studies, series, instances, frames, and bulkdata, along with their metadata variants.

10.1 ResourcesThe resources managed by the Storage Service are a collection of DICOM Studies. The resources are conceptually organized in a tree hierarchy that corresponds to the DICOM Information Entity Model (see xxx), that is, Study, Series, and Instance.

The following URI template variables are used in the definitions of the resources in Table 10.1-1:

{study_uid} the Study UID of a study contained in the Studies resource.

{series_uid} the Series UID of a series contained within the parent resource.

{instance_uid} the SOP Instance UID of an instance contained within the parent resource.

{frames} a comma-separated (comma = %2C) list of frame numbers in ascending order contained within a single instance.

{+bulkdata} a URI that references a bulkdata resource.

2595

2600

2605

2610

The Storage Service defines the following resources:

Table 10.1-1: RS Resource Names, URI Templates and DescriptionsName URI Template and DescriptionService /

The Service resource is the base URI of one or more RS Services.All Studies /studies

The All Studies resource references the entire collection of studies contained in the Studies Service. All RS Storage Service resources begin with this resource.

Study /studies/{study_uid}

The Study resource references a single study.Study Metadata

/studies/{study_uid}/metadata

The Study Metadata resource references the metadata of a single study. Study Metadata is defined to be all attributes in the specified study, where any values larger than a threshold defined by the origin server may be replaced by a Bulkdata Reference. This threshold is typically in the range: 128 <= threshold <= 1024 bytes.

All Series /series

The All Series resource references the collection of all series in all studies contained in the Studies Service.

Study’s Series

/studies/{study_uid}/series

The Study’s Series resource references the collection of all series contained in a study.Series /studies/{study_uid}/series/{series_uid}

The Series resource references a single series in a study Series Metadata

/studies/{study_uid}/series/{series_uid}/metadata

The Series Metadata resource references the metadata of a single series in in a study.All Instances /instances

The All Instances resource references the collection of all instances in all series in all studies contained in the Studies Service.

Study’s Instances

/studies/{study_uid}/instances

The Study’s Instances resource references the collection of all instances in a single study.Series’ Instances

/studies/{study_uid}/series/{series_uid}/instances

The Series’ Instances resource references the collection of all series in a single study.Instance /studies/{study_uid}/series/{series_uid}/instances/{instance_uid}

The Instance resource references a single instance contained in a series.Instance Metadata

/studies/{study_uid}/series/{series_uid}/instances/{instance_uid}/metadata

The Instance Metadata resource references the metadata of a single instance contained in a series.Frame List /studies/{study_uid}/series/{series_uid}/instances/{instance_uid}/frames/

{frame_list}

The Frames resource references an ordered collection of frames in a single multi-frame instance. Bulkdata {+bulkdata}

The Bulkdata resource references one or more bulkdata objects. Bulkdata URIs are contained in a metadata resource. A metadata resource must be retrieved first, then the bulkdata URIs that it contains can be used to retrieve bulkdata resources. The URI is determined by the origin server. It is not specified

by this standard.

10.2 TransactionsThe Storage Service defines the six transactions specified in the following table:

Table 10.2-1: Storage Service Transactions

Transaction MethodRequestPayload

ResponsePayload Description

RetrieveCapabilities

OPTIONS Empty Capabilities Description

Retrieves a description of the capabilities of the storage service, including transactions, resources, query parameters, etc.

Retrieve DICOM

GET Empty Instance(s)or PD

Retrieves one or more representations, specified by the target resource in an acceptable DICOM media type.

Retrieve Rendered

GET Empty Renderedinstance(s)or PD

Retrieves one or more representations, specified by the target resource, which shall not be a presentation state, in an acceptable rendered media type(s).

Retrieve PS GET Empty Rendered PS instance

Retrieves one or more representations, specified by the target resource, which shall be a presentation state instance, in an acceptable rendered media type(s).

Store POST Instance(s)

Empty or PD

Stores one or more DICOM representations, contained in the request payload, in the location referenced by the target resource.

Search GET Empty Result(s) Searches the target resource for objects that match the search parameters and returns a list of matches in an acceptable media type.

Open Event Channel

Opens a WebSocket channel between the user agent and origin server, which the origin server uses to send event notifications.

Send Event Report

Sends an Event Notification Report from the origin server to the user agent.

CreateSubscriptionDeleteSubscription

Table 10.2-2 shows the resources defined for each transaction.

Table 10.2-2 Resources by Transaction

ResourceRetrieveDicom

RetrieveRendered

RetrievePS Store Search Capabilities

/ XAll Studies X XStudy X X X XStudy Metadata X XAll Series XStudy’s Series ? ? XSeries X XSeries Metadata X XAll Instances XStudy Instances X X X

2615

2620

Series’ Instances X X XInstance X X X XInstance Metadata XFrame List X X X

10.3 Retrieve DICOM TransactionThe Retrieve DICOM transaction retrieves the target resource in a DICOM media type.

10.3.1 RequestThe Retrieve DICOM services has the following retrieve message format:

GET∎{/resource}{?deidentify}∎version↲*header-field↲↲

Where,

deidentify = yes / no

See Section 10.3.1.2.1 for details.

10.3.1.1 ResourcesThe Retrieve DICOM transaction supports the resources listed in Table 10.3-1. If an origin server supports this transaction it shall support all resources.

Table 10.3-1 shows the resources, with their URI templates, supported by the Retrieve DICOM transaction.

Table 10.3-1: Resources, Templates, and DescriptionTarget Resource Resource URI TemplateStudy /studies/{study_uid}

Retrieves a study in an acceptable DICOM media type.Study Metadata /studies/{study_uid}/metadata

Retrieves the metadata for a study in an acceptable DICOM media type.Series /studies/{study_uid}/series/{series_uid}

Retrieves a series in an acceptable DICOM media type.Series Metadata /studies/{study_uid}/series/{series_uid}/metadata

Retrieves the metadata for a series in an acceptable DICOM media type.Instance /studies/{study_uid}/series/{series_uid}/instances/{instance_uid}

Retrieves a instance in an acceptable DICOM media type.Instance Metadata /studies/{study_uid}/series/{series_uid}/instances/{instance_uid}/metadata

Retrieves the metadata for an instance in an acceptable DICOM media type.Frames /studies/{study_uid}/series/{series_uid}/instances/{instance_uid}/frames/{frame_list}

Retrieves one or more frames in an acceptable DICOM media type.

2625

2630

2635

Bulkdata {/bulkdata}

Retrieves one or more bulkdata items in an acceptable DICOM media type.

10.3.1.2 Query Parameters

10.3.1.2.1 De-Identificationdeidentify = yes / no

The “deidentify” parameter is optional and has a value of ‘yes’ or ‘no’. It specifies that the target resource shall have all Personally Identifiable Information (PII) removed. This includes removing or "blanking out" any area(s) containing PII burned into the pixels or in overlays in the return representations. This process is called de-identification and is sometimes referred to as anonymization; although, the latter term is discouraged. See PS3.15 Section E. Attribute Confidentiality Profiles.

De-identification is the responsibility of the origin server. De-identified objects shall have a new SOP Instance UID that is different from that of the original identified objects. The Server may return an error if either it cannot or refuses to de-identify the requested objects.

10.3.1.3 Header FieldsRequired: Accept

See Section 6.3.1.3

10.3.1.4 PayloadThe request has no payload.

10.3.2 BehaviorThe origin server locates the target resource and returns in an acceptable DICOM media type.

10.3.3 ResponseThe response has the following format:

version∎status-code∎reason-phrase↲Content-Type: dicom-media-type↲*header-field↲↲[payload]

Where,

dicom-media-type is one of the media types defined in Table 10.3-X and Annex X.

10.3.3.1 Status CodesThe following status codes are defined for the RS Protocol and shall be used to report any of the associated error and warning situations. Implementers may use other status codes for other error and warning situations.

Table 10.3-X: Status CodesStatus Code Phrase Description

2640

2645

2650

2655

2660

2665

Success

200 OK Indicates that all instances were successfully retrieved.

Warning 206 Partial Content Indicates that the response contains some, but not all, of the requested content.

Error See Table X.Y-Z

10.3.3.2 Header FieldsRequired: Content-Type

See Section 6.3.1.3.2

10.3.3.3 PayloadA success response has a payload containing one or more representations of the DICOM instances specified by the target resource. The payload may be single part or multipart depending on the media type.

An error response may have no payload; however, it is recommended that failure responses contain a Status Details document that describes the problems encountered by the origin server.

10.3.4 Media TypesDICOM Pixel data shall be encoded using the media types in Table 9.2-1. These media types have a corresponding transfer syntax that is specified by a UID which is the value of the transfer syntax parameter. The column marked DFT indicates the default transfer syntax (D) for a specific media type. For imaging media types without a default, the Explicit VR Little Endian transfer syntax will be used, if a transfer syntax parameter is not specified. See PS3.5 and PS3.6.

Origin servers implementing the RS protocol shall be prepared to handle transfer syntax parameters for all imaging media types. The syntax is:

media-type; transfer-syntax={transfer-syntax}

For example, an Accept header field might look as follows:

Accept: multipart/related; type=”application/dicom”; transfer-syntax=1.2.840.10008.1.2.4.70

or

Accept: application/json; transfer-syntax=1.2.840.10008.1.2.4.70

Table 10.3-1: DICOM Image Media Types and Legal Transfer Syntaxes

Media Type Transfer Syntax UID Default NameSingle Frame ImageImage/dicom+evle 1.2.840.10008.1.2.1 D Explicit VR Little Endian

Note: Equivalent to the application/octet-stream media type.

image/dicom+jpeg 1.2.840.10008.1.2.4.50 JPEG Baseline Lossy 8 bit

1.2.840.10008.1.2.4.51 JPEG Extended Lossy 12 bit

1.2.840.10008.1.2.4.57 JPEG Lossless, Non-Hierarchical

1.2.840.10008.1.2.4.70 D JPEG Lossless, Non-Hierarchical, First Order Prediction

image/dicom+rle 1.2.840.10008.1.2.5 D RLE Lossless

2670

2675

2680

2685

2690

image/dicom+jpeg-ls 1.2.840.10008.1.2.4.80 JPEG-LS Lossless

1.2.840.10008.1.2.4.81 JPEG-LS Lossy (Near Lossless)

image/dicom+jp2 1.2.840.10008.1.2.4.90 D JPEG 2000 Lossless

1.2.840.10008.1.2.4.91 JPEG 2000

image/dicom+jpx 1.2.840.10008.1.2.4.92 D JPEG 2000 Part 2 Multi-component Lossless

1.2.840.10008.1.2.4.93 JPEG 2000 Part 2 Multi-component Multi-Frame Imageimage/dicom+jpx 1.2.840.10008.1.2.4.92 D JPEG 2000 Part 2 Multi-component Lossless

1.2.840.10008.1.2.4.93 JPEG 2000 Part 2 Multi-componentVideovideo/mpeg 1.2.840.10008.1.2.4.100 MPEG2 Main Profile @ Main Level

1.2.840.10008.1.2.4.101 MPEG2 Main Profile @ High Level

video/mp4 1.2.840.10008.1.2.4.102 MPEG-4 H.264 High Profile

1.2.840.10008.1.2.4.103 MPEG-4 H.264 BD-compatible High Profile

See Sections 6.3.5 and 9.2.4 for information about RS Protocol media types.

2695

Digital Imaging and Communication in Medicine (DICOM)

RS Supplement 174: Rendering for Restful Services

**** Begin Remove before Public Comment ****

Note: WG-06 believes that the decision as to what parameters should be included in RS Rendering, should be based on what is easy to do in a user agent without putting stress on the CPU or memory system.

Scope for Rendering

Dentistry is out of scope Should be Diagnostic quality rendering Rendering will not be fully specified Should allow only presentation states to be rendered? What are the consequences? Request should be able to include a PS specification payload.

What about Documents? They are different media type

Editor’s Note:The new HTTP/1.1 standard (RFC 7231 Section 3.3) recommends that:

Response messages with an error status code usually contain a payload that represents the error condition, such that it describes the error state and what next steps are suggested for resolving it.

Editorial Issues# Issue Status1 Is there any reason to de-identify a rendered image?

Yes notes in PS.2 Is there any reason to de-identify other rendered objects?

Documents? YesOther types??

3 What is the correct ordering of the rendering parameters according to the rendering pipeline?4 How should the parameter definition sections be ordered – by pipeline or alphabetically?

Decision: AlphabeticallyClosed

5 Should the region parameters be named (top, left, bottom, right) or (xMin, yMin, xMax, yMax)?Mathworks (x, y, width, height) in pixelsImageMagick(width, height, xOffset, yOffset)IIIF ImageAPI(x, y, w, h) or (pct: x, y, w, h) where 0, 0 is upper left corner

2700

2705

2710

2715

2720

6 Should Flip and Rotate be done before or after the Region is selected? After?

**** End of Remove before Public Comment ****

Closed Issues1 Should unknown parameter keywords be ignored or should they generate errors?

Decision: Unknown parameters should be ignored. URI and WS should also ignore unknown parameters.

2 Can vendors add other parameters? YES. Any vendor defined parameters should be specified in their Conformance Statement and in their Service Capabilities response.

3 What should we do if the region parameter is ill defined?Decision: return an error.

4 Should there be a separate service for rendering?Yes. There should be three separate retrieve services. One for DICOM, one for rendered images using query parameters, and one for rendered images using presentation states. The render presentation state service should only reference presentation states.

5 Should Accept headers be in preference order?No. Proxies won’t preserve the ordering. The ‘q’ (quality) parameter can be used to specify preference order.

6 Should we add the ability to specify VOILUT function, and/or which VOILUT by number? No. A Presentation State instance has only one VOILUT.

7 If no parameters are supplied by the user agent, how should the response payload be rendered?Decision: rendered in TRUE SIZE with no transformation applied.

8 Should a ‘viewport=rows, columns’ parameter be included. It makes the scaling choice easier for the user agent. The semantics would be that the origin server would scale the image to the largest size possible while maintaining the original aspect ratio.Yes. “Viewport” should be included and “rows” and “columns” should not be supported by RS Retrieve Rendered.

9 Should we keep the Retrieve Rendered Presentation Study and Series transactions? Are the semantics clear enough? If so what should the behavior be? What is the best heuristic?No. Only one PS instance can be retrieved

11a Part 1: Should implementations of RS rendering services be required to support all composite SOP classes? No. List in conformance statement and Capabilities Descriptions.

14 Should Rendering support all the photometric interpretations?Decision: “Supported SOP Classes, with their implied photometric interpretations, shall be specified in Conformance Statement and Capabilities Description. Do not see a need to mandate a baseline.”

18 Should the rendered PS transaction have a ‘deidentify’ parameter. Yes, On a best efforts basis. The origin server can refuse to de-identify any instance.

2725

43 Which parameters can be used with presentation states?Decision: The only parameters that can be used with PSes are ‘annotation’, ‘deidentify’, ‘imageQuality’, and ‘viewport’.

Open Issues# Issue StatusGeneral0 What are the target use cases for RS Rendering

1. Display one image per URI inside a report, email, or other document?2. Display multiple images per URI inside a report, email, or other document?3. Retrieve images for display in a web based clinical viewer?4. Retrieve images for display in a web based diagnostic viewer?5. What others?

10 Should RS rendering services be mandatory if you implement RS Retrieve? (leaning toward No)11b Part 2: Should implementations have to be able to support any objects that it can retrieve as native

DICOM (leaning towards No).12 Part 1: Should the Rendering Services support Structured Display? (Dental and eye care) supply

references. Part 2: Should the supplement address this?Part 3: If defined, should it be a separate transaction?

13 Should we specify how interpolation is done for images that are being magnified and then scaled to fit a viewport? What about images that are smaller than the viewport?*Take a look at IHE mamo profile, and Pathology whole slide IOD.Should we have an interpolation algorithm parameter?*If the origin server does a non-linear interpolation it should say so.Is there a way to get derivation information into an overlay, so that it is visible?

JFP Todo

15 What status code should we use for partial success, i.e., some instances were unable to be rendered, some frames rendered but not all? RS Retrieve* uses 206 and RS Store uses 202? Should we create our own status code? We could request one from IANA - http://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml.

16 Should extensions for RS rendering will be retrofitted to URI? To the extent that they can be. Since URI can only return one object, some of the functionality in RS will not be possible to retrofit.

17 Can we define the grayscale and color space, if the window on the user agent device can be calibrated?For dumb clients there is not much we can do; however, for smart user agents, what information can they provide, what parameters should they use to transmit the information, and what should the server be required to do with that information. For example, clients could measure ambient light, send it to the server in a parameter and the server could re-render the image appropriately. In other words, who is responsible for applying calibration information – the client or the server?

19 Do we need to say anything about making measurements on rendered images?20 Should origin servers be required to support all the rendering query parameters? If not, what

should be done if the origin server is unable to perform all the transformation specified in the request?

21 What should be done in the cases of Partial Success of transformations, i.e. where some transformations where not able to be applied to all instances?

1. Return an error with a description of the problems.2. Return the images that were successfully rendered, with a message in the Warning header

field?3. Other?

22 Can the ‘deidentify’ parameter be used with the Rendering services?Specific Parameters30 Part 1: Should we extend the “annotation” parameter to use the DICOM keywords or tags in IHE

BIR to specify the annotations?Part 2: Should we specify where the information goes on the screen? If so, how would be specify the locations?

31 When should annotations be applied? Proposal after the region is selected and scaled to the appropriate size. This is not specified in the PS pipelines.

33 Should the “order” of Images parameter be included? When the user agent receives a set of images, It cannot reorder the images in any meaningful way because it has no information that lets it change the order in a meaning full way; unless the user agent retrieved the metadata first.

34 Should the “rotate” parameter be included?35 Should the “flip” parameter be included?36 Should the server defined presets be included in the “window” parameter?37 Is there anything missing from the Retrieve Rendered service?

Should the coordinates of the “region” parameter be in pixels or normalized from 0.0 to 1.1? The browser would typically generate the units in pixels.

Presentation States40 Should Blending Presentation States be allowed to be supported?42 What Presentation State SOP classes should be included in Presentation State rendering? All of

them? 2D only? 3D? What 3D?Should any be mandatory?Should all supported SOP classes be specified in the Conformance Statement?

44 Can presentation states refer to non-image object? Yes, so they must be considered when de-identifying them

delete

49 Is there anything missing from the Retrieve Rendered Presentation State service?

.

10.4 RS Retrieve Rendered TransactionThe Retrieve Rendered service retrieves DICOM objects rendered as: images, text based documents, or other appropriate representations depending on the resource. Its primary use case is to provide user agents with a simple interface for displaying medical images and related documents, without requiring deep knowledge of DICOM data structures and encodings. It is similar to the Retrieve DICOM service in that it uses the same method, resources, header fields and status codes. The primarily difference is the query parameters and media types supported.

If the target resource references contains any presentation state instances they shall not be rendered.

If the region parameter is not present, images are rendered in their original size.

10.4.1 RequestThe Retrieve Rendered service has the following request message format:

GET∎{resource-path}{?query*}∎version↲*header-field↲↲

Where,

query = zero or more query parameters as defined in Section 10.4.1.2 below.

10.4.1.1 Target ResourcesTable 10.4-1 shows the resources supported by the Retrieve Rendered transaction along with their associated URI templates.

Table 10.4-1: Resources, Templates, and DescriptionTarget Resource Resource URI TemplateStudy /studies/{study_uid}

Retrieves a study in an acceptable rendered media type.Series /studies/{study_uid}/series/{series_uid}

Retrieves a series in an acceptable rendered media type.Instance /studies/{study_uid}/series/{series_uid}/instances/{instance_uid}

Retrieves a instance in an acceptable rendered media type.Frames /studies/{study_uid}/series/{series_uid}/instances/{instance_uid}/frames/{frame_list}

Retrieves one or more frames in an acceptable rendered media type.Bulkdata {/bulkdata}

Retrieves one or more bulkdata items in an acceptable rendered media type.

The specified resource shall not contain any presentation state series or instances.

10.4.1.2 Query ParametersThis service defines query parameters that specify how the identified instance(s) is rendered. The parameters defined in this section specify various rendering transformations to be applied to the images contained in the target resource.

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

2730

2735

2740

2745

2750

1. All parameters are optional for the user agent.2. The “deidentify” and “order” parameters are optional for the origin server; all other are required. 3. These parameters only apply to resources that are images and video as defined in Section 9.3.6.4. These parameters do not apply to resources that are not images or video. Instances that are not images will

be rendered in an acceptable media type, if one exists; otherwise, they will not be rendered.5. The data types of the parameter values are defined in Section [ref]6. Unless otherwise specified the image(s) are rendered in their original size. For example, when no parameters

are supplied.7. The set of transformations specified by the parameters in this section shall be applied to the target resource

images as if they were a presentation state, that is, in the order specified by the applicable image rendering pipeline specified in PS 3.3.

Table 10.4-2: Query Parameters for the Retrieve Rendered ServiceKey Values Type R/O Descriptiondeidentify

‘yes’ or ‘no’ O Remove all Personally Identifying Information from the target resource.

order keyword O Order of the return images.region x, y, width, height integer R The sub-region of the image(s)flip keyword R Flip the image(s) along their ‘horizontal’ or ‘vertical’ axis.rotate degrees integer R Rotate the image by 90 degree increments from -270 to 270.window center, width or keyword decimal R Set the Window Levelannotation

keyword R Annotates the image(s) with information.

viewport width, height integer R Scales the images to the size of the viewportquality factor integer R Specifies the quality (1 <= integer <= 100) of lossy compressed

images.

10.4.1.2.1 Annotation on the Imageannotation = (patient / procedure) / #{attribute}

The “annotation” parameter specifies that the target resource shall be annotated with information about the patient and/or procedure. If this parameter is not present, the returned images shall have no annotations applied.

The parameter value is a non-empty comma-separated list of either:

patient for displaying patient information on the image(s) (e.g. name, birth date, etc.)

procedure for displaying information of the procedure or technique used

attribute one or more of the attribute identifiers defined below in Table 10.4-3.

The annotation may be burned into the returned image pixels or overlays may be used.

When used in conjunction with the “region” and/or “viewport” parameters, the annotations shall be applied after the region has been selected and the image(s) scaled to the appropriate size.

If the “deidentify” parameter is present, no Personally Identifiable Information shall be present in the annotations. The ‘patient’ keyword and any patient attributes shall be ignored by the origin server.

The exact nature and presentation of the annotations is determined by the origin server. Any additional annotation attributes supported by the server should be documented in the Conformance Statement and in the Retrieve Capabilities response.

Table 10.4-3: Attribute IdentifiersKeyword Tag NotesPatient Identifiers

2755

2760

2765

2770

2775

2780

PatientName 00100010PatientID 00100020PatientBirthDate 00100030PatientSex 00100040InstitutionName 00080080StudyID 00200010AccessionNumber 00080050SeriesNumber 00200011SeriesDescription 0008103EAcquisitionDateTime 0008002A if present, else AcquisitionDate (0008,0022) and

AcquisitionTime (0008,0032), if present, else ContentDate (0008,0023) and ContentTime (0008,0033), if present, else SeriesDate (0008,0021) and SeriesTime (0008,0031), if present, else StudyDate (0008,0020) and StudyTime (0008,0030)

Procedure IdentifiersInstanceNumber 00200013 (for correlation with slices described in the report)SliceLocation 00201041 If present, else TablePosition (0018,9327), if present else

a value derived from ImagePosition (Patient) (0020,0032)SliceThickness 00180050SpacingBetweenSlices 00180088 if present, else a value derived from successive values of Image

Position (Patient) (0020,0032) perpendicular to the Image Orientation (Patient) (0020,0037)

IVContrastUsed See notes whether or not intravenous contrast was used (C+/-), derived from Contrast/Bolus Agent Sequence (0018,0012), if present, else Contrast/Bolus Agent (0018,0010)

Compressed See notes whether or not lossy compression has been applied, derived from Lossy Image990 Compression (0028,2110), and if so, the value of Lossy Image Compression Ratio(0028,2112) and Lossy Image Compression Method (0028,2114), if present (as per FDA Guidance for the Submission Of Premarket Notifications for Medical Image Management Devices, July 27, 2000)

WindowCenter 00281050 the currently applied window center and width (or window top and bottom for clamped modeWindowWidth 00281051

10.4.1.2.2 De-Identificationdeidentify = yes / no

See Section 10.3.1.3.1.

10.4.1.2.3 Flip Imageflip = {keyword} where keyword = ‘horizontal’ or ‘vertical’

The “flip” parameter controls the flipping of the image(s) in the target resource. The value is either “horizontal” or “vertical,” which specifies the axis around which the image is flipped.

10.4.1.2.4 Order of Rendered Imagesorder = {keyword}

2785

2790

The “order” parameter requests that the target resource image(s) be returned in a specific order. The value is one of the keywords defined in Table 10.4-x below.

Table 20.4-x: Keywords for Ordering ImagesKeyword Description Attributetime The objects in the response will be in ascending

order by acquisition time.{0008,0012) InstanceCreationDate(0008,0013) InstanceCreationTIme

number The objects in the response will be in ascending order by series number, instance number and frame number.

(0020,0011) SeriesNumber,(0020,0013) InstanceNumber,(0020,9156) FrameAcquisitionNumber

position The objects in the response will be in ascending order by series, instance and frame position.

(0020,0032 ) ImagePositionPatient

phase The objects in the response will be in ascending order by series, instance and frame position.

TemporalPositionIndex

The implementer may provide additional keyword values, which should be included in the conformance statement and in the Retrieve Capabilities response.

10.4.1.2.5 Quality of the Imagequality = {integer} where 1 <= integer <= 100

The “quality” parameter specifies the requested quality of the rendered images. The value shall be an integer in the inclusive range of 1 to 100.

It is only supported for media types that allow lossy compression.

10.4.1.2.6 Region of the Imageregion = {x, y, width, height} where 0 <= x, y, width, height <= 32,6767 (216 – 1)

The “region” parameter requests a rectangular region of the original image(s). Its value shall be a list of four comma-separated, non-negative integers, which represent in the following order:

x offset from top, left cornery offset from top, left cornerwidth width of regionheight height of region,

If the specified region is not within the bounds of the image the origin server shall return an error response, with a status code of 400 (Bad Request), and a payload containing a Problems Details document.

If the region parameter is not present the returned representations shall be in their original size.

10.4.1.2.7 Rotate the Imagerotate = {integer} where -270 <= integer <= 270 in 90˚ increments

The “rotate” parameter specifies that the target resource image(s) should be rotated before rendering. The value is an integer that is a multiple of 90 between -270 and 270 inclusive. A positive value indicates clockwise rotation, and a negative value indicates counterclockwise rotation.

If both the “region” and “rotate” parameters are present the region will be selected before it is rotated.

10.4.1.2.8 Window Level Imagewindow = {center,width) / {preset} where center and width are decimal numbers, and

preset is an origin server defined keyword

2795

2800

2805

2810

2815

2820

2825

The “window” parameter controls the luminosity and contrast of the images as defined in PS 3.3. The value shall be either two comma-separated decimal values, specifying the Window Center and Window Width in that order, or one keyword.

Preset keywords defined by the origin server and correspond to specific values for Window Center and Window Width.

This Standard does not define either: 1) the range of the decimal values, or 2) the set of preset keywords and associated values.

The origin server may define preset keywords and their values. The user agent can use the Retrieve Capabilities transaction to retrieve the origin server’s Capabilities Description document, which shall contain any preset keywords that it defines.

10.4.1.2.9 View Port on the User Agentviewport = {width,height} where 0 <= width, height <= 32,6767 (216 – 1)

The “viewport” parameter specifies a rectangular area defined by its width and height in pixels. The viewport is intended to correspond to a window on the user agent’s device. The origin server shall scale the rendered images, maintaining their original aspect ratio, until either the image width is the same as the viewport width or the image height is the same as the viewport height, whichever comes first. In other words, viewport scaling makes the image(s) as large as possible, within the viewport, without overflowing the viewport area.

If the viewport parameter is not present, the returned images are not scaled.

10.4.1.3 Header FieldsRequired: Accept

See Section 6.3.1.3

10.4.1.4 PayloadThis request has no payload.

10.4.2 BehaviorThe target resource(s) are rendered according to the query parameters, by applying the transformations according to the appropriate rendering pipeline specified in PS3.3, Sections xx.

10.4.3 ResponseA success response shall contain a success status code (2XX), appropriate content representation headers, and a payload containing one or more representation encoded in an acceptable media type.

An error response will contain an error status code (4XX or 5XX), appropriate error response headers, and may contain a payload with a Status Details document.

10.4.3.1 Status CodesThe most common success status codes are:

200 Success The origin server successfully rendered all of the instances referenced by the resource.

206 Warning The origin server successfully rendered only some of the instances referenced by the resource.

2830

2835

2840

2845

2850

2855

2860

4XX Error The origin server was unable to successfully render any of the instances. It will return an Error Status Code from Table X.Y-z and should include a Status Details document in the payload.

10.4.3.2 Header FieldsRequired: Content-Type

See Section 6.3.1.3

10.4.3.3 PayloadThe origin server shall include all successfully rendered images in the payload. If no instances were successfully rendered, the payload should contain a Status Details document.

10.4.4 Media TypesA successful Retrieve Rendered transaction shall return rendered media types. See Section 9.3.5.

10.5 Retrieve Rendered Presentation States Instance TransactionThe Retrieve Rendered Presentation State (PS) Instance transaction retrieves a rendering of the target resource, which must be a presentation state instance, in an acceptable media type.

The transaction has the following characteristics:

1. The target resource shall be a single presentation state instance.2. The media type specified in the request shall be a rendered media type.

10.5.1 Request The Retrieve Presentation State transactions uses the GET method. The request has the following format:

GET∎{/resource}{?query*}∎version↲*header-field↲↲

10.5.1.1 Target ResourceTable 10.5-x shows the target resources and their URI template for this transaction. The target resource shall reference only one presentation state instance.

Table 10.4-1: Target Resource, URI Template, and DescriptionTarget Resource Resource URI TemplateInstance /studies/{study_uid}/series/{series_uid}/instances/{instance_uid}

Retrieves a PS instance in an acceptable rendered media type.Frames /studies/{study_uid}/series/{series_uid}/instances/{instance_uid}/{frame_list}

Retrieves one or more frames from a PS instance in an acceptable rendered media type.Bulkdata {/bulkdataI}

Retrieves one or more rendered frames from a bulkdata item in an acceptable rendered media type.

2865

2870

2875

2880

2885

10.5.1.2 Query ParametersThe Retrieve Rendered Presentation State service provides query parameters that may be used to specify how the origin server should render the target resource before returning it in the payload.

10.5.1.2.1 Annotations on the Imageannotation = (patient / procedure) / #{attributeIDattribute}

See Section 10.4.1.2.1.

10.5.1.2.2 De-Identificationdeidentify = yes

The “deidentify” parameter specifies that any Personally Identifiable Information is to be removed from all representations returned in the payload. See Section 9.3.2.2.2

10.5.1.2.3 Volume of Interest Lookup Table (VOI LUT)voiLutItemNumber = { integer } non-negative or positive?

The “voiLutSequenceItemNumber” parameter specifies the VOI LUT Sequence (0028,3010) Item to be used to render the returned images.

10.5.1.2.4 Quality of the Imagequality = {integer} where 1 <= integer <= 100

See Section 10.4.1.2.x.

10.5.1.2.5 View Port on the User Agentviewport = {rows,columns} where rows and columns are positive integers

See Section 10.4.1.2.x.

10.5.1.3 Header FieldsRequired: Accept

See Section 6.3.1.3.

10.5.1.4 PayloadThe request message has no payload.

10.5.2 BehaviorThe origin server shall support all of the query parameters defined by this transaction.

The origin server shall render the presentation state instance referenced by the target resource in an acceptable media type. Rendering a presentation state instance requires rendering its Referenced SOP Instance (0008,1155) using the rendering pipeline specified in PS 3.4.

If the Presentation Size Mode is TRUE SIZE the displayed area specified in the presentation state shall NOT be scaled; however, if a “viewport” parameter was specified, and a success response message shall have a Warning header field containing the following text:

Warning {+service}: Presentation Size Mode was TRUE SIZE. The image has not been scaled to the specified viewport={rows,columns}.

2890

2895

2900

2905

2910

2915

2920

if the Presentation Size Mode is SCALE TO FIT, the displayed area specified in the presentation state shall be scaled to maximize the size of the image in the viewport, while maintaining its aspect ratio; however, if no “viewport” parameter was specified the image shall not be scaled, and a success response message shall have a Warning header field containing the following text::

Warning {+service}: Presentation Size Mode was SCALE TO FIT, but not view port was specified. The image has not been scaled.

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. 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 view port.

If the Annotation parameter is present the annotations shall be applied to the images after the presentation state has been applied.

10.5.3 ResponseA success response shall contain a success status code (2XX), appropriate content representation headers, and a payload containing one representation encoded in an acceptable media type.

An error response will contain an error status code (4XX or 5XX), appropriate error response headers, and may contain a payload with a Problem DetailsStatus Details document.

10.5.3.1 Status CodesThe most common success status codes are:

200 Success The origin server successfully rendered all of the instance referenced by the resource.

4XX Error The origin server was unable to successfully render any of the instances. It will return an Error Status Code from Table X.Y-z and should include a Problem DetailsStatus Details document in the payload.

10.5.3.2 Header FieldsRequired: Content-Type

See Section 6.3.1.3.2

10.5.3.3 PayloadThe origin server shall include a successfully rendered image in the payload. If the instance was not successfully rendered, the payload may contain a Problem DetailsStatus Details document.

10.5.4 Media TypesThis service supports rendered media types. See Sections 6.3.5, 9.2.4, and Annex X for information about RS media types.

10.6 Store ServiceThe Store Service stores instances contained in the request payload at the location specified by the target resource. It is used to create or update DICOM studies on the origin server.

2925

2930

2935

2940

2945

2950

The Store Service supports only DICOM media types.

This transaction requests that the origin server create, append, or update resources for the instances contained in the request payload, that is, it stores the instances so that they can be retrieved in the future. The target resource specifies whether the instances can come from only one or from more than one study.

10.6.1 Request Transactions in this service use the POST method. The request syntax is:

POST∎/studies{/study_uid}∎version↲Content-Type: dicom-media-type↲*header-field↲↲[payload]

Where,

studyUIDstudy_uid is the Study Instance UID of a DICOM Study. If the studyUIDstudy_uid is specified all instances contained in the payload shall be from that study. Instances not matching the studyUIDstudy_uid shall be rejected.

dicom-media-type is one of the media types from [ref].

The request message has the following characteristics:

The referenced resource shall be either /studies or /studies/{study_uid}{/study_uid}. The request has no defined query parameters. The Content-Type header fields, which shall be present and contain a DICOM media type, specifies the

representation media type contained in the payload. The request must have a payload that contains one or more DICOM instances, encoded in the media type

specified by the Content-Type header field.

10.6.1.1 ResourcesThe target resource shall reference either the Studies or Study resource.

The Store service transactions and their associated resources are specified in Table 9.5-X. The URI Template associated with the resources is specified in Table 9.2-1.

Table 9.5-X: Store Service Transactions and ResourcesTransaction Resource URI TemplateStore Instances

Studies /studies{/study_uid}

Stores a set of instances possibly from different studies. The instances can later be retrieved using one of the RS Retrieve transactions.

Study /studies/{/study_uid}

Stores a set of instances that shall have the same Study Instance UID as study_uid above. The instances can later be retrieved using one of the Studies Service retrieve transactions.

10.6.1.2 Query ParametersThe Store service defines no query parameters.

10.6.1.3 Header FieldsRequired: Content-Type

2955

2960

2965

2970

2975

2980

2985

See Section 6.3.1.3.2.

10.6.1.4 PayloadThe request payload contains all the representations to be stored, in one of the DICOM media types, specified by the Content-Type header field.

10.6.2 BehaviorThe origin server will take the instances contained in the payload and store them so that they may be retrieved later using the Studies Service retrieve transactions.

However, before storing the instances the origin server may coerce or replace the values of data elements such as Patient Name, Patient ID, and Accession Number. For example, this might occur when importing media from an external institution, reconciling the instances against a master patient index, or reconciling them against an imaging procedure order. The origin server may also fix incorrect values, such as Patient Name or Patient ID; for example, because an incorrect worklist item was chosen or operator input error has occurred.

If any element is coerced or corrected, the Original Attribute Sequence (0400,0561) shall be included in the DICOM Object that is stored and may be included in the Status Details document. See Section 9.6.4.3.

Note

For more information on populating the Original Attribute Sequence see PS3.3, Section C.12.1.

10.6.3 ResponseThe response shall have the following format:

version∎status-code∎reason-phrase↲Location: {+studyURI}↲*header-field↲↲[payload]

Where,

studyURI is the URI of the created or updated Study resource.

The response shall contain a status code and reason phrase, followed by a payload containing a Status Details document, as defined in Table 6.6.1-2, in an acceptable media type. If the request does not include an Accept header field, the Content-Type of the response shall be the same as the Content-Type of the request. The payload shall be encoded in a DICOM media type as specified in Annex X. The media types that are currently supported are:

An application/dicom+xml An application/json

10.6.3.1 Status CodesThe origin server shall return an appropriate status code. The most common status codes are:

Table 10.6-x: Common Status CodesCode Description

Success

200 (OK) The origin server has successfully received, processed, and stored all of the instances contained in the request payload, and at least one of the instances belonged to an existing study.

2990

2995

3000

3005

3010

3015

3020

201 (Created) The origin server has successfully received, processed, and stored all of the instances contained in the request payload; and all the instances belonged to newly created studies.

202 (Accepted) If the origin server successfully received all the instances in the request payload, but has not stored all of them.

204 (No Content) Indicates that the server has successfully fulfilled the request and that 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.

206 (Partial Content) The origin server has successfully received and processed all the instances, but did not store all of them because of errors in processing.

Error

409 (Conflict) The origin server failed to store any of the instances contained in the request payload because of instance specific errors.

4XX See [ref]

5XX See [ref]

10.6.3.2 Header FieldsRequired: Content-Type

Location

Recommend: Warning

It is recommended that the text returned in the Warning header field (see RFC7234, Section 5.5) contain a DICOM Status Code and descriptive reason as defined in Section 10.6.4.2.1. For example,

Warning: "A700: Out of memory

See Section 6.3.1.3.2

10.6.3.3 PayloadThe payload shall contain a Status Details document that contains status information for each instance in the request payload as defined in Table 10.6-X below. The Status Details document may also include information about the the addition, modification, or deletion of attributes by the origin server, for each instance.

If the request does not contain an Accept header field, the media type of the Status Details object shall be the same as the media type of the request.

Table 10.6-X: Status DetailsAttribute Name Tag Type Attribute Description

Retrieve URL (0008,1190) 2 The URI where the Study can be retrieved.

Note: The VR of this attribute has changed from UT to UR.

Failed SOP Sequence (0008,1198) 1C A sequence of Items where each Item references an instance that was not stored.

3025

3030

3035

Attribute Name Tag Type Attribute Description

Required if any instances failed to store.

>Table 10-11 “SOP Instance Reference Macro Attributes” in PS3.3

>Failure Reason (0008,1197) 1 The reason that storage could not be provided for this instance. See Section 10.6.4.3.1.

Referenced SOP Sequence

(0008,1199) 1C A sequence of Items where each Item references an instance that was successfully stored.

Required if any instances were successfully stored.

>Table 10-11 “SOP Instance Reference Macro Attributes” in PS3.3

>Retrieve URL (0008,1190) 2 The URI where the instance can be retrieved.

Note: The VR of this attribute has changed from UT to UR.

>Warning Reason (0008,1196) 1C The reason that this instance was accepted with warnings.

Required if there was a warning for this instance. See Section 10.6.4.3.2.

>Original Attributes Sequence

(0400,0561) 3 Sequence containing all attributes that were removed or replaced by other values.

One or more Items are permitted in this sequence.

>>Attribute Modification DateTime

(0400,0562) 1 Date and time the attributes were removed and/or replaced.

>>Modifying System (0400,0563) 1 Identification of the system that removed and/or replaced the attributes.

>>Reason for the Attribute Modification

(0400,0565) 1 Reason for the attribute modification. Defined terms are:COERCE = Replace values of attributes such as Patient Name, ID,

Accession Number, for example, during import of media from an external institution, or reconciliation against a master patient index.

CORRECT = Replace incorrect values, such as Patient Name or ID, for example, when incorrect worklist item was chosen or operator input error.

>>Modified Attributes Sequence

(0400,0550) 1 Sequence that contains all the Attributes, with their previous values, that were modified or removed from the main data set.

Only a single Item shall be included in this sequence.

>>Any Attribute from the main data set that was modified or removed; may include Sequence Attributes and their Items.

10.6.3.3.1 Failure ReasonThe following values shall be used for the Failure Reason (0008,1197) in the Status Details document for this transaction:

Table 10.6-X: Failure Reason CodesCode Description

3040

A7xx - Refused out of Resources The origin server did not store the instance because it was out of resources.

A9xx - Error: Data Set does not match SOP Class

The origin server did not store the instance because the instance does not conform to its specified SOP Class.

Cxxx - Error: Cannot understand The origin server did not store the instance because it cannot understand certain Data Elements.

C122 - Referenced Transfer Syntax not supported

The origin server did not store the instance because it does not support the requested Transfer Syntax for the instance.

0110 - Processing failure The origin server did not store the instance because of a general failure in processing the operation.

0122 - Referenced SOP Class not supported

The origin server did not store the instance because it does not support the requested SOP Class.

Additional codes may be used for the Failure Reason (0008,1197) for other issues. Implementation specific Failure Reason codes shall be defined in the conformance statement and returned in the Capabilities Description document.

In the event that multiple codes may apply, the single most appropriate code shall be used.

For more information on Failure Reason Codes see PS3.3 Section X.Y.Z.

10.6.3.3.2 Warning ReasonThe following values shall be used for the Warning Reason (0008,1196) in the Store Status Details:

Table 9.6-X: Warning Reason Codes Code & Phrase DescriptionB000 - Coercion of Data Elements The origin server modified one or more data elements during storage of the

instance. See Section 6.6.1.3.B006 - Elements Discarded The origin server discarded some data elements before storing the

instance. See Section 6.6.1.3.B007 - Data Set does not match SOP Class

The origin server observed that the Data Set did not match the constraints of the SOP Class.

Additional codes may be used for the Warning Reason (0008,1196) for other issues. Implementation specific Warning Reason codes shall be defined in the conformance statement and returned in the Capabilities service response.

In the event that multiple codes may apply, the single most appropriate code shall be used.

For more information on Warning Reason Codes see PS3.3 Section X.Y.Z.

10.6.4 Media TypesThe Service is required to support uncompressed Bulkdata.

The supported media types are:

Table 10.6-x: Store Transaction Media TypesMedia Type Requiredmultipart/related; type=”application/dicom”[; transfer-syntax={ts}] Requiredmultipart/related; type=”application/dicom+xml” [; transfer-syntax={ts}] ?multipart/related; type=application/json [; transfer-syntax={ts}] ?multipart/related; type= application/octet-stream Required

3045

3050

3055

3060

Where

{ts} is an optional transfer syntax UID that specifies the transfer syntax of images contained in the payload.

See Sections 6.3.5 and 9.2.4 for information about RS media types.

See Annex X for definitions of the DICOM media types.

10.7 Search TransactionThe Search transaction searches the target resource for contained resources that match the search criteria defined by the query parameters.

10.7.1 RequestThe Search service uses the GET method and has the following message format:

GET∎{/resource}{?query*, fuzzy_matching, limit, offset}∎version↲Accept: media-type*header-field↲↲

See Section 10.7.4 for details.

10.7.1.1 ResourcesTable 10.7-1 shows the resources along with the URI templates for their target URIs.

Table 10.7-1: Search Resources, URI Templates, and DescriptionsResource URI Template and DescriptionAll Studies /studies{?query*}

Search this service for any Study matching the query parametersAll Series /series{?query*}

Searches this service for any Series that match the query parameters.Study’s Series /studies/{study_uid}/series{?query*}

Searches the specified Study for any Series matching the query parameters All Instances /instances{?query*}

Searches this service for any Instances that match the query parameters.Study’s Instances /studies/{study_uid}/instances{?query*}

Searches the specified Study for any Instances matching the query parametersSeries’ Instances /studies/{study_uid}/series/{series_uid}/instances{?query*}

Searches the specified Series in Study for any Instances matching the query parameters

Any origin server that supports this transaction shall support all resources specified in Table.

3065

3070

3075

3080

10.7.1.2 Search Query ParametersThe following table contains the ABNF for Search Request query parameters:

Table 7.1-2: ABNF Grammar for Query ParametersTerm Rulequery “?” term *(“&” term)term = *(attribute “=” value) / ; zero or more attribute-value pairs

*includefield / ; zero or more includefield parameters 0:1fuzzy / ; zero or one fuzzymatching parameters 0:1offset / ; zero or one offset parameters 0:1limit ; zero or one limit parameters

attribute = keyword *(“.” attribute) / tag *(“.” attribute)keyword ; A data element keyword from PS3.6, Table x.ytag ; A data element tag from PS3.6, Table x.y

value ; A value that corresponds to the value representation associated with the keyword or tag in PS3.6, Table x.y. If the value representation is binary then it shall be encoded in base64.

includefield = “includefield ” “=” #attribute / all

; The value is either a comma-separated list of attributes or "all", which indicates that all available attributes should be included in the response

fuzzy = “fuzzymatching” “=” “true” / “false” ; A Boolean value indicating whether fuzzy matching should be used or not.

offset = “Offset” “=” skipped-resultsskipped-results ;A non-negative integer number of results to skip, before including results in the

responselimit = “limit” “=” maximum-resultsMaximum-results ; An integer indicating the maximum number of results to return in the response

The Search service supports the following search parameters:

Parameter Key and Value Number of Values{attribute_pair}{attribute}={value} 0 to n {attribute}={value} pairs allowedIncludefield = #{attributes*} | all

0 to N includefield = #{attribute} pairs allowed. Each includefield where "all" indicates that all available attributes should be included for each response

fuzzy_matching = true /| false

A Boolean value indicating whether fuzzy matching should be used or not.

offset={skippedResults} A non-negative integer number of results to skip, before including results in the response.

limit={maximumResults} An integer indicating the maximum number of results to return in the response

In Table 10.7-2 above each {attribute} must refer to one of:

Patient IE attributes Study IE attributes

3085

3090

Series IE attributes (only Search for Series or Search for Instances requests) Composite Instance IE attributes (only Search for Instances requests) Additional Query/Retrieve Attributes (PS3.4 Section C.3.4) Timezone Offset From UTC (0008,0201)

The next section give the encoding rules for {attribute} and {value}.

10.7.1.2.1 Encoding Rules for {attribute} and {value}

1. Each {attribute} parameter name shall be unique unless the associated DICOM Attribute allows UID List matching (see PS3.4 Section C.2.2.2.2), in which case the {value} is a comma-separated list of UIDs.

2. The acceptable values for {value} are determined by the types of matching allowed by C-FIND for its associated {attribute}. See PS3.4 Section C.2.2.2. All characters in {value} that are disallowed in the query component of URIs shall be percent-encoded. See [RFC3986 ] for details.

3. If an {attribute} is a value of an "includefield" parameter, it is equivalent to C-FIND Universal matching for that attribute. See PS3.4 Section C.2.2.2.3.

{attribute} can be one of the following:

{tag} where, {tag} is a string with eight hexadecimal string corresponding to the Tag of a data element (see PS3.6, Section 6),

{keyword} where, {keyword} is the Keyword of a data element (see PS3.6, Section 6),,

{tag}.{attribute} where, {attribute} is an element of the sequence specified by {tag}, or

{keyword}.{attribute} where, {attribute} is an element of the sequence specified by {keyword}.

Notes

1. Examples of valid values for {attribute}:

0020000DStudyInstanceUID00101002.00100020OtherPatientIDsSequence.PatientID00101002.00100024.00400032OtherPatientIDsSequence.IssuerOfPatientIDQualifiersSequence.UniversalEntityID

2. Examples of valid Search URLs:

http://dicomrs/studies?PatientID=11235813http://dicomrs/studies?PatientID=11235813&StudyDate=20130509http://dicomrs/studies?00100010=SMITH*&00101002.00100020=11235813&limit=25http://dicomrs/studies?00100010=SMITH*&OtherPatientIDsSequence.00100020=11235813http://dicomrs/studies?PatientID=11235813&includefield=00081048&includefield=00081049

&includefield=00081060http://dicomrs/studies?PatientID=11235813&StudyDate=20130509-20130510http://dicomrs/studies ?

StudyInstanceUID=1.2.392.200036.9116.2.2.2.2162893313.1029997326.94587 %2c1.2.392.200036.9116.2.2.2.2162893313.1029997326.94583

10.7.1.2.2 ABNF Grammar for Search Query Parametersattribute = name = valuesname = keyword [ *( “.” attribute ) ] / tag [ *( “.” attribute) ]

Where <keyword>s, <tag>s, and <values> are defined in PS3.6 Table 6-1. The encoding of the <value> above shall be defined by the media type.

3095

3100

3105

3110

3115

3120

3125

3130

3135

10.7.1.2.3 Fuzzy MatchingThe “fuzzy_matching” parameter specifies whether fuzzy matching of Person Names shall be performed by the origin server. It is optional. If the parameter is not present then its value is “false”. See PS3.X Section…

10.7.1.2.4 Offset, Limit and Number of Results ReturnedThe user agent can use the “offset” and “limit” parameters to control the set of results return. These parameters allow the user agent to paginate the results.

10.7.1.3 Header FieldsRequired: Accept

See Section 6.3.1.3.

10.7.1.4 PayloadThe request has no payload.

10.7.2 BehaviorThe origin server shall perform the search indicated by the request and it shall return the search results or, when the search cannot be performed, a failure status code.

10.7.2.1 MatchingThe matching semantics for each attribute are determined by the types of matching allowed by C-FIND (see Section C.2.2.2 in PS3.4).

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

Combined DateTime matching shall be performed (see Section C.2.2.2.5 in PS3.4).

Note

If an origin server is acting as a proxy for a C-FIND SCP that does not support combined DateTime matching, it will need to perform a C-FIND request using Date only and filter results outside the time range before returning a response

If the TimezoneOffsetFromUTC / 00080201 parameter name is included in the request, dates and times in the request are to be interpreted in the specified time zone.

If the "fuzzymatchingfuzzy_matching” query parameter is included in the request and its value is “true", and it is supported then additional fuzzy semantic matching of person names shall be performed in the manner specified in the DICOM Conformance Statement for the origin server. If Fuzzy Matching is not supported, the response shall include the following HTTP/1.1 Warning header:

Warning: 299 {+service}: "Fuzzy Matching is not supported. Only literal matching has been performed."

where {+service} is the base URL for the service. See RFC 7230 Section for more information in the Warning header field.

Note

The Warning header field is separate from the Status Line and does not affect the returned Status Code.

3140

3145

3150

3155

3160

3165

3170

10.7.2.1.1 Required Query ParametersThe origin server shall support the query parameters described in Table 10.7-X:

Table 10.7-X: Search ParametersIE Level Keyword Tag

Study StudyDate 00080020

StudyTime 00080030

AccessionNumber 00080050

ModalitiesInStudy 00080061

ReferringPhysicianName 00080090

PatientName 00100010

PatientID 00100020

StudyInstanceUID 0020000D

StudyID 00200010

Series Modality 00080060

SeriesInstanceUID 0020000E

SeriesNumber 00200011

PerformedProcedureStepStartDate 00400244

PerformedProcedureStepStartTime 00400245

RequestAttributeSequence 00400275

>ScheduledProcedureStepID 00400009

>RequestedProcedureID 00401001

Instance SOPClassUID 00080016

SOPInstanceUID 00080018

InstanceNumber 00200013

If studyUIDstudy_uid is not specified in the resource-path and this formSeries-Level of Relational Search is supported, all Study-level attributes specified in Table 10.7-X shall also be supported.

If {SeriesUID}{series_uid} is not specified in the URL and this form ofInstance-Level Relational Search is supported, all Series-level attributes specified in Table 10.7-X shall also be supported.

10.7.2.1.2 Fuzzy MatchingFuzzymatching = true / false

If the “fuzzymatchingfuzzy_matching” parameter is not present then it defaults to false and no fuzzy matching will be performed. If the parameter is present with a value isof “true” and the origin server supports fuzzy matching then additional fuzzy semantic matching of person names shall be performed in the manner specified in the DICOM Conformance Statement for the origin server. See PS3.X Section Y.Z.

3175

3180

10.7.2.2 Pagination using Offset and LimitIf the “limit” parameter is not specified or its value exceeds the total number of matching results then {maximumResults} is the lesser of the number of matching results and the maximum number of results supported by the Server.

If the “offset” parameter is not specified or its value is less than zero then {skippedResults} is zero.

The first result returned shall be result number ({skippedResults} + 1). The last result returned shall be result number ({skippedResults} + {maximumResults}). If ({skippedResults} + 1) exceeds {maximumResults} then no results are returned.

If the number of results exceeds the maximum supported by the server, the server shall return the maximum supported results and the response shall include the following HTTP/1.1 Warning header field. See RFC7230 Section 5.5:

Warning: 299 {SERVICE}: "The number of results exceeded the maximum supported by the server. Additional results can be requested.

The server shall be idempotent so that if the list of results is the same, the response to a request with a specific set of parameters shall always be the same, including order. If the complete list of results is different for subsequent transactions the responses may be different. In a situation where results are changing due to changes in the server contents, queries using the limit and offset may be inconsistent.

10.7.3 ResponseThe response will contain …

The response format depends on the Accept header specified in the request.

10.7.3.1 Status CodesTable 10.7-4 lists the status codes that shall be used to report any of the associated error and warning situations. Other error codes may be present for other error and warning situations.

Table 10.7-X: Status CodesStatus Code Description

Success 200 The query completed and any matching results are returned in the message body.

206 ToDo

Failure See Section X.Y.Z.

10.7.3.2 Header FieldsRequired: Content-Type

WarningSee Section 6.3.1.3.2<#6.3.1.3.2>

10.7.3.3 PayloadThe response payload will contain the following information.

10.7.3.3.1 Response Payload of Search for StudyFor each matching Study, the origin server shall return all attributes in accordance with Table 6.7.1-2:

3185

3190

3195

3200

3205

3210

3215

Table 6.7.1-2. Search for Study Response PayloadAttribute Name Tag Notes

Specific Character Set (0008,0005) If necessary for encoding any returned attributes

Study Date (0008,0020)

Study Time (0008,0030)

Accession Number (0008,0050)

Instance Availability (0008,0056)

Modalities in Study (0008,0061)

Referring Physician's Name (0008,0090)

Timezone Offset From UTC (0008,0201) May be absent if no value is available

Retrieve URL (0008,1190) Shall be empty if the resource cannot be retrieved via an RS retrieve service

Note

The VR of this attribute has changed from UT to UR.

Patient's Name (0010,0010)

Patient ID (0010,0020)

Patient's Birth Date (0010,0030)

Patient's Sex (0010,0040)

Study Instance UID (0020,000D)

Study ID (0020,0010)

Number of Study Related Series (0020,1206)

Number of Study Related Instances (0020,1208)

All other Study Level DICOM Attributes passed as {attributeIDattribute} query parameters that are supported by the origin server as matching or return attributes

All other Study Level DICOM Attributes passed as "include" query parameter values that are supported by the origin server as return attributes

All available Study Level DICOM Attributes if the "include" query parameter is included with a value of "all"

Series Level and Instance Level attributes passed as "include" query values shall not be returned.

Note

The above list is consistent with those required for IHE RAD-14 (see http://www.ihe.net/Technical_Framework/upload/IHE_RAD_TF_Vol2.pdf Table 4.14-1).

10.7.3.3.2 Response Payload of Search for Series

For each matching Series, the origin server shall return all attributes listed in Table 6.7.1-2a:

Table 6.7.1-2a. Search for Series Response PayloadAttribute Name Tag Notes

Specific Character Set (0008,0005) If necessary for encoding any returned attributes

3220

3225

Attribute Name Tag Notes

Modality (0008,0056)

Timezone Offset From UTC (0008,0201) May be absent if no value is available

Series Description (0008,103E) May be absent if no value is available

Retrieve URL (0008,1190) Shall be empty if the resource cannot be retrieved via the Retrieve DICOM service

Note

The VR of this attribute has changed from UT to UR.

Series Instance UID (0020,000E)

Series Number (0020,0011)

Number of Series Related Instances (0020,1209)

Performed Procedure Step Start Date (0040,0244) May be absent if no value is available

Performed Procedure Step Start Time (0040,0245) May be absent if no value is available

Request Attribute Sequence (0040,0275) May be absent if no value is available

>Scheduled Procedure Step ID (0040,0009)

>Requested Procedure ID (0040,1001)

All other Series Level DICOM Attributes passed as {attributeIDattribute} query parameters that are supported by the origin server as matching or return attributes

All other Study or Series Level DICOM Attributes passed as "include" query parameter values that are supported by the origin server as return attributes

All available Instance Level DICOM Attributes if the "include" query parameter is included with a value of "all"

If {studyUID}{study_uid} is not specified, all sStudy-level attributes specified in Table 6.7.1-2

Instance Level attributes passed as "include" query values shall not be returned.

Note

The above list is consistent with the attributes required for IHE RAD-14 (see http://www.ihe.net/Technical_Framework/upload/IHE_RAD_TF_Vol2.pdf Table 4.14-1).

10.7.3.3.3 Response Payload of Search for InstanceFor each matching instance, the origin server shall return all attributes listed in Table 6.7.1-2b:

Table 6.7.1-2b. Response Payload of Search for InstanceAttribute Name Tag Notes

Specific Character Set (0008,0005) If necessary for encoding any returned attributes

SOP Class UID (0008,0016)

SOP Instance UID (0008,0018)

Instance Availability (0008,0056)

Timezone Offset From UTC (0008,0201) May be absent if no value is available

Retrieve URL (0008,1190) Shall be empty if the resource cannot be retrieved via a Retrieve service

3230

Attribute Name Tag Notes

Note

The VR of this attribute has changed from UT to UR.

Instance Number (0020,0013)

Rows (0028,0010) Only present for Image Instances

Columns (0028,0011) Only present for Image Instances

Bits Allocated (0028,0100) Only present for Image Instances

Number of Frames (0028,0008) Only present for Multi-frame image instances

All other Instance Level Attributes passed as {attributeIDattribute} query keys that are supported by the origin server as matching or return attributes

All other Study, Series or Instance Level Attributes passed as "include" query values that are supported by the origin server as return attributes

All available Instance Level Attributes if the "include" query key is included with a value of "all"

If {studyUID}{study_uid} is not specified, all Study-level attributes specified in Table 6.7.1-2

If {SeriesInstanceUIDseries_uid} is not specified, all Series-level attributes specified in Table 6.7.1-2a

Note

The above list is consistent with the attributes required for IHE RAD-14 (see http://www.ihe.net/Technical_Framework/upload/IHE_RAD_TF_Vol2.pdf Table 4.14-1 and Table 4.14-2).

10.7.4 Media TypesThe origin server shall support the following media types:

multipart/related; type=application/dicom+xml

11 Retrieve Capabilities Transaction

Closed Issues# Issues

Open Issues# Issues

3235

3240

The Retrieve Capabilities transaction requests that the target service return a machine readable document, called the Capabilities Description, of the transactions, resources, and representations provided by that service.

The Retrieve Capabilities Service transaction shall be implemented by each restful service defined in this standard. a single transaction which shall be supported by all implementations.

[11.1] TransactionsThe Retrieve Capabilities Service supports the transactions in Table 9.8-1. If an origin server supports this service it shall support all transactions.

Table 9.4-1: Retrieve Capabilities TransactionTransaction URI Template DescriptionRetrieve Capabilities Retrieve a descriptions of the service’s capabilities in an acceptable

media type.

[11.2] RequestThe Retrieve Capabilities request uses the OPTIONS method and has the following format:

OPTIONS∎/∎version↲*header-field↲↲

Where,

“/” is the base URL for the service. This may be a combination of protocol (either http or https), host, port, and application. See Section 9.2.1 for details.

[11.2.1] ResourcesThe only resource supported by this transaction is a service itself. Each RS service will support this transaction.

[11.2.2] Query ParametersThis service has no query parameters.

[11.2.3] Header FieldsRequired: Accept

See Section 6.3.1.3.

3245

3250

3255

3260

3265

[11.2.4] PayloadThe request has no payload.

[11.2.5] BehaviorThe origin server will return a machine readable description of its capabilities in an acceptable media type.

[11.2.6] ResponseThe format of the response is as follows:

version∎status-code∎reason-phrase↲Content-Type: {media-type}↲*header-field↲↲[payload]

All responses have single part payloads. A successful response will return a Web Application Description Language (WADL) document encoded in a Media Type consistent with the Accept header of the request.

[11.3] Status CodesA success response will have a status code of 200 (OK).

A failure response will have a status code from Table X.Y-Z.

[11.3.1] Header FieldsRequired: Content-TypeSee Section 6.3.1.3.2.

[11.3.1.1] PayloadA success payload is single part and contains a representation of a WADL document in an acceptable media type.

The WADL document shall contain one top-level "application" element, which shall contain one "resources" element whose "base" attribute value is “/”, which is the base URL for the Storage Service.

A failure response may have an empty payload; however, it is recommended that it contains a “Problem Details” document. See Section 7.2.3.3.

[11.3.2] Media TypesThe Retrieve Capabilities service supports the following media types:

application/vnd.sun.wadl+xml

application/json

See Annex X, Y, …

[11.3.3] WADL Document FormatThe full WADL resource tree follows directly and unambiguously from the RESTful resource endpoints defined in 6.5, 6.6, 6.7 and 6.9.

3270

3275

3280

3285

3290

3295

3300

For informative purposes, the full resource tree and the methods defined for each resource are described in Table 9.8-X.

Table 9.8-XResources and MethodsResource Methods supported (excluding Retrieve Capabilities) Reference

/ N/A N/A

studies SearchForStudiesStoreInstances

6.8.1.2.2.36.8.1.2.2.2

{StudyUID} RetrieveStudyStoreStudyInstances

6.8.1.2.2.16.8.1.2.2.3

metadata RetrieveStudyMetadata 6.8.1.2.2.1

series SearchForStudySeries 6.8.1.2.2.3

{SeriesInstanceUID} RetrieveSeries 6.8.1.2.2.1

metadata RetrieveSeriesMetadata 6.8.1.2.2.1

instances SearchForStudySeriesInstances 6.8.1.2.2.3

{SOPInstanceUID} RetrieveInstance 6.8.1.2.2.1

metadata RetrieveInstanceMetadata 6.8.1.2.2.1

frames N/A N/A

{framelist} RetrieveFrames 6.8.1.2.2.1

instances SearchForStudyInstances 6.8.1.2.2.3

series SearchForSeries 6.8.1.2.2.3

{SeriesInstanceUID} N/A N/A

{instances} SearchForInstances 6.8.1.2.2.3

instances SearchForInstances 6.8.1.2.2.3

{BulkDataURL} RetrieveBulkData 6.8.1.2.2.1

workitems SearchForUPSCreateUPS

6.8.1.2.2.36.8.1.2.2.2

{UPSInstanceUID} RetrieveUPSUpdateUPS

6.8.1.2.2.16.8.1.2.2.4

state ChangeUPSState 6.8.1.2.2.4

cancelrequest RequestUPSCancel 6.8.1.2.2.4

subscribers N/A N/A

{AETitle} CreateSubscriptionDeleteSubscription

6.8.1.2.2.56.8.1.2.2.5

1.2.840.10008.5.1.4.34.5 N/A N/A

subscribers N/A N/A

{AETitle} CreateSubscriptionDeleteSubscription

6.8.1.2.2.56.8.1.2.2.5

suspend SuspendGlobalSubscription 6.8.1.2.2.5

Resource Methods supported (excluding Retrieve Capabilities) Reference

1.2.840.10008.5.1.4.34.5.1 N/A N/A

subscribers N/A N/A

{AETitle} CreateSubscriptionDeleteSubscription

6.8.1.2.2.56.8.1.2.2.5

suspend SuspendGlobalSubscription 6.8.1.2.2.5

11.1.1.1[11.3.3.1] Methods

11.1.1.1.1[11.3.3.1.1] Retrieve MethodsThe Retrieve methods define the capabilities of one of the following resources:

A WADO-RS resource (see 6.5) or A Retrieve UPS resource (see 6.9.4).

The Retrieve methods shall contain the following attributes:

A "name" attribute with a value of "GET" An "id" attribute with a value of "RetrieveStudy", "RetrieveSeries", "RetrieveInstance", "RetrieveBulkData",

"RetrieveFrames", "RetrieveStudyMetadata", "RetrieveSeriesMetadata", "RetrieveInstanceMetadata" or "RetrieveUPS"

The Retrieve methods shall contain a "request" element with "param" elements documenting the following:

supported Accept header valueso if the same Media Type is supported with multiple Transfer Syntaxes there should be one entry for each

combination of Media Type and Transfer Syntax

The Retrieve methods shall contain one or more "response" elements documenting the following:

supported Status Codes Media Types returned for each Status Code (if applicable)

o if the same Media Type is supported with multiple Transfer Syntaxes there should be one entry for each combination of Media Type and Transfer Syntax

Note

More than one Status Code can be described by a single "response" element.

Example:

<method name="GET" id="RetrieveStudies"> <request> <param name="Accept" style="header" default="multipart/related; type=application/dicom"> <option value="multipart/related; type=application/dicom" /> <option value="multipart/related; type=application/dicom"; transfer-syntax=1.2.840.10008.1.2 /> <option value="multipart/related; type=application/dicom"; transfer-syntax=1.2.840.10008.1.2.1 /> <option value="multipart/related; type=application/octet-stream" /> <option value="multipart/related; type=image/dicom+jpx" /> <option value="multipart/related; type=image/dicom+jpx; transfer-syntax=1.2.840.10008.1.2.4.92" /> <option value="multipart/related; type= video/mpeg; transfer-syntax=1.2.840.10008.1.2.4.100" /> </param>

3305

3310

3315

3320

3325

3330

3335

3340

</request> <response status="200,206"> <representation mediaType="multipart/related; type=application/dicom"; transfer-syntax=1.2.840.10008.1.2 /> <representation mediaType="multipart/related; type=application/dicom"; transfer-syntax=1.2.840.10008.1.2.1 /> <representation mediaType="multipart/related; type=application/octet-stream" /> <representation mediaType="multipart/related; type= image/dicom+jpx" /> <representation mediaType="multipart/related; type= image/dicom+jpx; transfer-syntax=1.2.840.10008.1.2.4.92" /> <representation mediaType="multipart/related; type= video/mpeg; transfer-syntax=1.2.840.10008.1.2.4.100" /> </response> <response status="400 404 406 410 503" /></method>

11.1.1.1.2[11.3.3.1.2] Store Methods

The Store methods define the capabilities of a Store resource (see 6.6) or a CreateUPS resource (see 6.9.1).

The Store methods shall contain the following attributes:

A "name" attribute with a value of "POST" An "id" attribute with a value of "StoreInstances", "StoreStudyInstances" or "CreateUPS"

The Store methods shall contain a "request" element with "param" elements documenting the following:

supported Accept header values supported Representations

if the same Media Type is supported with multiple Transfer Syntaxes there should be one entry for each combination of Media Type and Transfer Syntax

The Store methods shall contain one or more "response" elements documenting the following:

supported Status Codes Media Types returned for each Status Code (if applicable) Headers returned for each Status Code

Note

More than one Status Code can be described by a single "response" element.

Example:

<method name="GET" id="StoreInstances"> <request> <param name="Accept" style="header" default="application/dicom+xml"> <option value="application/dicom+xml" /> </param> <representation mediaType="multipart/related; type=application/dicom" /> <representation mediaType="multipart/related; type=application/dicom; transfer-syntax=1.2.840.10008.1.2" /> <representation mediaType="multipart/related; type=application/dicom; transfer-syntax=1.2.840.10008.1.2.1" /> <representation mediaType="multipart/related; type=application/dicom+xml" /> <representation mediaType="multipart/related; type=application/dicom+xml; transfer-syntax=1.2.840.10008.1.2" /> <representation mediaType="multipart/related; type=application/dicom+xml; transfer-syntax=1.2.840.10008.1.2.1" /> <representation mediaType="multipart/related; type=application/dicom+xml;

3345

3350

3355

3360

3365

3370

3375

3380

3385

3390

transfer-syntax=1.2.840.10008.1.2.4.92" /> <representation mediaType="multipart/related; type=application/dicom+xml; transfer-syntax=1.2.840.10008.1.2.4.100" /> </request> <response status="200" /> <response status="202,409"> <representation mediaType="application/dicom+xml" /> </response> <response status="400,401,403,503" /></method>

11.1.1.1.3[11.3.3.1.3] Search Methods

The Search methods define the capabilities of a Search Transaction (see 6.7) or a SearchForUPS resource (see 6.9.3).

The Search methods shall contain the following attributes:

A "name" attribute with a value of "GET" An "id" attribute with a value of "SearchForStudies", "SearchForStudySeries", "SearchForSeries",

"SearchForStudySeriesInstances", "SearchForStudyInstances", "SearchForSeriesInstances", "SearchForInstances" or "SearchForUPS"

The Search methods shall contain a "request" element with "param" elements documenting the following:

supported Accept header values support for the Cache-control header support of "limit", "offset" and "fuzzymatchingfuzzy_matching" query parameters supported search parameters (both tag and keyword variants shall be listed) supported options for the "includefield" parameter (both tag and keyword variants shall be listed)

The Search methods shall contain one or more "response" elements documenting the following:

supported Status Codes returned "header" parameters, including use of "warning headers" Media Types returned for each Status Code (if applicable)

Note

More than one Status Code can be described by a single "response" element.

Example:

<method name="GET" id="SearchForStudies"> <request> <param name="Accept" style="header" default="multipart/related; type=application/dicom+xml"> <option value="multipart/related; type=application/dicom+xml" /> <option value="application/json" /> </param> <param name="Cache-control" style="header"> <option value="no-cache" /> </param> <param name="limit" style="query" /> <param name="offset" style="query" /> <param name="fuzzymatchingfuzzy_matching" style="query" /> <param name="StudyDate" style="query" /> <param name="00080020" style="query" /> <param name="StudyTime" style="query" /> <param name="00080030" style="query" />

3395

3400

3405

3410

3415

3420

3425

3430

3435

3440

… <param name="includefield" style="query" repeating="true" /> <option value="all" /> <option value="00081049" /> <option value="PhysiciansOfRecordIdentificationSequence" /> <option value="00081060" /> <option value="NameOfPhysiciansReadingStudy" /> … </param></request><response status="200"> <representation mediaType="multipart/related; type=application/dicom+xml" /> <representation mediaType="application/json" /></response><response status="400 401 403 413 503" /></method>

11.1.1.1.4[11.3.3.1.4] Update Methods

The Update methods define the capabilities of an UpdateUPS, a ChangeUPSState or a RequestUPSCancellation resource (see 6.9.2).

The Update methods shall contain the following attributes:

A "name" attribute with a value of "POST" for UpdateUPS and RequestUPSCancel A "name" attribute with a value of "PUT" for ChangeUPSState An "id" attribute with a value of "UpdateUPS", "ChangeUPSState" or "RequestUPSCancellation"

The Update methods shall contain a "request" element with "param" elements documenting the following:

supported Representations

The Update methods shall contain one or more "response" elements documenting the following:

supported Status Codes Headers returned for each Status Code

Note

More than one Status Code can be described by a single "response" element.

Example:

<method name="POST" id="UpdateUPS"> <request> <representation mediaType="application/dicom+xml" /> <representation mediaType="application/json" /> </request> <response status="200"> <param name="Warning" style="header" fixed="299 {+svc}: The UPS was created with modifications." /> <param name="Warning" style="header" fixed="299 {+svc}: Requested optional Attributes are not supported." /> </response> <response status="409"> <param name="Warning" style="header" fixed="299 {+svc}: The Transaction UID is missing." /> <param name="Warning" style="header" fixed="299 {+svc}: The Transaction UID is incorrect." /> <param name="Warning" style="header" fixed="299 {+svc}: The submitted request is inconsistent with the current state of the UPS Instance." />

3445

3450

3455

3460

3465

3470

3475

3480

3485

3490

</response> <response status="400 401 403 404 503" /></method>

Where {+svc} is the base URI for the service.

11.1.1.1.5[11.3.3.1.5] Subscribe Methods

The Subscribe methods define the capabilities of a Create Subscription, a Suspend Global Subscription or a Delete Subscription resource (see 6.9.7, 6.9.8 and 6.9.9).

The Subscribe methods shall contain the following attributes:

A "name" attribute with a value of "POST" for CreateSubscription and SuspendGlobalSubscription A "name" attribute with a value of "DELETE" for DeleteSubscription An "id" attribute with a value of "CreateSubscription", "SuspendGlobalSubscription" or "DeleteSubscription"

The Subscribe methods shall contain a "request" element with "param" elements documenting the following:

supported Representations

The Subscribe methods shall contain one or more "response" elements documenting the following:

supported Status Codes Headers returned for each Status Code

Note

More than one Status Code can be described by a single "response" element.

Example:

<method name="POST" id="CreateSubscription"> <request> <param name="deletionlock" style="query" default="false"> <option value="true" /> <option value="false" /> </param> </request> <response status="201"> <param name="Warning" style="header" fixed="299 {+svc}: Deletion Lock not granted." /> </response> <response status="403"> <param name="Warning" style="header" fixed="299 {+svc}: The origin server does not support Global Subscription Filtering." /> </response> <response status="400 401 404 409 503" /></method>

Where {+svc} is the base URI for the service.

12 Unified Workflow and Procedure Step (UPS Worklist) Service

3500

3505

3510

3515

3520

3525

3530

Closed Issues# Issues

Open Issues# Issues

The UPS Worklist service, or just Worklist service, defines a RESTful interface to the UPS SOP Classes in PS3.3 [link] & PS3.4 [link].

If an origin server implements a Worklist service, it manages a single (global) worklist. user agents can create, update, retrieve, search for and request cancellation of work items on that worklist. Each work item is identified by a DICOM UID.

Subscriptions

User agents can also request notifications

User agents can also request to receive notifications called Event Reports for a single work item or for all work items managed by the origin server. In order to receive notifications the user agent must first request that the origin server open an event channel to the user agent.

b open an event channel changes state or when subscribe, unsubscribe, or suspend

This RS Service defines a RESTful interface to the UPS SOP Classes (see PS3.3 & PS3.4).

A UPS origin server manages one worklist, aka the Global Worklist

Terminology

Worklist

Work item Each work item is a UPS SOP Instance, we will prefer the term work item because it is more

C-FIND

Event Report (N-Event-Report)

3535

3540

3545

3550

3555

N-ACTION

N-CREATE

N-GET

N-FIND

Need a general transition diagram that shows the states and transitions without subscriptions

Need another one with subscriptions

12.1 Overview

12.1.1 TransactionsThe UPS Service supports following transactions:

Transaction MethodRequestPayload

ResponsePayload Description

Capabilities GET Empty 1 work itemCreate POST 1 work item emptyUpdate PUT N attributes emptySearch GET Empty N resultsRetrieve GET Empty 1 work itemChange State PUT ? NoRequest Cancellation POST Yes NoCreate Subscription POST Empty EmptySuspend Subscription POST Empty EmptyDelete Subscription DELETE Empty EmptyOpen Event Channel GET Empty EmptySend Event Report --- Yes Empty

Table X.Y-A: UPS Worklist TransactionsUPS Transaction Description UPS DIMSE [link]Create Requests the creation of a UPS Instance on the origin

server.N-CREATE

Update This action sets the attributes of a UPS Instance managed by the origin server.

N-SET

Search Searches for work items C-FINDRetrieve Retrieves a work item N-GETChange State Changes the state of a work item N-ACTION

"Change UPS State"Request Cancellation

Requests the cancellation of a work item N-ACTION"Request UPS Cancel"

Create Subscription Creates a subscription N-ACTION"Subscribe to Receive Event Reports".

Suspend Global Subscription

Suspends an existing subscription to the Global Worklist

N-ACTION"Suspend Global Subscription".

Delete Subscription Cancels an existing subscription to a work item or to N-ACTION

3560

3565

the Global Worklist “Unsubscribe from Receiving Event Reports”

Open Event Channel

Initiates a WebSocket connection to the origin server to allow the user agent to start receiving Event Report messages

Send Event Report The origin server sends an Event Report to a user agent using a WebSocket connection.

N-EVENT-REPORT

An origin server shall support all UPS Worklist server transactions.

The requirements for a UPS origin server that is also a Unified Worklist and Procedure Step SCP are described in PS3.4 Section CC.1. [link]

12.1.2 UPS Requests OverviewThe Worklist service transactions used the method and resource URI template specified in Table 9.9-A

Table 9.9-A: Worklist Methods and ResourcesTransaction Section Method Method & Resource

Create 6.9.1 POST /workitems{?WorkItemUID}

Update 6.9.2 POST /workitems/{WorkItemUID}{?transaction}

Search 6.9.3 GET /workitems{?query*}

Retrieve 6.9.4 GET /workitems/{workItemUID}

Change State 6.9.5 PUT /workitems/{workItemUID}/state

Request Cancellation

6.9.6 POST /workitems/{workItemUID}/cancelrequest

Create Subscription

6.9.7 POST /workitems/{workItemUID}/subscribers/{AETitle}{?deletionlock}/workitems/1.2.840.10008.5.1.4.34.5/subscribers/{AETitle}{?deletionlock}/workitems/1.2.840.10008.5.1.4.34.5.1/subscribers/{AETitle}{?deletionlock,query*}

Suspend Global Subscription

6.9.8 POST /workitems/1.2.840.10008.5.1.4.34.5/subscribers/{AETitle}/suspend/workitems/1.2.840.10008.5.1.4.34.5.1/subscribers/{AETitle}/suspend

Delete Subscription

6.9.9 DELETE /workitems/{workItemUID}/subscribers/{AETitle}

Open Event Channel

6.9.10 GET {+socket}/subscribers/{AETitle}

Send Event Report

6.9.11 N/A N/A

Acknowlege?

The origin server shall comply with all requirements placed on the SCP for the corresponding services in Annex CC in PS3.4.

3570

3575

12.1.2.1 Resources

12.1.2.2 Query Parameters

12.1.2.3 Header FieldsRequired: Accept

See Section 6.3.1.3

12.1.2.4 PayloadThe payload depends on the transaction.

12.1.3 Behavior OverviewTODO

12.1.4 Response Overview

12.1.4.1 Status CodesThe status codes defined in Table X.Y-Z below are the primary status codes used by this service; however, any of the status codes in Table 6.X-Z might be used by the transactions defined by this service.

Table X.Y-1. Status CodesStatus Code Reason Phrase Description

Success 200 OK The work item was updated

201 Created The work item was created

206 Partial Content Only some of the query results were returned and the rest can be requested.

Failure 400 Bad Request The UPS-RS origin server was unable to understand the request

401 Unauthorized The UPS-RS origin server refused to accept the request because the client is not authenticated.

403 Forbidden The UPS-RS origin server understood the request, but is refusing to perform the query (e.g., an authenticated user with insufficient privileges).

404 Not found The specified UPS Instance does not exist or is not managed by this origin server.

409 Conflict The request cannot be performed for one of the following reasons: the submitted request is inconsistent with the current state of the UPS Instance the Transaction UID is missing, or the Transaction UID is incorrect

503 Busy Service is unavailable.

12.1.5 Media TypesThe media types supported by the UPS Worklist service are:

application/jsonapplication/dicom+xml

3580

3585

3590

3595

Add a table of language mapping from ps3.4 to worklist

12.2 Basic Transactions

12.2.1 Create Work Item Transaction

12.2.1.1 RequestThe request has the following format:

POST∎/workitems/{?workItemUID}∎version↲Content-Type: media-type↲*header-field↲↲[payload]

Where,

workItemUID specifies the Affected SOP Instance UID (0000,1000) of the requested work item. If no workItemUID is specified the origin server will create and assign a new UID. See [ref] on creating UIDs from UUIDs.

media-type is a media type supported by the service.

12.2.1.2 ResourcesTODO

12.2.1.3 Query ParametersworkItemUID specifies the UID of the created work item. It is optional, if not supplied the origin server will create and assign a new UID. See [ref] on creating UIDs from UUIDs.

12.2.1.4 Header FieldsRequired: Content-Type

See Section 6.3.1.3.

12.2.1.5 PayloadThe payload shall be single part and shall contain a single work item. The work item will contain all attributes to be stored. Any binary data contained in the payload shall be inline (ref element in xml & json).

The work item shall comply with all instance requirements in the Req. Type N-CREATE column of Table CC.2.5-3 in PS3.4.

12.2.1.6 BehaviorThe origin server shall create and maintain work items as specified in the request, and as specified by the SCP behavior defined in PS3.4 Section CC.2.5.3.

12.2.1.7 ResponseThe response has the following format:

version∎status-code∎reason-phrase↲Location: {+workItemURI}↲

3600

3605

3610

3615

3620

3625

3630

*header-field↲↲Where,

{+workItemURI} is the URI of the created work item.

The origin server shall return an appropriate status code, with no payload.

12.2.1.8 Status CodesA successful response will contain a status code of 201 (Created).

A failure response will contain an appropriate failure status code from table X.Y-A.

12.2.1.9 Header FieldsRequired in success response:

Content-Location

Location The URI of the created work item. This URI shall correspond to the created resource, not to a particular representation.

If the work item was modified by the origin server the response shall also have the following header:

Warning: 299 {+service}: The Work Item was created with modifications.↲See Section 6.3.1.3.2.

12.2.1.10 PayloadThe response payload is empty.

12.2.2 Retrieve Work ItemThis transaction retrieves a Work Item from a Worklist.

12.2.2.1 RequestGET∎/workitems/{workItemUID}∎version↲Accept: {media-type}↲*header-field↲↲

Where,

{workItemUID}workItemUID is the UID of a Work Item.

12.2.2.2 Header FieldsRequired: Accept

Recommended: Cache-control: no-cache

If included, specifies that search results returned should be current and not cached.

See Section 6.3.1.3

3635

3640

3645

3650

3655

3660

12.2.2.3 PayloadThe request payload is empty.

12.2.2.4 BehaviorThe origin server shall return the specified Work Item.

Note

The requirement for the origin server to respond to GET requests for UPS Instances that have moved to the COMPLETED or CANCELED state is limited. See Section CC.2.1.3 in PS3.4.

The user agent origin server shall not return the Transaction UID (0008,1195) attribute of the Work Item. This is necessary to preserve this Attribute's role as an access lock.

12.2.2.5 ResponseThe response shall have the following format:

version∎status-code∎reason-phrase↲Content-Type: text/plain↲*header-field↲↲[payload]

12.2.2.6 Status CodesA success response will contain a status code of 200 (OK).

A failure response will contain an appropriate status code from Table 12.2-A.

12.2.2.7 Header FieldsRequired: Content-Type

See Section

12.2.2.8 PayloadA success response has a single part payload containing the requested Work Item in an acceptable media type.

A failure response payload shall be empty.

12.2.2.9 Media TypesAn origin server shall support all media-types allowed in the request.

The media types supported by this transaction are:

application/dicom+xml”application/json

12.2.3 Update Work Item TransactionThe transaction modifies an existing work item.

12.2.3.1 RequestThe request has the following format:

POST∎/workitems/{workitemUID}{?transactionUID}∎version↲

3665

3670

3675

3680

3685

3690

3695

Content-Type: media-type↲*header-field↲↲[payload]

Where,

workItemUID is the UID of the work item.

transactionUID is the Transaction UID for the specified work item.

If the UPS instance is currently in the SCHEDULED state, {transactionUID} shall not be specified.

If the UPS instance is currently in the IN PROGRESS state, the {transactionUID} shall be specified.

Because the request will be treated as atomic (indivisible) and idempotent (repeating the same request has no additional effect), all changes contained in the request shall leave the Work Item in an internally consistent state.

12.2.3.2 Query ParametersRequired if work item state is IN-PROGRESS:

transactionUID the UID of the lock that is used to modify the work item or change its state if the work item is IN-PROGRESS.

12.2.3.3 Header FieldsRequired: Content-Type

See Section 6.3.1.3

12.2.3.4 PayloadThe request payload specifies changes to a single Work Item. It shall be single part and shall contain only attributes whose values are to be modified. Any binary data contained in the payload shall be inline. The changes shall comply with all requirements described in PS3.4 Section CC.2.6.2.

12.2.3.5 BehaviorThe origin server shall modify the Work Item as specified in the request, and in a manner consistent with the SCP behavior specified in PS3.4 Section CC.2.6.3.

12.2.3.6 Responseversion∎status-code∎reason-phrase↲*header-field↲↲

12.2.3.7 Status CodesIf the Update request is successful the response will contain a status code of 200 (OK).

If the request fails the response will contain an appropriate status code from table X.Y-A.

12.2.3.8 Header FieldsIf the Work Item was updated but with modifications made by the origin server, the response shall include the following in the Warning header field:

Warning: 299 {+service}: The Work Item was updated with modifications.

If optional attributes were rejected, the response shall include the following Warning header field:

3700

3705

3710

3715

3720

3725

3730

3735

Warning: 299 {+service}: Requested optional attributes are not supported.

If the request was rejected with a 409 status code, the response shall include a Warning header field with one of following messages that best in describes the nature of the conflict:

Warning: 299 {+service}: The Transaction UID is missing.

Warning: 299 {+service}: The Transaction UID is incorrect.

Warning: 299 {+service}: The submitted request is inconsistent with the current state of the Work Item.

12.2.3.9 PayloadThe response payload is empty.

12.2.4 Change Work Item State TransactionThis transaction changes the state of an existing Work Item.

[explain the legal state transitions]

12.2.4.1 RequestThe request shall have the following format:

PUT∎/workitems/{workItemUID}/state∎version↲Content-Type: {media-type}↲*header-field↲↲

Where,

{workItemUID}workItemUID is the UID of a Work Item.

12.2.4.2 Header FieldsRequired: Content-Type

See Section 6.3.1.3

12.2.4.3 PayloadThe request has a single part payload that describes a state change to the target Work Item. It shall include all attributes required for an SCU in PS3.4 Table CC.2.1-1.

12.2.4.4 BehaviorThe origin server shall modify the target Work Item’s state as specified in the request. It shall do so as described by the SCP behavior in PS3.4 Section CC.2.1.3.

12.2.4.5 ResponseThe response shall have the following format:

version∎status-code∎reason-phrase↲*header-field↲↲

12.2.4.6 Status CodesA success response will contain a status code of 200 (OK).

3740

3745

3750

3755

3760

3765

3770

A failure response will contain an appropriate status code from Table .

12.2.4.7 Header FieldsIf the user agent specifies a Procedure Step State (0074,1000) attribute with a value of "CANCELED" and the Work Item is already in that state, the response message shall include the following Warning header field:

Warning: 299 {+service}: The Work Item is already in the requested state of CANCELED.

If the user agent specifies a Procedure Step State (0074,1000) attribute with a value of "COMPLETED" and the Work Item is already in that state, the response message shall include the following Warning header field:

Warning: 299 {+service}: The UPS is already in the requested state of COMPLETED.

If the request was rejected with a 409 status code, the response shall include a Warning header field with one of following messages that best in describes the nature of the conflict:

Warning: 299 {+service}: The Transaction UID is missing.

Warning: 299 {+service}: The Transaction UID is incorrect.

Warning: 299 {+service}: The submitted request is inconsistent with the current state of the Work Item.

12.2.4.8 PayloadThe response payload is empty.

12.2.4.9 Media TypesAn origin server shall support all media-types allowed in the request.

The media types supported by this transaction are:

application/dicom+xml”application/json

12.2.5 Request Cancellation This transaction requests that a Work Item be cancelled, that is, that the origin server change its state to ‘cancelled’.

[explain the legal state transitions]

12.2.5.1 RequestPOST∎/workitems/{workItemUID}/cancelrequest∎version↲Content-Type: {media-type}↲*header-field↲↲

Where,

{workItemUID}workItemUID is the UID of a Work Item.

12.2.5.2 Header FieldsRequired: Content-Type

See Section 6.3.1.3

3775

3780

3785

3790

3795

3800

3805

12.2.5.3 PayloadThe request has a single part payload that describes a request to cancel the target Work Item. It shall include all attributes required for an SCU in PS3.4 Table CC.2.1-1.

The payload may include a Reason for Cancellation and/or a proposed Procedure Step Discontinuation Reason Code Sequence. It may also include a Contact Display Name and/or a Contact URI for the person with whom the cancel request may be discussed.

12.2.5.4 BehaviorThe origin server shall change the state of the target Work Item to CANCELED as shown in Figure CC.1.1-1 in PS3.4. The origin server shall process the request as described by the SCP behavior in Section CC.2.2.3 in PS3.4.

To cancel an IN PROGRESS Work Item that the user agent is itself performing, the user agent shall instead use the Change Work Item State transaction as described in Section 12.2.4.

The origin server shall modify the target Work Item’s state as specified in the request. It shall do so as described by the SCP behavior in PS3.4 Section CC.2.1.3.

12.2.5.5 Response{version}version ∎{status-code}status-code ∎{reason-phrase}reason-phrase↲*{header-field↲}header-field↲↲

12.2.5.6 Status CodesA success response will contain a status code of 202 (Accepted). A success Status Code means that the Request was accepted, not that the Work Item has been canceled. The system performing the Work Item is not obliged to honor the request to cancel and in some scenarios, may not even receive notification of the request. See Section CC.2.4 in PS3.4.

A failure response will contain an appropriate status code from Table .

12.2.5.7 Header FieldsIf the Work Item is already in a canceled state, the response message shall include the following Warning header field:

Warning: 299 {+service}: The UPS is already in the requested state of CANCELED.

12.2.5.8 PayloadThe response payload is empty.

12.2.5.9 Media TypesAn origin server shall support all media-types allowed in the request.

The media types supported by this transaction are:

application/dicom+xmlapplication/json

12.2.6 Search for Work Items TransactionThis transaction returns a list of Work Items that match specified query parameters. Each Work Item in the returned list includes the any return attributes specified in the request,

3810

3815

3820

3825

3830

3835

3840

12.2.6.1 RequestThe request has the following format:

GET∎/workitems{?query} ∎{version}version ↲Accept: {media-type}↲Cache-Control: no-cache↲*{header-field↲}header-field↲↲

12.2.6.2 Query ParametersThe query parameters have the following format:

query = *{attribute / include / fuzzy / offset / limitattribute = attributeIDattribute = valueattributeIDattribute an attribute keyword or tag from the UPS IOD. See PS3.3 Section B.26.2.value a valid value for the attribute as defined in PS3.6.include = “include=” #attributeIDattribute / “all”“all” indicates that all attributes with values should be included for each response.fuzzy = “fuzzymatchingfuzzy_matching=” (true / false)limit = maximumResultsoffset = skippedResultsmaximumResults = positive integerskippedResults = positive-integer

12.2.6.3 Header FieldsRequired: Accept

Recommended: Cache-control: no-cache

If included, specifies that search results returned should be current and not cached.

See Section 6.3.1.3.

12.2.6.4 PayloadThe request payload is empty.

12.2.6.5 BehaviorThe Origin-Serverorigin server shall perform a search according the requirements for the RS Storage Service Search transaction. See Section 10.7.3.

An Origin-Serverorigin server shall support matching against all Unified Procedure Step Instance Attributes in Table CC.2.5-3 in PS3.4 with a Match Key Type value of U, R or *.

See Section 10.7.3.1 for matching behavior.

For each matching Work Item, the Origin-Serverorigin server shall return:

All Unified Procedure Step Instance Attributes in Table CC.2.5-3 in PS3.4 with a Return Key value of 1 and 2. All Unified Procedure Step Instance Attributes in Table CC.2.5-3 in PS3.4 with a Return Key value of 1C for

which the conditional requirements are met. All other Unified Procedure Step Instance Attributes passed as {attributeIDattribute} query keys that are

supported by the Origin-Serverorigin server as matching or return attributes

3845

3850

3855

3860

3865

3870

3875

3880

All other Unified Procedure Step Instance Attributes passed as "include" query values that are supported by the Origin-Serverorigin server as return attributes.

12.2.6.6 ResponseThe response shall have the following format:

{version}version ∎{status-code}status-code ∎{reason-phrase}reason-phrase↲Content-Type: {media-type}↲*{header-field↲}header-field↲↲[payload]

12.2.6.7 Status CodesA success response will contain a status code of 200 (OK).

A failure response will contain an appropriate status code from table X.Y-A.

12.2.6.8 Header FieldsIf the Work Item was updated but with modifications made by the Origin-Serverorigin server, the response shall include the following in the Warning header field:

• Warning: 299 {+svc}{+service}: The Work Item was updated with modifications.

If optional attributes were rejected, the response shall include the following Warning header field:

• Warning: 299 {+svc}{+service}: Requested optional attributes are not supported.

If the request was rejected with a 409 status code, the response shall include a Warning header field with one of following messages that best in describes the nature of the conflict:

• Warning: 299 {+svc}{+service}: The Transaction UID is missing.

• Warning: 299 {+svc}{+service}: The Transaction UID is incorrect.

• Warning: 299 {+svc}{+service}: The submitted request is inconsistent with the current state of the UPS Instance.

12.2.6.9 PayloadThe response payload contains the search results in one of the media types specified by the request Accept header field. If there are no matching results the payload will be empty.

12.2.6.10 Media TypesAn Origin-Serverorigin server shall support all media-types allowed in the request.

The media types supported by this transaction are:

multipart/related; type=”application/dicom+xml”; boundary={boundary}

Specifies that the payload is a multipart message body where each part is a DICOM PS3.19 XML Dicom Native Model element containing the attributes for one matching Work Item. See PS3.19 Section A.1.

application/json

Specifies that the payload is a JSON array containing one property for each matching Work Item, which in turn contains sub-properties describing the matching attributes for that Work Item. See Section F.2.

3885

3890

3895

3900

3905

3910

3915

12.3 SubscriptionsEach Work Item can have a list a User-Agentuser agents who are subscribers, that is, they request that they be notified of events associated with the Work Item.

The Worklist Service also has a list of User-Agentuser agents who are subscribers. These subscribers receive notification of any event associated with any Work Item. Subscribers to the Worklist can either receive all notifications or they can supply a filter, in which case they will only receive notifications for Work Items that pass the filter.

Upon receipt of the Create Subscription, Suspend Global Subscription or Delete Subscription request, the Origin-Serverorigin server shall attempt to update the appropriate subscription state Global Subscription State, Filtered Global Subscription and/or Work Item Subscription State of the specified Application Entity with respect to the specified SOP Instance UID as described in Table CC.2.3-2 in PS3.4 and then return an appropriate response.

12.3.1 Deletion Locks

12.3.2 Filters

12.3.3 ResourcesA User-Agentuser agent can subscribe to the three types of resources in the following table:

Table 12.2-1: Subscription ResourcesName Resource DescriptionSubscription Work Item Receive event notifications for a single Work Item.Global Subscription Worklist Receive event notifications for all Work Items in the Worklist.Filtered Subscription Filtered Worklist Receive event notifications for any Work Item in the Worklist that passes

a specified subscription filter.

12.3.4 Create Subscription TransactionThis transaction records subscribers to whom future events associated with the specified Work Items will be reported.

12.3.4.1 RequestThe request shall be formatted as follows:

POST∎/workitems/{resource}∎{version}version ↲Content-Length: 0↲*{header-field↲}header-field↲↲

Where,

{resource} is one of:

{workItemUID}/subscribers/{aetitle}{?deletionlock}1.2.840.10008.5.1.4.34.5/subscribers/{aetitle}{?deletionlock}1.2.840.10008.5.1.4.34.5.1/subscribers/{aetitle}?{filter*}{?deletionlock}

1.2.840.10008.5.1.4.34.5/subscribers/{aetitle}{?deletionlock}{&filter}

3920

3925

3930

3935

3940

3945

3950

And

{aetitle} = 16{token}

is an Application Entity Title that conforms to the “AE” Value Representation and identifies the Application Entity to be subscribed. See PS3.5 Table 6.2-1.

{deletionlock} = true / false

If present, shall have a value of ‘true’ or ‘false’, indicating whether or not the User-Agentuser agent is requesting a Deletion Lock.

{filter} = *{attributeIDattribute}={value}

If present, specifies the key/value pairs describing the filter parameters. Each {attributeIDattribute} shall refer to an attribute of the Unified Procedure Step IOD (see PS3.3, Section B.26.2). See Section 6.7.1.1 for {attributeIDattribute} and {value} encoding rules.

**** This could be simplified to ****

The request shall be formatted as follows:

POST∎/workitems{/workItemUID}{?filter}{&deletionlock}∎{version}version ↲Content-Length: 0↲*{header-field↲}header-field↲↲

Where,

{/workItemUID} = {uid}

Specifies an optional Work Item, if it is not present then the subscription will be global, that is, to all present and future items in the Worklist.

{filter} = *{attributeIDattribute}={value}

If present, specifies the key/value pairs describing the filter parameters. Each {attributeIDattribute} shall refer to an attribute of the Unified Procedure Step IOD (see PS3.3, Section B.26.2). See Section 6.7.1.1 for {attributeIDattribute} and {value} encoding rules.

{deletionlock} = true / false

If present, shall have a value of ‘true’ or ‘false’, indicating whether or not the User-Agentuser agent is requesting a Deletion Lock.

**** end of simplification ****

12.3.4.2 Header FieldsRequired: Content-Length: 0

See Section 6.3.1.3

12.3.4.3 PayloadThe request payload shall be empty.

12.3.4.4 BehaviorThe Origin-Serverorigin server shall create a subscription to the target resource for the User-Agentuser agent.

3955

3965

3970

3975

3980

3985

3990

The Origin-Serverorigin server shall support the management of subscriptions as specified by the SCP behavior in PS3.4, Section CC.2.3.3.

Upon receipt of the Create Subscription, Suspend Global Subscription or Delete Subscription request, the Origin-Serverorigin server shall attempt to update the Global Subscription State, Filtered Global Subscription and/or Work Item Subscription State of the specified Application Entity with respect to the specified SOP Instance UID as described in PS3.4, Table CC.2.3-2 and then return the appropriate response.

12.3.4.5 ResponseThe response shall have the following format:

{version}version ∎{status-code}status-code ∎{reason-phrase}reason-phrase↲Location: {+web-socket}↲Content-Length: 0↲{*header-field↲}↲[payload]

Where,

{+web-socket} is the base URL for the WebSocket service. This shall include the WebSocket protocol (either WS or WSS) and may include a combination of authority and path.

12.3.4.6 Status CodesA success response shall contain a status code of 201 (Created).

A failure response shall contain a status code from Table .

12.3.4.7 Header FieldsRequired: Location

Required if the Create Subscription request was accepted but the Deletion Lock was not, the response shall include the following Warning header field:

Warning: 299 {+svc}{+service}: Deletion Lock not granted.

Required if the request was rejected with a status code of 403, because Filtered Global Subscriptions are not supported, the response message shall include the following Warning header field:

Warning: 299 {+SERVICE}: The Origin-Serverorigin server does not support Global Subscription Filtering.

12.3.4.8 PayloadThe response payload is empty.

12.3.4.9 Media TypesAn Origin-Serverorigin server shall support all media-types allowed in the request.

The media types supported by this transaction are:

application/dicom+xml”application/json

3995

4000

4005

4010

4015

4020

4025

12.3.5 Delete SubscriptionIf the target resource is a Work Item the User-Agentuser agent’s subscription to that Work Item is removed. The “suspend” query parameter is ignored when the target resource is a Work Item.

If the target resource is the Worklist and the “suspend” query parameter is “true” then all future subscriptions to Work Items are cancelled. If the “suspend” query parameter is either “false” or not present, the all current and future subscriptions are cancelled.

12.3.5.1 RequestThe request shall be formatted as follows:

DELETE∎/workitems/{resource}/subscribers/{aetitle}{?suspend}∎version↲Content-Length: 0↲*header-field↲↲

Where,

resource = {workItemUID} / 1.2.840.10008.5.1.4.34.5 / 1.2.840.10008.5.1.4.34.5.1

aetitle = 16{token}

The subscribed Application Entity

?suspend = true / false

If present, indicates that the subscription should be suspended, i.e. current subscriptions should not be deleted, but no future subscriptions should be created.

**** This could be simplified to ****

DELETE∎/workitems{/workItemUID}{?suspend}∎version↲Content-Length: 0↲*header-field↲↲

Where,

{?suspend} = true / false

If present, indicates that the subscription should be suspended, i.e. current subscriptions should not be deleted, but no future subscriptions should be created.

**** end of simplification ****

12.3.5.2 Header FieldsRequired: Content-Length: 0

12.3.5.3 PayloadThe request payload shall be empty.

12.3.5.4 BehaviorIf the “suspend” query parameter is “true” the origin server shall no longer automatically subscribe the user agent to newly-created Work Items; however, this does not delete existing subscriptions to Work Items. If the “suspend” query

4030

4035

4040

4045

4050

4055

4060

4065

parameter is “false” or not present the origin server shall remove any of the user agent’s existing subscriptions to the target resource.

The origin server shall conform to the behavior described in Section 12.1.8.4, “Behavior”.

12.3.5.5 ResponseThe response shall have the following format:

version∎status-code∎reason-phrase↲Content-Length: 0↲*header-field↲↲

12.3.5.6 Status CodesA success response shall contain a status code of 200 (OK), indicating that the target subscription(s) have been suspended or deleted.

A failure response will contain an appropriate status code from Table 12.2-A.

12.3.5.7 Header FieldsRequired: Content-Length: 0

12.3.5.8 PayloadThe response payload shall be empty.

12.3.5.9 Media TypesThis transactions shall specify no media types in the request or response.

12.3.6 Open Event Channel TransactionThis transaction opens a WebSocket channel that will be used to send Event Reports to the client. The WebSocket connection can use the same TCP port as the HTTP connection, but they are separate connections.

See RFC-6455 for details of the WebSocket protocol.

12.3.6.1 RequestThe request shall have the following format:

GET∎/subscribers/{aetitle}∎version↲*header-field↲↲

Where,

/ is the base URL for the WebSocket Worklist Service. This shall include the WebSocket protocol (either WS or WSS) and may include a combination of authority and path.

aetitle identifies the subscribed Application Entity.

**** This could be simplified to: ****

GET∎/∎version↲Host: server.example.com↲

4070

4075

4080

4085

4090

4095

4100

Upgrade: websocket↲Connection: Upgrade↲Sec-WebSocket-Key: {key}↲Sec-WebSocket-Protocol: {protocols}↲Sec-WebSocket-Version: {ws-version}↲*header-field↲↲

Where,

/The base URL for the Worklist Service. This shall include the WebSocket scheme (either WS or WSS).

**** End of simplification ****

12.3.6.2 Header FieldsRequired: Upgrade: websocket

Connection: Upgrade

Sec-WebSocket-Key

Sec-WebSocket-Protocol

Sec-WebSocket-Version

12.3.6.3 PayloadThe request payload shall be empty.

12.3.6.4 BehaviorThe origin server upgrades the HTTP connection to a WebSocket connection and records the association between the user agent and the WebSocket. In the future the origin server will use this WebSocket connection to send Event Reports for any Work Items that have subscriptions from the user agent.

The origin server opens and maintains the active WebSocket connection to the user agent and uses it to send Event Report messages for Work Items that have subscriptions from the user agent. See Section 6.9.7.2, “Behavior”).

The connection shall remain open and may be used by the server to send Event messages (see Section 6.9.11, “SendEventReport”).

If the WebSocket connection is lost at any point the user agent can re-establish it by repeating the request.

The state of a WebSocket connection does not affect subscriptions and an origin server is not required to queue messages when the connection is down.

Note

A user agent will only receive the initial state of a newly-subscribed Work Item if the WebSocket connection was initiated prior to creating the subscription.

12.3.6.5 ResponseThe response shall have the following format:

version∎status-code∎reason-phrase↲Upgrade: websocket↲Connection: Upgrade↲Sec-WebSocket-Accept: response-key↲

4105

4110

4115

4120

4125

4130

4135

4140

Sec-WebSocket-Protocol: protocol↲*header-field↲↲Where,

12.3.6.6 Status CodesA success response will contain a status code of 101 (Switching Protocols), which indicates that the origin server has opened the connection.

A failure response will contain an appropriate status code from Table .

12.3.6.7 Header FieldsRequired:

Upgrade: websocketConnection: UpgradeSec-WebSocket-AcceptSec-WebSocket-Protocol

12.3.6.8 PayloadThe response payload shall be empty.

12.3.6.9 Media TypesThis transaction shall specify no media types in the request or response.

12.3.7 Send Event ReportThis transaction sends Event Reports from the origin server to a user agent over an established WebSocket connection.

12.3.7.1 RequestThe request will use the WebSocket Data Frame transmission protocol.

12.3.7.2 PayloadThe Event Report shall contain all mandatory attributes described in Table CC.2.4-1 in PS3.4 and Table 10.3-1 in PS3.7 for the event type.

Events Reports are encoded as WebSocket data frames with an opcode of "%x1" (text).

The frame payload data shall be a DICOM JSON dataset containing the attributes of the Event Report.

Note

1. Example WebSocket payload:

{"00000002": [ "1.2.840.10008.5.1.4.34.6.4" ],"00000100": [ 256 ],"00000110": [ 23 ],"00001000": [ "1.2.840.10008.5.1.4.34.6.4.2.3.44.22231" ],

4145

4150

4155

4160

4165

4170

4175

4180

"00001001": [ 1 ],"00741238": [ "SCHEDULED" ],"00744041": [ "READY" ]}↲

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

12.3.7.3 BehaviorPS3.4, Section CC.2.4.3 describes the scenarios in which an origin server sends Event Reports to a subscriber, as well as the content of the Event Report messages.

12.3.7.4 ResponseThere is no response.

[Annex A] ParametersDICOM Media Types Closed Issues

# Issues

Open Issues

# IssuesShould each Media Type have its own annex or should they all be in one AnnexShould the examples be part of the media type definitionShould the media type include the IANA Registration information

A.1 application/dicom

4185

4190

4195

4200

A.1 application/dicom+json, application/json

12.3.7.5 JSON Search ResultsContent-Type: application/json

The payload is a JSON array containing a DICOM JSON object for each matching study, series or instance containing sub-objects describing the matching attributes for each study, series or instance (see Section F.2).

The origin server may use a bulkdata reference [ref] at its discretion (see Section F.2.6). For example, this might be done to avoid encoding a large DICOM Value Field, such as an image thumbnail.

If there are no matching results, the payload will be empty.

A.1.1 application/dicom+xml

12.3.7.6 XML Search ResultsContent-Type: multipart/related; type=application/dicom+xml

The response is a multipart payload, where each part is a DICOM PS3.19 XML Native Dicom Model element containing the attributes for one matching Study, Series or Instance (see Section A.1 in PS3.19).

The origin server may use a bulkdata reference [ref] at its discretion (see Table A.1.5-2 in PS3.19 and Section 6.5.6). For example, this might be done to avoid encoding a large DICOM Value Field, such as an image thumbnail.

If there are no matching results, the payload will be empty.

Each item in the multipart payload will contain the following HTTP/1.1 headers:

Content-Type: application/dicom+xml

12.3.8 XML Status Details Document

12.3.8.1 Status Details ExampleThe following is an example of a PS3.18 XML Store Instances Response Module in the response message body containing 2 failed SOP Instances, 1 successful SOP Instance, and 1 accepted SOP Instance with a warning:

<?xml version="1.0" encoding="utf-8"?><NativeDicomModel xmlns="http://dicom.nema.org/PS3.19/models/NativeDICOM"xsi:schemaLocation="http://dicom.nema.org/PS3.19/models/NativeDICOM"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <DicomAttribute tag="00081198" vr="SQ" keyword="FailedSOPSequence"> <Item number="1"> <DicomAttribute tag="00081150" vr="UI" keyword="ReferencedSOPClassUID"> <Value number="1">1.2.840.10008.3.1.2.3.1</Value> </DicomAttribute> <DicomAttribute tag="00081155" vr="UI" keyword="ReferencedSOPInstanceUID"> <Value number="1"> 2.16.124.113543.6003.1011758472.49886.19426.2085542308</Value> </DicomAttribute> <DicomAttribute tag="00081197" vr="US" keyword="FailureReason">

4205

4210

4215

4220

4225

4230

4235

4240

<Value number="1">290</Value> </DicomAttribute> </Item> <Item number="2"> <DicomAttribute tag="00081150" vr="UI" keyword="ReferencedSOPClassUID"> <Value number="1">1.2.840.10008.3.1.2.3.1</Value> </DicomAttribute> <DicomAttribute tag="00081155" vr="UI" keyword="ReferencedSOPInstanceUID"> <Value number="1"> 2.16.124.113543.6003.1011758472.49886.19426.2085542309</Value> </DicomAttribute> <DicomAttribute tag="00081197" vr="US" keyword="FailureReason"> <Value number="1">290</Value> </DicomAttribute> </Item> </DicomAttribute> <DicomAttribute tag="00081199" vr="SQ" keyword="ReferencedSOPSequence"> <Item number="1"> <DicomAttribute tag="00081150" vr="UI" keyword="ReferencedSOPClassUID"> <Value number="1">1.2.840.10008.5.1.4.1.1.2</Value> </DicomAttribute> <DicomAttribute tag="00081155" vr="UI" keyword="ReferencedSOPInstanceUID"> <Value number="1"> 2.16.124.113543.6003.189642796.63084.16748.2599092903</Value> </DicomAttribute> <DicomAttribute tag="00081190" vr="UR" keyword="RetrieveURL"> <Value number="1"> https://wadors.hospital.com/studies/2.16.124.113543.6003.1154777499.30246.19789.3503430045/ series/2.16.124.113543.6003.2588828330.45298.17418.2723805630/ instances/2.16.124.113543.6003.189642796.63084.16748.2599092903</Value> </DicomAttribute> </Item> <Item number="2"> <DicomAttribute tag="00081150" vr="UI" keyword="ReferencedSOPClassUID"> <Value number="1">1.2.840.10008.5.1.4.1.1.2</Value> </DicomAttribute> <DicomAttribute tag="00081155" vr="UI" keyword="ReferencedSOPInstanceUID"> <Value number="1"> 2.16.124.113543.6003.189642796.63084.16748.2599092905</Value> </DicomAttribute> <DicomAttribute tag="00081196" vr="US" keyword="WarningReason"> <Value number="1">45056</Value> </DicomAttribute> <DicomAttribute tag="00081190" vr="UR" keyword="RetrieveURL"> <Value number="1"> https://wadors.hospital.com/studies/2.16.124.113543.6003.1154777499.30246.19789.3503430045/ series/2.16.124.113543.6003.2588828330.45298.17418.2723805630/ instances/2.16.124.113543.6003.189642796.63084.16748.2599092905</Value> </DicomAttribute> </Item> </DicomAttribute> <DicomAttribute tag="00081190" vr="UR" keyword="RetrieveURL"> <Value number="1"> https://wadors.hospital.com/studies/2.16.124.113543.6003.1154777499.30246.19789.3503430045</Value>

4245

4250

4255

4260

4265

4270

4275

4280

4285

4290

4295

4300

</DicomAttribute></NativeDicomModel>

Annex B Rendered Media Types

Annex C Other Media Types[C.1] WADL Docuiment Format - application/vnd.sun.wadl+xmlThe Capabilities Description document shall contain one top-level "application" element, which shall contain one "resources" element whose "base" attribute value is “/”, which is the base URL for the Service.

The full WADL resource tree follows directly and unambiguously from the RESTful resource endpoints defined in 6.5, 6.6, 6.7 and 6.9.

For informative purposes, the full resource tree and the methods defined for each resource are described in Table 9.8-X.

WADL Media Type Registration

Application/ vnd.sun.wadl+xml; chaset

C.1.1 IANA Registration(last updated 07 March 2006)

Name: Marc Hadley

Email: marc.hadley&sun.com

MIME media type name: Application

MIME subtype name: Vendor Tree - vnd.sun.wadl+xml

Required parameters: None

Optional parameters:

charset:This parameter has identical semantics to the charset parameter of the "application/xml" media type as specified in RFC 3023 [http://www.ietf.org/rfc/rfc3023.txt].

Encoding considerations: 8bit

This media type may require encoding on transports not capable of handling 8 bit text.

Security considerations:

The media type does not contain active or executable content. The other security issues associates with this type have not been assessed.

Interoperability considerations:

This media type is designed to be interoperable across a wide range of platforms and devices with different capabilities. The format does not provide any functionality that could be considered as platform or device specific.

Published specification: http://weblogs.java.net/blog/mhadley/wadl.pdf

4310

4315

4320

4325

4330

4335

Applications which use this media :None yet released.

Additional information:

1. Magic number(s): none2. File extension(s): .wadl3. Macintosh file type code: none4. Object Identifiers: none

Person to contact for further information:1. Name: Marc Hadley2. Email: marc.hadley&sun.com

Intended usage: Common

Author/Change controller: marc.hadley&sun.com

(file created 07 March 2006)

C.1.2 DefinitionGeneral Format:

Table 9.8-XResources and MethodsResource Methods supported (excluding Retrieve Capabilities) Reference

/ N/A N/A

studies SearchForStudiesStoreInstances

6.8.1.2.2.36.8.1.2.2.2

{StudyUID} RetrieveStudyStoreStudyInstances

6.8.1.2.2.16.8.1.2.2.3

metadata RetrieveStudyMetadata 6.8.1.2.2.1

series SearchForStudySeries 6.8.1.2.2.3

{SeriesInstanceUID} RetrieveSeries 6.8.1.2.2.1

metadata RetrieveSeriesMetadata 6.8.1.2.2.1

instances SearchForStudySeriesInstances 6.8.1.2.2.3

{SOPInstanceUID} RetrieveInstance 6.8.1.2.2.1

metadata RetrieveInstanceMetadata 6.8.1.2.2.1

frames N/A N/A

{framelist} RetrieveFrames 6.8.1.2.2.1

instances SearchForStudyInstances 6.8.1.2.2.3

series SearchForSeries 6.8.1.2.2.3

{SeriesInstanceUID} N/A N/A

{instances} SearchForInstances 6.8.1.2.2.3

instances SearchForInstances 6.8.1.2.2.3

{BulkDataURL} RetrieveBulkData 6.8.1.2.2.1

workitems SearchForUPSCreateUPS

6.8.1.2.2.36.8.1.2.2.2

4340

4345

4350

Resource Methods supported (excluding Retrieve Capabilities) Reference

{UPSInstanceUID} RetrieveUPSUpdateUPS

6.8.1.2.2.16.8.1.2.2.4

state ChangeUPSState 6.8.1.2.2.4

cancelrequest RequestUPSCancel 6.8.1.2.2.4

subscribers N/A N/A

{AETitle} CreateSubscriptionDeleteSubscription

6.8.1.2.2.56.8.1.2.2.5

1.2.840.10008.5.1.4.34.5 N/A N/A

subscribers N/A N/A

{AETitle} CreateSubscriptionDeleteSubscription

6.8.1.2.2.56.8.1.2.2.5

suspend SuspendGlobalSubscription 6.8.1.2.2.5

1.2.840.10008.5.1.4.34.5.1 N/A N/A

subscribers N/A N/A

{AETitle} CreateSubscriptionDeleteSubscription

6.8.1.2.2.56.8.1.2.2.5

suspend SuspendGlobalSubscription 6.8.1.2.2.5

12.3.8.2 Methods

12.3.8.2.1 Retrieve MethodsThe Retrieve methods define the capabilities of one of the following resources:

A WADO-RS resource (see 6.5) or A Retrieve UPS resource (see 6.9.4).

The Retrieve methods shall contain the following attributes:

A "name" attribute with a value of "GET" An "id" attribute with a value of "RetrieveStudy", "RetrieveSeries", "RetrieveInstance", "RetrieveBulkData",

"RetrieveFrames", "RetrieveStudyMetadata", "RetrieveSeriesMetadata", "RetrieveInstanceMetadata" or "RetrieveUPS"

The Retrieve methods shall contain a "request" element with "param" elements documenting the following:

supported Accept header valueso if the same Media Type is supported with multiple Transfer Syntaxes there should be one entry for each

combination of Media Type and Transfer Syntax

The Retrieve methods shall contain one or more "response" elements documenting the following:

supported Status Codes Media Types returned for each Status Code (if applicable)

o if the same Media Type is supported with multiple Transfer Syntaxes there should be one entry for each combination of Media Type and Transfer Syntax

Note

More than one Status Code can be described by a single "response" element.

4355

4360

4365

4370

Example:

<method name="GET" id="RetrieveStudies"> <request> <param name="Accept" style="header" default="multipart/related; type=application/dicom"> <option value="multipart/related; type=application/dicom" /> <option value="multipart/related; type=application/dicom"; transfer-syntax=1.2.840.10008.1.2 /> <option value="multipart/related; type=application/dicom"; transfer-syntax=1.2.840.10008.1.2.1 /> <option value="multipart/related; type=application/octet-stream" /> <option value="multipart/related; type=image/dicom+jpx" /> <option value="multipart/related; type=image/dicom+jpx; transfer-syntax=1.2.840.10008.1.2.4.92" /> <option value="multipart/related; type= video/mpeg; transfer-syntax=1.2.840.10008.1.2.4.100" /> </param> </request> <response status="200,206"> <representation mediaType="multipart/related; type=application/dicom"; transfer-syntax=1.2.840.10008.1.2 /> <representation mediaType="multipart/related; type=application/dicom"; transfer-syntax=1.2.840.10008.1.2.1 /> <representation mediaType="multipart/related; type=application/octet-stream" /> <representation mediaType="multipart/related; type= image/dicom+jpx" /> <representation mediaType="multipart/related; type= image/dicom+jpx; transfer-syntax=1.2.840.10008.1.2.4.92" /> <representation mediaType="multipart/related; type= video/mpeg; transfer-syntax=1.2.840.10008.1.2.4.100" /> </response> <response status="400 404 406 410 503" /></method>

12.3.8.2.2 Store Methods

The Store methods define the capabilities of a Store resource (see 6.6) or a CreateUPS resource (see 6.9.1).

The Store methods shall contain the following attributes:

A "name" attribute with a value of "POST" An "id" attribute with a value of "StoreInstances", "StoreStudyInstances" or "CreateUPS"

The Store methods shall contain a "request" element with "param" elements documenting the following:

supported Accept header values supported Representations

if the same Media Type is supported with multiple Transfer Syntaxes there should be one entry for each combination of Media Type and Transfer Syntax

The Store methods shall contain one or more "response" elements documenting the following:

supported Status Codes Media Types returned for each Status Code (if applicable) Headers returned for each Status Code

Note

More than one Status Code can be described by a single "response" element.

Example:

4375

4380

4385

4390

4395

4400

4410

4415

4420

<method name="GET" id="StoreInstances"> <request> <param name="Accept" style="header" default="application/dicom+xml"> <option value="application/dicom+xml" /> </param> <representation mediaType="multipart/related; type=application/dicom" /> <representation mediaType="multipart/related; type=application/dicom; transfer-syntax=1.2.840.10008.1.2" /> <representation mediaType="multipart/related; type=application/dicom; transfer-syntax=1.2.840.10008.1.2.1" /> <representation mediaType="multipart/related; type=application/dicom+xml" /> <representation mediaType="multipart/related; type=application/dicom+xml; transfer-syntax=1.2.840.10008.1.2" /> <representation mediaType="multipart/related; type=application/dicom+xml; transfer-syntax=1.2.840.10008.1.2.1" /> <representation mediaType="multipart/related; type=application/dicom+xml; transfer-syntax=1.2.840.10008.1.2.4.92" /> <representation mediaType="multipart/related; type=application/dicom+xml; transfer-syntax=1.2.840.10008.1.2.4.100" /> </request> <response status="200" /> <response status="202,409"> <representation mediaType="application/dicom+xml" /> </response> <response status="400,401,403,503" /></method>

12.3.8.2.3 Search Methods

The Search methods define the capabilities of a Search Transaction (see 6.7) or a SearchForUPS resource (see 6.9.3).

The Search methods shall contain the following attributes:

A "name" attribute with a value of "GET" An "id" attribute with a value of "SearchForStudies", "SearchForStudySeries", "SearchForSeries",

"SearchForStudySeriesInstances", "SearchForStudyInstances", "SearchForSeriesInstances", "SearchForInstances" or "SearchForUPS"

The Search methods shall contain a "request" element with "param" elements documenting the following:

supported Accept header values support for the Cache-control header support of "limit", "offset" and "fuzzymatchingfuzzy_matching" query parameters supported search parameters (both tag and keyword variants shall be listed) supported options for the "includefield" parameter (both tag and keyword variants shall be listed)

The Search methods shall contain one or more "response" elements documenting the following:

supported Status Codes returned "header" parameters, including use of "warning headers" Media Types returned for each Status Code (if applicable)

Note

More than one Status Code can be described by a single "response" element.

Example:

4425

4430

4435

4440

4445

4455

4460

4465

4470

<method name="GET" id="SearchForStudies"> <request> <param name="Accept" style="header" default="multipart/related; type=application/dicom+xml"> <option value="multipart/related; type=application/dicom+xml" /> <option value="application/json" /> </param> <param name="Cache-control" style="header"> <option value="no-cache" /> </param> <param name="limit" style="query" /> <param name="offset" style="query" /> <param name="fuzzymatchingfuzzy_matching" style="query" /> <param name="StudyDate" style="query" /> <param name="00080020" style="query" /> <param name="StudyTime" style="query" /> <param name="00080030" style="query" /> … <param name="includefield" style="query" repeating="true" /> <option value="all" /> <option value="00081049" /> <option value="PhysiciansOfRecordIdentificationSequence" /> <option value="00081060" /> <option value="NameOfPhysiciansReadingStudy" /> … </param></request><response status="200"> <representation mediaType="multipart/related; type=application/dicom+xml" /> <representation mediaType="application/json" /></response><response status="400 401 403 413 503" /></method>

12.3.8.2.4 Update Methods

The Update methods define the capabilities of an UpdateUPS, a ChangeUPSState or a RequestUPSCancellation resource (see 6.9.2).

The Update methods shall contain the following attributes:

A "name" attribute with a value of "POST" for UpdateUPS and RequestUPSCancel A "name" attribute with a value of "PUT" for ChangeUPSState An "id" attribute with a value of "UpdateUPS", "ChangeUPSState" or "RequestUPSCancellation"

The Update methods shall contain a "request" element with "param" elements documenting the following:

supported Representations

The Update methods shall contain one or more "response" elements documenting the following:

supported Status Codes Headers returned for each Status Code

Note

More than one Status Code can be described by a single "response" element.

Example:

4475

4480

4485

4490

4495

4500

4510

4515

4520

<method name="POST" id="UpdateUPS"> <request> <representation mediaType="application/dicom+xml" /> <representation mediaType="application/json" /> </request> <response status="200"> <param name="Warning" style="header" fixed="299 {+svc}: The UPS was created with modifications." /> <param name="Warning" style="header" fixed="299 {+svc}: Requested optional Attributes are not supported." /> </response> <response status="409"> <param name="Warning" style="header" fixed="299 {+svc}: The Transaction UID is missing." /> <param name="Warning" style="header" fixed="299 {+svc}: The Transaction UID is incorrect." /> <param name="Warning" style="header" fixed="299 {+svc}: The submitted request is inconsistent with the current state of the UPS Instance." /> </response> <response status="400 401 403 404 503" /></method>

Where {+svc} is the base URI for the service.

12.3.8.2.5 Subscribe Methods

The Subscribe methods define the capabilities of a Create Subscription, a Suspend Global Subscription or a Delete Subscription resource (see 6.9.7, 6.9.8 and 6.9.9).

The Subscribe methods shall contain the following attributes:

A "name" attribute with a value of "POST" for CreateSubscription and SuspendGlobalSubscription A "name" attribute with a value of "DELETE" for DeleteSubscription An "id" attribute with a value of "CreateSubscription", "SuspendGlobalSubscription" or "DeleteSubscription"

The Subscribe methods shall contain a "request" element with "param" elements documenting the following:

supported Representations

The Subscribe methods shall contain one or more "response" elements documenting the following:

supported Status Codes Headers returned for each Status Code

Note

More than one Status Code can be described by a single "response" element.

Example:

<method name="POST" id="CreateSubscription"> <request> <param name="deletionlock" style="query" default="false"> <option value="true" /> <option value="false" /> </param> </request> <response status="201"> <param name="Warning" style="header" fixed="299 {+svc}: Deletion Lock not granted." /> </response> <response status="403">

4525

4530

4535

4540

4545

4550

4555

4560

4565

4570

<param name="Warning" style="header" fixed="299 {+svc}: The origin server does not support Global Subscription Filtering." /> </response> <response status="400 401 404 409 503" /></method>

Where {+svc} is the base URI for the service.

[Annex D] Query Parameter SyntaxStatus Details

The DICOMweb Status Details is a machine-readable document containing the details of an RS transaction in an HTTP response. It is modeled on the Problem Details for HTTP APIs. The document describes the results first with respect to the target resource, and then with respect to sub-resources contained in the target resource.

A Status Details document MAY have the following members:

"type" (string) - An absolute URI [RFC3986] that identifies the problem type. When dereferenced, it SHOULD provide human-readable documentation for the problem type (e.g., using HTML [W3C.REC-html401-19991224]). When this member is not present, its value is assumed to be "about:blank".

"title" (string) - A short, human-readable summary of the problem type. It SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.

"status" (number.number) - The HTTP status code ([RFC7231], Section 6) generated by the origin server for this occurrence of the problem, followed by a, possibly empty DICOM code.

"detail" (string) - An human readable explanation specific to this occurrence of the problem.

"location" (string) - An absolute URI that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.

“IOD” (string) – The Information Object Definition of the resource.

“class” (string) – SOP Class UID of the resource.

“sub-resources”: An array of Status Details documents for each sub-resource.

Below is a JSON Schema for the Status Details document:

{ type": URI,"title": String,“status”: ResourceStatus,“sub-resources”: [ ResourceStatus ],}

Where,

type: is a URI that identifies the type and structure of the document. For example, in the dicom+json media type the URL refers to a location where a JSON Schema for the document may be found.

title is the title of the status document.

status is an object describing the status of the target resource.

4575

4580

4585

4590

4595

4600

4605

4610

sub-resources an array of resource statuses.

A resource status have the following structure:

{“type”: is a string containing one of ‘Success’, ‘Warning’, or ‘Error’.“ie”: is the Information Entity type of the resource,“class”: is the resources SOP Class UID of the resource,“location”: is a URI that references the resource,“code”: a string in the form of XXX.YYY, where XXX is the HTTP Status Code for the

resource, and YYY is the DICOM status code for the resource.“detail”: a string describing the status with respect to this resource.}

[Annex E] HTTP Status Codes (Informative)Code

Reason-Phrase DICOM Defined in...

100 Continue Section 6.2.1101 Switching Protocols Section 6.2.2200 OK Success Section 6.3.1201 Created Section 6.3.2202 Accepted Section 6.3.3203 Non-Authoritative Information Proxy Section 6.3.4204 No Content Section 6.3.5205 Reset Content Section 6.3.6206 Partial Content Section 4.1 of [RFC7233] 300 Multiple Choices Section 6.4.1301 Moved Permanently Section 6.4.2302 Found Section 6.4.3303 See Other Section 6.4.4304 Not Modified Section 4.1 of [RFC7232] 305 Use Proxy Section 6.4.5307 Temporary Redirect Section 6.4.7400 Bad Request Section 6.5.1401 Unauthorized Section 3.1 of [RFC7235] 402 Payment Required Section 6.5.2403 Forbidden Section 6.5.3404 Not Found Section 6.5.4405 Method Not Allowed Section 6.5.5406 Not Acceptable Section 6.5.6407 Proxy Authentication Required Section 3.2 of [RFC7235] 408 Request Timeout Section 6.5.7409 Conflict Section 6.5.8410 Gone Section 6.5.9

4615

4620

4625

411 Length Required Section 6.5.10 412 Precondition Failed Section 4.2 of [RFC7232] 413 Payload Too Large Section 6.5.11 414 URI Too Long Section 6.5.12 415 Unsupported Media Type Section 6.5.13 416 Range Not Satisfiable Section 4.4 of [RFC7233] 417 Expectation Failed Section 6.5.14 426 Upgrade Required Section 6.5.15 500 Internal Server Error Section 6.6.1501 Not Implemented Section 6.6.2502 Bad Gateway Section 6.6.3503 Service Unavailable Section 6.6.4504 Gateway Timeout Section 6.6.5505 HTTP Version Not Supported Section 6.6.6

The status codes listed below are defined in this specification, Section   4 of [RFC7232] , Section   4 of [RFC7233], and Section   3 of [RFC7235] . The reason phrases listed here are only recommendations -- they can be replaced by local equivalents without affecting the protocol. Responses with status codes that are defined as cacheable by default (e.g., 200, 203, 204, 206, 300, 301, 404, 405, 410, 414, and 501 in this specification) can be reused by a cache with heuristic expiration unless otherwise indicated by the method definition or explicit cache controls [RFC7234]; all other status codes are not cacheable by default.

Annex D[Annex F] DICOM Media TypesD.1[F.1] application/dicomThe application/dicom media type is specified in [IETF RFCRFC ]

The representations returned for this media type shall be encoded as PS3.10 binary objects in an acceptable Transfer Syntax (Explicit VR Little Endian by default) with one payload part per DICOM Instance.

Other types of responses will be encoded in the following manner: (see Figure 6.5-1).

.

•

•

Note

If the Transfer Syntax is not specified, then a reversible (lossless) encoding is used.

4630

4635

4640

4645

D.2[F.2] application/dicom+xmlAll XML responses shall be encoded as described in the Native DICOM Model defined in PS3.19 with one message part per XML object.

D.3[F.3] Application/dicom+json or application/jsonAll JSON responses shall be encoded as a DICOM JSON Model Object as defined in Annex F.

D.4[F.4] application/dicom+bulkdataUncompressed bulk and pixel data shall be encoded in a Little Endian format using the application/octet-stream media type with one message part per bulk databulkdata item.

Compressed pixel data may be encoded in one of three ways:

1. Single-frame pixel data encoded using a single-frame media type (one message part)

2. Multi-frame pixel data encoded using a single-frame media type (one frame per message part)

3. Multi-frame or video pixel data encoded using a multi-frame media type (multiple frames in one message part)

A.2.1 Definition

A.2.2 Schemas

A.2.3 Examples

A.3 application/dicom+json

A.3.1 Definition

A.3.2 Examples

A.4 application/wadl+json

WS Schema

F DICOM JSON ModelF.1 Introduction to JavaScript Object Notation (JSON)JSON is a text-based open standard, derived from JavaScript, for representing data structures and associated arrays. It is language-independent, and primarily used for serializing and transmitting lightweight structured data over a network connection. It is described in detail by the Internet Engineering Task Force (IETF) in RFC 4627, available at http://www.ietf.org/rfc/rfc4627.txt.

The DICOM JSON Model complements the XML-based Native DICOM Model, by providing a lightweight representation of data returned by DICOM web services. While this representation can be used to encode any type of DICOM Data Set it is expected to be used by client applications, especially mobile clients, such as described in the Search use cases (see Chapter HHH in PS3.17).

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

4650

4655

4660

4665

4670

4675

4680

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

F.2.1.1 ExamplesF.2.1.1.1 Native DICOM Model

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

F.2.1.1.2 DICOM JSON Model

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

F.2.2 DICOM JSON Model Object StructureThe DICOM JSON Model object is a representation of a DICOM Data Set.

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

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

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

The name of each attribute object is:

• The eight character uppercase hexadecimal representation of a DICOM Tag

Each attribute object contains the following named child objects:

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

4685

4690

4695

4700

4705

4710

4715

4725

4730

• At most one of:

• Value: An array containing one of:

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

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

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

• Alphabetic

• Ideographic

• Phonetic

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

Empty sequence items are represented by empty objects

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

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

Note

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

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

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

"vr": "CS"

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

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

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

AE Application Entity String

AS Age String String

AT Attribute Tag String

CS Code String String

DA Date String

DS Decimal Number

4735

4740

4745

4750

4755

4760

Code VR Name JSON Data Type

DT Date Time String

FL Floating Point Single Number

FD Floating Point Double Number

IS Integer String Number

LO Long String String

LT Long Text String

OB Other Byte String Base64 encoded string

OD Other Double String Base64 encoded string

OF Other Float String Base64 encoded string

OW Other Word String Base64 encoded string

PN Person Name Object containing Person Name component groups as strings (see Section F.2.2)

SH Short String String

SL Signed Long Number

SQ Sequence Array containing DICOM JSON Objects

SS Signed Short Number

ST Short Text String

TM Time String

UI UID String

UL Unsigned Long Number

UN Unknown Base64 encoded string

UR URI String

US Unsigned Short Number

UT Unlimited Text String

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

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

For example:

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

or:

"Value": [ "bar" ]

4765

4770

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

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

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

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

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

F.2.6 BulkDataURIIf an attribute contains a "BulkdData URI" , this contains the URI ofit is a reference to a bulk data element as defined in Table A.1.5-2 in PS3.19.

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

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

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

Note

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

F.3 Transformation with other DICOM FormatsF.3.1 Native DICOM Model XMLThe transformation between the Native DICOM Model XML and the DICOM JSON model cannot be done through the use of generic XML - JSON converters.

The mapping between the two formats is as follows (see also Table F.3.1-1):

• The XML "NativeDicomModel" element maps to the DICOM JSON Model Object

• Each "DicomAttribute" element maps to an attribute object within the DICOM JSON model object

• The "tag" attribute maps to the JSON object name

• The Native DICOM Model XML allows for duplicate Tag values and the DICOM JSON model does not. To resolve this, private attribute Tag values must be remapped according to the conflict avoidance rules specified in Section 7.8.1 “Private Data Element Tags” in PS3.5.

• The "vr" attribute maps to the "vr" child string

• "Value" elements map to members of the "Value" child array

• A "Value" element with the attribute "number=n" maps to "Value[n-1]"

4780

4785

4790

4795

4800

4805

4810

• Empty "Value" elements are represented by "null" entries in the "Value" array

• "PersonName" elements map to objects within the "Value" array. For a "PersonName" element with the attribute "number=n":

• The "Alphabetic" element maps to "Value[n-1].Alphabetic"

• The "Ideographic" element maps to "PersonName[n].Ideographic"

• The "Phonetic" element maps to "PersonName[n].Phonetic"

- "Item" elements map to members of the "Value" child array

• An "Item" element with the attribute "number=n" maps to "Value[n-1]"

• Empty "Item" elements are represented by empty JSON property entries in the "Value" array

• The "uri" attribute of the "BulkData" element maps to the "BulkDataURI" string

• The "InlineBinary" element maps to the "InlineBinary" string

Table F.3.1-1. XML to JSON Mapping

DICOM PS3.19 XML DICOM JSON Model

<NativeDicomModel>

<DicomAttribute tag= ggggee01 … />

<DicomAttribute tag= ggggee02 … />

…

</NativeDicomModel>

{

ggggee01 : { … },

ggggee02 : { … },

…

}

<DicomAttribute

tag= ggggeeee

vr= VR >

<Value number="1"> Value </Value>

</DicomAttribute>

ggggeeee : {

"vr": VR ,

"Value": [ Value ]

}

<DicomAttribute tag= ggggeeee … >

<Value number="1"> Value1 </Value>

<Value number="2"> Value2 </Value>

…

</DicomAttribute>

ggggeeee : {

…

"Value": [ Value1 ,

Value2 , …

]

}

<DicomAttribute tag= ggggeeee … >

</DicomAttribute>

ggggeeee : {

…

}

4815

4820

4825

DICOM PS3.19 XML DICOM JSON Model

<DicomAttribute tag= ggggeeee vr="PN" … >

<PersonName number="1">

<Alphabetic>

<FamilyName> SB1

</FamilyName>

<GivenName> SB2

</GivenName>

<MiddleName> SB3

</MiddleName>

<NamePrefix> SB4

</NamePrefix>

<NameSuffix> SB5

</NameSuffix>

</Alphabetic>

<Ideographic>

<FamilyName> ID1

</FamilyName>

…

</Ideographic>

<Phonetic>

<FamilyName> PH1

</FamilyName>

…

</Phonetic>

</PersonName>

<PersonName number="2">

<Alphabetic>

<FamilyName> SB6

</FamilyName>

</Alphabetic>

</PersonName>

</DicomAttribute>

ggggeeee : {

…

"vr": "PN",

"Value": [

{

" Alphabetic " : "SB1^SB2^SB3^SB4^SB5",

"Ideographic": "ID1^ID2^ID3^ID4^ID5" ,

"Phonetic": "PH1^PH2^PH3^PH4^PH5"

},

{

"Alphabetic":

" SB6 "

}

]

}

DICOM PS3.19 XML DICOM JSON Model

<DicomAttribute tag= ggggeeee vr="SQ" … >

<Item number="1">

<DicomAttribute tag= ggggee01 … />

<DicomAttribute tag= ggggee02 … />

…

</Item>

<Item number="2">

<DicomAttribute tag= ggggee01 … />

<DicomAttribute tag= ggggee02 … />

…

</Item>

<Item number="3">

</Item>

…

</DicomAttribute>

ggggeeee : {

…

"vr": "SQ",

"Value":

[

{

ggggee01 : { … },

ggggee02 : { … },

…

}

{

ggggee01 : { … },

ggggee02 : { … },

…

}

{ }

…

]

}

<DicomAttribute tag= ggggeeee … >

<BulkData URI= BulkDataURI >

</DicomAttribute>

ggggeeee : {

…

"BulkDataURI": BulkDataURI

}

<DicomAttribute tag= ggggeeee … >

<InlineBinary> Base64String </InlineBinary>

</DicomAttribute>

ggggeeee : {

…

"InlineBinary": " Base64String"

}

<DicomAttribute tag= gggg00ee PrivateCreator= PrivateCreator … >

…

</DicomAttribute>

ggggXXee : {

…

}

F.4 DICOM JSON Model ExampleThe following example is a Storage ServiceSearch for Studies response consisting of two matching studies, corresponding to the example Search request:

GET http://search.nema.org/studies?PatientID=12345&includefield=all&limit=2

[ { // Result 1 "00080005": { "vr": "CS", "Value": [ "ISO_IR192" ] }, "00080020": { "vr": "DT", "Value": [ "20130409" ] }, "00080030": { "vr": "TM", "Value": [ "131600.0000" ] }, "00080050": { "vr": "SH", "Value": [ "11235813" ] }, "00080056": { "vr": "CS", "Value": [ "ONLINE" ] }, "00080061": { "vr": "CS", "Value": [ "CT", "PET" ] }, "00080090": { "vr": "PN", "Value": [ { "Alphabetic": "^Bob^^Dr." } ] }, "00081190": { "vr": "UR", "Value": [ "http://wado.nema.org/studies/ 1.2.392.200036.9116.2.2.2.1762893313.1029997326.945873" ] }, "00090010": { "vr": "LO", "Value": [ "Vendor A" ] }, "00091002": { "vr": "UN", "Value": [ "z0x9c8v7" ] }, "00100010": { "vr": "PN", "Value": [ {

4830

4835

4840

4845

4850

4855

4860

4865

4870

4875

4880

"Alphabetic": "Wang^XiaoDong", "Ideographic": "王^小東" } ] }, "00100020": { "vr": "LO", "Value": [ "12345" ] }, "00100021": { "vr": "LO", "Value": [ "Hospital A" ] }, "00100030": { "vr": "DT", "Value": [ "19670701" ] }, "00100040": { "vr": "CS", "Value": [ "M" ] }, "00101002": { "vr": "SQ", "Value": [ { "00100020": { "vr": "LO", "Value": [ "54321" ] }, "00100021": { "vr": "LO", "Value": [ "Hospital B" ] } }, { "00100020": { "vr": "LO", "Value": [ "24680" ] }, "00100021": { "vr": "LO", "Value": [ "Hospital C" ] } } ] }, "0020000D": { "vr": "UI", "Value": [ "1.2.392.200036.9116.2.2.2.1762893313.1029997326.945873" ] }, "00200010": { "vr": "SH", "Value": [ "11235813" ] }, "00201206": { "vr": "IS", "Value": [ 4 ] }, "00201208": { "vr": "IS", "Value": [ 942 ]

4885

4890

4895

4900

4905

4910

4915

4920

4925

4930

4935

4940

4945

} }, { // Result 2 "00080005": { "vr": "CS", "Value": [ "ISO_IR192" ] }, "00080020": { "vr": "DT", "Value": [ "20130309" ] }, "00080030": { "vr": "TM", "Value": [ "111900.0000" ] }, "00080050": { "vr": "SH", "Value": [ "11235821" ] }, "00080056": { "vr": "CS", "Value": [ "ONLINE" ] }, "00080061": { "vr": "CS", "Value": [ "CT", "PET" ] }, "00080090": { "vr": "PN", "Value": [ { "Alphabetic": "^Bob^^Dr." } ] }, "00081190": { "vr": "UR", "Value": [ "http://wado.nema.org/studies/ 1.2.392.200036.9116.2.2.2.2162893313.1029997326.945876" ] }, "00090010": { "vr": "LO", "Value": [ "Vendor A" ] }, "00091002": { "vr": "UN", "Value": [ "z0x9c8v7" ] }, "00100010": { "vr": "PN", "Value": [ { "Alphabetic": "Wang^XiaoDong", "Ideographic": "王^小東" } ] }, "00100020": {

4950

4955

4960

4965

4970

4975

4980

4985

4990

4995

5000

5005

"vr": "LO", "Value": [ "12345" ] }, "00100021": { "vr": "LO", "Value": [ "Hospital A" ] }, "00100030": { "vr": "DT", "Value": [ "19670701" ] }, "00100040": { "vr": "CS", "Value": [ "M" ] }, "00101002": { "vr": "SQ", "Value": [ { "00100020": { "vr": "LO", "Value": [ "54321" ] }, "00100021": { "vr": "LO", "Value": [ "Hospital B" ] } }, { "00100020": { "vr": "LO", "Value": [ "24680" ] }, "00100021": { "vr": "LO", "Value": [ "Hospital C" ] } } ] }, "0020000D": { "vr": "UI", "Value": [ "1.2.392.200036.9116.2.2.2.2162893313.1029997326.945876" ] }, "00200010": { "vr": "SH", "Value": [ "11235821" ] }, "00201206": { "vr": "IS", "Value": [ 5 ] }, "00201208": { "vr": "IS", "Value": [ 1123 ] } }]

F.5 References

5010

5015

5020

5025

5030

5035

5040

5045

5050

5055

5060

IETF RFCRFC 4627 http://www.ietf.org/rfc/rfc4627.txt (Normative JSON definition)

JSON. http://www.json.org/ (Informative)

Wikipedia, definition of JSON. http://en.wikipedia.org/wiki/JSON (Informative)

JSON in FHIR. http://www.hl7.org/implement/standards/fhir/formats.htm#json (Informative)5070

1 December 2014 Sup 183 Web Services Re-Documentation Page 177

G WADL JSON RepresentationG.1 IntroductionWhile the WADL specification only specifies an XML encoding for the WADL payload, the data structure can easily be represented using JSON. Additionally, conversion from XML to JSON and vice-versa can be done in a lossless manner.

G.2 XML ElementsThe JSON encoding of WADL XML elements depends on whether the element is:

• a "doc" element

• an element that is unique within a particular parent element (e.g., "request")

• an element that can be repeated within a particular parent element (e.g., "param")

G.2.1 Doc ElementsA "doc" element is represented as an array of objects, where each object may contain:

• a "@xml:lang" string

• a "@title" string

• a "value" string

Example:

"doc": [ { "@xml:lang": "en", "value": "Granular cell tumor" }, { "@xml:lang": "ja", "value": "顆粒細胞腫" }, { "@xml:lang": "fr", "value": "Tumeur à cellules granuleuses" }]

G.2.2 Unique ElementsAll unique WADL XML elements are represented as an object whose name is the name of the XML element and where each member may contain:

• a "@{attribute}" string for each XML attribute of the name {attribute}

• a child object for each child element that must be unique

• a child array for each child element that may not be unique

Example:

5075

5080

5085

5090

5095

5100

5105

1 December 2014 Sup 183 Web Services Re-Documentation Page 178

"request": { "param": [ ... ], "representation": [ ... ]}

G.2.3 Repeatable ElementsAll repeatable WADL XML elements are represented as an array of objects whose name is the name of the XML element and where each may contain:

• a "@{attribute}" string for each XML attribute of the name {attribute}

• a child object for each child element that must be unique

• a child array for each child element that may not be unique

Example:

"param": [ { "@name": "Accept", "@style": "header" }, { "@name": "Cache-control", "@style": "header" } ]

****** Extra stuff – delete before publishing ******

RS Resource Hierarchy

A resource hierarchy that includes all Services

/

/retrieve/dicom/studies/…

/retrieve/rendered/studies/…

/retrieve/rendered/ps/studies/…

/store/studies

/search/studies

/search/series

/search/instances

/workflow

A simpler resource hierarchy that includes all Services

/

/retrieve/dicom/…

/retrieve/rendered/…

5110

5120

5125

5130

5135

5140

5145

5150

1 December 2014 Sup 183 Web Services Re-Documentation Page 179

/retrieve/rendered/ps/…

/store/…

/search/…

/search/series

/search/instances

/workflow

5155

5160