| DICOM PS3.18 2024d - Web Services |
|---|
Query Parameters are specified in the query component of the URI (see [RFC3986] Section 3.4.
The query component of a request URI may only be used to specify one or more Query Parameters. These parameters are referred to as Query Parameters to distinguish them from header field parameters or other types of parameters that may be contained in the payload.
The Query Parameters are specified using a URI Template that uses Form {?var} and Query Continuation Style {&var} Query Expansion as defined in [RFC6570].
If a Target URI includes a "query component" (see [RFC3986] Section 3.4), it shall contain Query Parameters that conform to the syntax defined here.
The Services and Transactions defined elsewhere in this Part of the Standard may further refine the qp-name and qp-value rules defined below.
[RFC3986] does not permit an empty query component, i.e., if the "?" appears in the Target URI, then there shall be at least one Query Parameter in the URI.
The origin server may define and support additional Query Parameters, or additional Query Parameter values for an existing Query Parameter. If an origin server defines new or extends existing Query Parameters, they shall be documented in the Conformance Statement and, if the service supports it, the Retrieve Capabilities response.
The origin server shall ignore any unsupported Query Parameters. The origin server shall process the request as if the unsupported parameters were not present and may return a response containing appropriate warning and/or error messages.
If a supported Query Parameter has an invalid value, the origin server shall return a 400 (Bad Request) error response and may include a payload containing an appropriate Status Report.
Query parameters have the following syntax:
query-parameters = "?" parameter *("&" parameter)
Each parameter after the first, is separated from the following parameter by the "&" character. Each parameter has the following syntax:
parameter = qp-name
/ qp-name "=" 1#qp-value
/ qp-name "=" 1#attribute
/ attribute
/ attribute "=" 1#qp-value
The qp-name is case sensitive, and starts with an alphabetic or underscore character, followed by zero or more alphanumeric or underscore "_" characters:
qp-name = %s 1*(ALPHA / "_") *(ALPHA / DIGIT / "_")
A qp-name by itself (with no values) is a legal Query Parameter. A parameter qp-name may also be followed by a comma-separated list of one or more qp-values, or one or more Attributes.
The qp-values are case-sensitive. A qp-value is composed of qp-chars, where qp-char is the set of legal query component characters as defined by [RFC3986], minus the equal ("="), ampersand ("&"), and comma (",") characters.
qp-value = %s DQUOTE 1*qp-char DQUOTE
qp-char = unreserved / pct-encoded / qp-special
qp-special = "!" / "$" / "'" / "(" / ")" / "*" / "+" / ";" /":" / "@" / "/" / "?"
The only visible US-ASCII characters disallowed in the query component by [RFC3986] are "#", "[", "]". This Part of the Standard further disallows "&", "=", and ",". However, the characters ("#", "[", "]" "&", "=", and ",".) may be included in qp-values if they are percent encoded.
Each Attribute is either a simple-attribute or a sequence-attribute:
attribute = simple-attribute / sequence-attribute
A simple-attribute is a single Data Element Tag or Keyword (see Table 6-1 “Registry of DICOM Data Elements” in PS3.6) that does not have a VR of SQ:
simple-attribute = keyword / tag keyword = %s DQUOTE 1*ALPHA *(ALPHA / DIGIT) DQUOTE tag = 8HEXDIG
DICOM keywords are case sensitive; they shall start with an alphabetic character followed by zero or more alphanumeric characters. See PS3.6.
A sequence-attribute is two or more attributes separated by the dot character ("."), all but the last attribute shall have a VR of SQ, and the last attribute shall not have a VR of SQ.
sequence-attribute = (keyword / tag) *("." attribute)
The following are examples of valid values for attribute:
0020000D
StudyInstanceUID
00101002.00100020
OtherPatientIDsSequence.PatientID
00101002.00100024.00400032
OtherPatientIDsSequence.IssuerOfPatientIDQualifiersSequence.UniversalEntityID
Some Query Parameters have a qp-name, which is an attribute, and a value that is a comma-separated list of one or more qp-values. The qp-values of an attribute parameter shall satisfy its Value Representation and Value Multiplicity, as defined in PS3.5 and PS3.6, of the corresponding attribute.
Unlike the Value Representations defined in PS3.5, Query Parameters:
shall encode UIDs as specified in PS3.5, except that they shall not be padded to an even length
The syntax and semantics of valid qp-names, qp-values and attributes are specified by the defining Service or Transaction; however, they shall conform to the rules in this Section.
Table 8.3.1-1 contains the collected syntax of Query Parameters. The Services and Transactions defined elsewhere in this Part of the Standard may further refine the qp-name, attribute, and qp-value rules.
All qp-names are case sensitive.
Table 8.3.1-1. ABNF for Query Parameter
query-parameters |
= "?" parameter *("&" parameter)
|
parameter |
= qp-name; a name only / qp-name "=" 1#qp-value ; a name with one or more values / qp-name "=" 1#attribute; a name with one or more attributes / attribute; an attribute only / attribute "=" 1#qp-value ; an attribute with one or more values |
qp-name |
= %s (ALPHA / "_") *(ALPHA / DIGIT / "_") |
qp-value |
=int / uint / pos-int / decimal / float /string / base64 / uid / %s 1*qp-char/ %s DQUOTE 1*qp-special DQUOTE; See Section 5.1.1 |
qp-char |
= unreserved / pct-encoded |
qp-special |
= "!" / "$" / "'" / "(" / ") " / "*" / "+" / ";"/":" / "@" / "/" / "?"
|
simple-attribute |
= keyword / tag |
sequence-attribute |
= keyword *( "." attribute) / tag *( "." attribute ) |
keyword |
= %suppercase *( ALPHA / DIGIT ) |
uppercase |
=%x41-5A |
tag |
= 8HEXDIG |
The syntax of qp-values is defined in Section 5.1.1.
The qp-char (Query Parameter characters) rule defined above is the query rule of [RFC3986], which defines the legal characters for the query component, minus the equal sign ("="), comma (","), and ampersand ("&"). So, the qp-char rule is the VCHAR rule minus "#", "[", "]", "=", "&", and ",".
All DICOM keywords are case sensitive. See PS3.6.
| DICOM PS3.18 2024d - Web Services |
|---|