OWS Common change request: Add SOAP encoding
OGC Doc 06-094r1
Open Geospatial Consortium
CR-Form-v3
CHANGE REQUEST
OWS Common CR ?
rev
1-
Current version:
1.1.0
For HELP on using this form, look at the pop-up text over the symbols.
Proposed change affects:
AS
Imp Spec X
Recom. Paper
Title:
OWS Common change request: Add SOAP encoding
Source:
Arliss Whiteside, Bastian Schaeffer
Work item code:
Category:
Other
Date: 2008-02-11
B
Use one of the following categories:
F (Critical correction)
A (corresponds to a correction in an earlier release)
B (Addition of feature),
C (Functional modification of feature)
D (Editorial modification)
Reason for change:
Some uses of all OGC Web Services (interface specifications) require use of
SOAP encoding
Summary of change: Add specifications of how to use SOAP encoding for transferring OGC Web
Service operation requests and responses, and how to show support of SOAP
encoding in the OperationsMetadata section of a Capabilities document
Consequences if
not approved:
Continued use of not-OGC-standardized SOAP encoding of OGC Web Service
operation requests and responses
Clauses affected:
3, 7.2.4, 7.4.6, 7.4.10, 8.6, 9.2.4, 9.4.1.5, 9.4.2.1, 11.1, 11.8
Other specs
Affected:
Other comments:
This change request is based on correcting and improving the SOAP encoding
specified in the WFS 1.1 and Catalog 2.0 already approved Implementation
Specifications and the OWS-5 results manifested in [OGC#: 08-009]
Other core specifications
Abstract specifications
Recommendation Papers
(Add following reference to Clause 3 of OWS Common specification:)
W3C Recommendation (24 June 2003): SOAP Version 1.2 Part 1: Messaging
Framework, http://www.w3.org/TR/SOAP/
Copyright © 2006 Open Geospatial Consortium, Inc. All Rights Reserved.
1
06-094
W3C Recommendation (25 January 2005): SOAP Message Transmission
Optimization Mechanism
W3C Recommendation (25 January 2005): XML-binary Optimized Packaging
Copyright © 2006 Open Geospatial Consortium, Inc. All Rights Reserved.
2
06-094
(Add following subclauses to OWS Common specification:)
11.8
SOAP encoding
Specific OWS specifications shall specify that servers may optionally implement SOAP
1.2 transfer of all operation requests and responses, using the same XML encodings as
specified for use with HTTP POST. When SOAP encoding is implemented, the SOAP
Request-Response message exchange pattern shall be used with the HTTP POST binding.
For SOAP transfer, each XML-encoded operation request shall be encapsulated in the
body of a SOAP envelope. In other words, the SOAP-Body shall be used only for
transmitting the actual OWS Service request.
The optional SOAP-Header shall be used for optional elements (NOT parameters) in
order to invoke the service and could be targeted at any SOAP receiver in the SOAP
message path. For instance, these elements could be identity tokens, licenses or other
elements that are not necessarily required by the implementation specification but are
additionally required to invoke the service and may be expressed as preconditions in a
WS-Policy WSDL attachment.
, which shall contain only a body and only this request in that body. Similarly, each
XML-encoded operation response shall be encapsulated in the body of a SOAP envelope.
Again, the optional header should be used for elements not directly related to the
operation response, e.g. licenses or information targeted at an SOAP receiver in the
SOAP message path., which shall contain only a body and only this response in that
body. An OWS server shall return operation responses and error messages using only
SOAP transfer when the operation request is sent using SOAP.
The SOAP 1.2 specification allows different styles and encodings. For the use of SOAP
with OGC Web Services only the Document Literal-Wrapped style shall be used.
For binary data send via a SOAP message, the Message Transportation Optimization
Mechanism (MTOM) shall be used in conjunction with XML-binary Optimized
Packaging (XOP).
All compliant OWS servers shall specify the URLs to which SOAP-encoded operation
requests may be sent, within the OperationsMetadata section of a service metadata
(Capabilities) XML document, as specified in Subclause 7.4.6. If an error is detected
while processing an operation request encoded in a SOAP envelope, an OWS server shall
generate a SOAP response message where the content of the Body element is a Fault
element containing an ExceptionReport element, as specified in Subclause 8.6.
7.2.4
GetCapabilities request SOAP encoding
Specific OWS servers may implement SOAP version 1.2 transfer of the GetCapabilities
operation request as specified in Subclause 11.8, using the XML encoding specified
above.
Copyright © 2006 Open Geospatial Consortium, Inc. All Rights Reserved.
3
06-094
7.4.10
Capabilities document SOAP encoding
Specific OWS servers may implement SOAP version 1.2 transfer of the GetCapabilities
operation response (service metadata or Capabilities document) as specified in Subclause
11.8, using the XML encoding specified above.
8.6
Exception report SOAP encoding
Specific OWS servers may optionally implement SOAP version 1.2 transfers of all
operation requests as specified in Subclause 11.8. If an error is detected while processing
an operation request encoded in a SOAP envelope, the OWS server shall generate a
SOAP response message where the content of the Body element is a Fault element
containing an ExceptionReport element. This shall be done using the following XML
fragment:
soap:Server
A server exception was encountered.
...
The Code element shall have the Value “soap:server” indicating that this is a server
exception. The Reason element shall have the Text “Server exception was encountered.”
This fixed string is used since the details of the exception shall be specified in the Detail
element using an ows:ExceptionReport element as specified in Subclause 8.5.
9.2.4
Operation request SOAP encoding
Specific OWS specifications shall specify that servers may implement SOAP 1.2 transfer
of all operation requests, as specified in Subclause 11.8, using the XML encoding
specified above.
10.1.1.1 GetResourceByID request SOAP encoding
Specific OWS specifications shall specify that servers may implement SOAP 1.2 transfer
of GetResourceByID operation requests, as specified in Subclause 11.8, using the XML
encoding specified abovein Subclause 11.8.
Copyright © 2006 Open Geospatial Consortium, Inc. All Rights Reserved.
4
06-094
(Add following to end of Subclause 9.4.2.1 GetResourceByID normal
response:)
Specific OWS specifications shall specify that servers may implement SOAP 1.2 transfer
of GetResourceByID operation responses, as specified in Subclause 11.8, using the same
XML encoding.
(Add following to end of Subclause 7.4.6 OperationsMetadata section
standard contents:)
All OWS servers shall specify the encodings that may be sent using HTTP POST transfer
of operation requests. Specifically, an ows:Constraint element shall be included, with
“PostEncoding” as the value of the “name” attribute and specifying different allowed
values for each allowed encoding:
a) The value “SOAP” shall indicate that SOAP encoding is allowed, as specified in
Subclause 11.8.
b) The value “XML” shall indicate that XML encoding is allowed (without SOAP
message encapsulation).
c) The value “KVP” shall indicate that KVP encoding is allowed.
If the HTTP POST connect point URL is different for different encodings of the operation
requests, this ows:Constraint element shall be included in each Post element. If the
connect point URL is the same for all encodings of all operation requests, this
ows:Constraint element shall be included in the OperationsMetadata element.
(Change Subclause 11.1 as follows:)
11.1
General HTTP rules
This specification applies to OWS interfaces that use the distributed computing platform
(DCP) comprising Internet hosts that support the Hypertext Transfer Protocol (HTTP)
[IETF RFC 2616]. Thus the Online Resource of each operation supported by a server is
an HTTP Uniform Resource Locator (URL). Each URL shall conform to the description
in Section 3.2.2 "HTTP URL" of [IETF RFC 2616], but is otherwise server
implementation dependent. Only the query portion comprising the service request itself is
defined by this specification.
This document defines two methods of encoding OWS operation requests. One method
uses XML as the encoding language, and the other method uses keyword-value pairs to
encode the various parameters. An example of a keyword value pair (KVP) is:
REQUEST=GetCapabilities
Copyright © 2006 Open Geospatial Consortium, Inc. All Rights Reserved.
5
06-094
where "REQUEST" is the parameter name and "GetCapabilitites" is the value. A KVP
value may include XML encoded elements. In both cases, the response to a request or
exception reporting must be identical.
HTTP supports two request methods: GET and POST. One or both of these methods may
be offered by a server for each operation, and the use of the Online Resource URL differs
in each case. This document defines three methods of encoding OWS operation requests,
and all three may be used with HTTP POST transfer of operation requests. One method
uses keyword-value pairs to encode the various parameters; only KVP encoded operation
requests can be used with HTTP GET transfer of operation requests.
The other two methods use XML encoding of operation requests, with the operation
request encoded as one XML element. This XML encoded operation request can be
transferred as-is (bare), or contained in the body of a SOAP message as specified in
Subclause 11.8.
Copyright © 2006 Open Geospatial Consortium, Inc. All Rights Reserved.
6
Open Geospatial Consortium
CR-Form-v3
CHANGE REQUEST
OWS Common CR ?
rev
1-
Current version:
1.1.0
For HELP on using this form, look at the pop-up text over the symbols.
Proposed change affects:
AS
Imp Spec X
Recom. Paper
Title:
OWS Common change request: Add SOAP encoding
Source:
Arliss Whiteside, Bastian Schaeffer
Work item code:
Category:
Other
Date: 2008-02-11
B
Use one of the following categories:
F (Critical correction)
A (corresponds to a correction in an earlier release)
B (Addition of feature),
C (Functional modification of feature)
D (Editorial modification)
Reason for change:
Some uses of all OGC Web Services (interface specifications) require use of
SOAP encoding
Summary of change: Add specifications of how to use SOAP encoding for transferring OGC Web
Service operation requests and responses, and how to show support of SOAP
encoding in the OperationsMetadata section of a Capabilities document
Consequences if
not approved:
Continued use of not-OGC-standardized SOAP encoding of OGC Web Service
operation requests and responses
Clauses affected:
3, 7.2.4, 7.4.6, 7.4.10, 8.6, 9.2.4, 9.4.1.5, 9.4.2.1, 11.1, 11.8
Other specs
Affected:
Other comments:
This change request is based on correcting and improving the SOAP encoding
specified in the WFS 1.1 and Catalog 2.0 already approved Implementation
Specifications and the OWS-5 results manifested in [OGC#: 08-009]
Other core specifications
Abstract specifications
Recommendation Papers
(Add following reference to Clause 3 of OWS Common specification:)
W3C Recommendation (24 June 2003): SOAP Version 1.2 Part 1: Messaging
Framework, http://www.w3.org/TR/SOAP/
Copyright © 2006 Open Geospatial Consortium, Inc. All Rights Reserved.
1
06-094
W3C Recommendation (25 January 2005): SOAP Message Transmission
Optimization Mechanism
W3C Recommendation (25 January 2005): XML-binary Optimized Packaging
Copyright © 2006 Open Geospatial Consortium, Inc. All Rights Reserved.
2
06-094
(Add following subclauses to OWS Common specification:)
11.8
SOAP encoding
Specific OWS specifications shall specify that servers may optionally implement SOAP
1.2 transfer of all operation requests and responses, using the same XML encodings as
specified for use with HTTP POST. When SOAP encoding is implemented, the SOAP
Request-Response message exchange pattern shall be used with the HTTP POST binding.
For SOAP transfer, each XML-encoded operation request shall be encapsulated in the
body of a SOAP envelope. In other words, the SOAP-Body shall be used only for
transmitting the actual OWS Service request.
The optional SOAP-Header shall be used for optional elements (NOT parameters) in
order to invoke the service and could be targeted at any SOAP receiver in the SOAP
message path. For instance, these elements could be identity tokens, licenses or other
elements that are not necessarily required by the implementation specification but are
additionally required to invoke the service and may be expressed as preconditions in a
WS-Policy WSDL attachment.
, which shall contain only a body and only this request in that body. Similarly, each
XML-encoded operation response shall be encapsulated in the body of a SOAP envelope.
Again, the optional header should be used for elements not directly related to the
operation response, e.g. licenses or information targeted at an SOAP receiver in the
SOAP message path., which shall contain only a body and only this response in that
body. An OWS server shall return operation responses and error messages using only
SOAP transfer when the operation request is sent using SOAP.
The SOAP 1.2 specification allows different styles and encodings. For the use of SOAP
with OGC Web Services only the Document Literal-Wrapped style shall be used.
For binary data send via a SOAP message, the Message Transportation Optimization
Mechanism (MTOM) shall be used in conjunction with XML-binary Optimized
Packaging (XOP).
All compliant OWS servers shall specify the URLs to which SOAP-encoded operation
requests may be sent, within the OperationsMetadata section of a service metadata
(Capabilities) XML document, as specified in Subclause 7.4.6. If an error is detected
while processing an operation request encoded in a SOAP envelope, an OWS server shall
generate a SOAP response message where the content of the Body element is a Fault
element containing an ExceptionReport element, as specified in Subclause 8.6.
7.2.4
GetCapabilities request SOAP encoding
Specific OWS servers may implement SOAP version 1.2 transfer of the GetCapabilities
operation request as specified in Subclause 11.8, using the XML encoding specified
above.
Copyright © 2006 Open Geospatial Consortium, Inc. All Rights Reserved.
3
06-094
7.4.10
Capabilities document SOAP encoding
Specific OWS servers may implement SOAP version 1.2 transfer of the GetCapabilities
operation response (service metadata or Capabilities document) as specified in Subclause
11.8, using the XML encoding specified above.
8.6
Exception report SOAP encoding
Specific OWS servers may optionally implement SOAP version 1.2 transfers of all
operation requests as specified in Subclause 11.8. If an error is detected while processing
an operation request encoded in a SOAP envelope, the OWS server shall generate a
SOAP response message where the content of the Body element is a Fault element
containing an ExceptionReport element. This shall be done using the following XML
fragment:
soap:Server
A server exception was encountered.
...
The Code element shall have the Value “soap:server” indicating that this is a server
exception. The Reason element shall have the Text “Server exception was encountered.”
This fixed string is used since the details of the exception shall be specified in the Detail
element using an ows:ExceptionReport element as specified in Subclause 8.5.
9.2.4
Operation request SOAP encoding
Specific OWS specifications shall specify that servers may implement SOAP 1.2 transfer
of all operation requests, as specified in Subclause 11.8, using the XML encoding
specified above.
10.1.1.1 GetResourceByID request SOAP encoding
Specific OWS specifications shall specify that servers may implement SOAP 1.2 transfer
of GetResourceByID operation requests, as specified in Subclause 11.8, using the XML
encoding specified abovein Subclause 11.8.
Copyright © 2006 Open Geospatial Consortium, Inc. All Rights Reserved.
4
06-094
(Add following to end of Subclause 9.4.2.1 GetResourceByID normal
response:)
Specific OWS specifications shall specify that servers may implement SOAP 1.2 transfer
of GetResourceByID operation responses, as specified in Subclause 11.8, using the same
XML encoding.
(Add following to end of Subclause 7.4.6 OperationsMetadata section
standard contents:)
All OWS servers shall specify the encodings that may be sent using HTTP POST transfer
of operation requests. Specifically, an ows:Constraint element shall be included, with
“PostEncoding” as the value of the “name” attribute and specifying different allowed
values for each allowed encoding:
a) The value “SOAP” shall indicate that SOAP encoding is allowed, as specified in
Subclause 11.8.
b) The value “XML” shall indicate that XML encoding is allowed (without SOAP
message encapsulation).
c) The value “KVP” shall indicate that KVP encoding is allowed.
If the HTTP POST connect point URL is different for different encodings of the operation
requests, this ows:Constraint element shall be included in each Post element. If the
connect point URL is the same for all encodings of all operation requests, this
ows:Constraint element shall be included in the OperationsMetadata element.
(Change Subclause 11.1 as follows:)
11.1
General HTTP rules
This specification applies to OWS interfaces that use the distributed computing platform
(DCP) comprising Internet hosts that support the Hypertext Transfer Protocol (HTTP)
[IETF RFC 2616]. Thus the Online Resource of each operation supported by a server is
an HTTP Uniform Resource Locator (URL). Each URL shall conform to the description
in Section 3.2.2 "HTTP URL" of [IETF RFC 2616], but is otherwise server
implementation dependent. Only the query portion comprising the service request itself is
defined by this specification.
This document defines two methods of encoding OWS operation requests. One method
uses XML as the encoding language, and the other method uses keyword-value pairs to
encode the various parameters. An example of a keyword value pair (KVP) is:
REQUEST=GetCapabilities
Copyright © 2006 Open Geospatial Consortium, Inc. All Rights Reserved.
5
06-094
where "REQUEST" is the parameter name and "GetCapabilitites" is the value. A KVP
value may include XML encoded elements. In both cases, the response to a request or
exception reporting must be identical.
HTTP supports two request methods: GET and POST. One or both of these methods may
be offered by a server for each operation, and the use of the Online Resource URL differs
in each case. This document defines three methods of encoding OWS operation requests,
and all three may be used with HTTP POST transfer of operation requests. One method
uses keyword-value pairs to encode the various parameters; only KVP encoded operation
requests can be used with HTTP GET transfer of operation requests.
The other two methods use XML encoding of operation requests, with the operation
request encoded as one XML element. This XML encoded operation request can be
transferred as-is (bare), or contained in the body of a SOAP message as specified in
Subclause 11.8.
Copyright © 2006 Open Geospatial Consortium, Inc. All Rights Reserved.
6