Loading...
 
ESA > Join & Share > HMA > HMA-FO OWS Common 1.2 review
Print

HMA-FO OWS Common 1.2 review

OWS Common 1.2 review

Points to be considered regarding the impact of moving to OWS Common 1.2 (or not). Points to be added by 13/11 and discussions completed by 19/11.
 
The document to review is 06-121r8 "OGC Web Services Common 1.2 Implementation Standard", which can be found at: http://portal.opengeospatial.org/files/?artifact_id=35497
 

Task 1

 

Task 2

Clarification of Reference / ServiceReference Usage

Preface

Reference/ServiceReference is going to be used by SPS in its DescribeResultAccess operation to inform clients from which services they can retrieve data. The information provided includes the service type and URL if the question is at which services a sensor stores its data in general. This is useful for clients as they can determine whether they will be able to access the data or not - for example, a sensor might only store data in a SOS, while another one might provide data only through a WCS. A sensor could even use different service types (like a SOS for basic data storage, a WCS for processed data with subsetting abilities and a WMS for direct portrayal). If clients want to access data gathered in an actual task performed by the sensor then the SPS would also include the request parameters required to directly retrieve the actual data (can be a complete KVP encoded request, or an XML request that needs to be posted to the service).

Issue description

OWS Common 1.2 has an optional ows:type attribute in the XML encoding of the ReferenceBase type (see the UML model on page 105 of the OWS Common 1.2 specification and the AbstractReferenceBase element in the owsManifest.xsd schema). This could well be used by SPS to indicate which type of service a reference points to.

The issue is that this attribute is not contained in the UML model of ReferenceBase and not documented in the specification and schema. It just exists in the schema.

Therefore, OWS Common 1.2 should:

  • add the "type" property to the UML model of ReferenceBase (the property could be renamed if required to clarify intended semantics) and
  • document it both in the specification and schema

The content of the "type" property could be the service abbreviation (like WCS, WFS, SOS etc.) but would ideally contain the namespace of the service type that is implemented. In the case of OGC services, this would clearly identify both the service type and implemented version. For example, if the value of "type" would be "http://www.opengis.net/sos/2.0" then the service would be a SOS version 2.0. In case the namespace does not contain the version number then still the service type can be identified.

Related issue

The actual type and encoding of the "type" property should also be compatible to the notation of the "serviceType" property in the ServiceIdentification section - see table 11 in 7.4.4.1. There, the "serviceType" is given as a Code (in ISO 19136 this would be a GenericName) with an actual code value and an optional codeSpace. In table 11, the code value is required to be a URN according to the OGC-NA policies and procedures (syntax: "urn:ogc:serviceType" ":" name ":" version ":" binding ":" profile - see http://www.opengeospatial.org/ogcUrnPolicy). This would mean that only URNs registered at OGC would be allowed. The question is if this mechanism is applicable also to non-OGC services that might be used by SPS. If it is not, then the requirement in the OWS Common 1.2 specification to only use OGC governed URNs as service type identifiers should be relaxed.

Possible impact

If this issue was addressed, then an upcoming version of SPS could leverage the functionality of References / ServiceReferences defined by OWS Common directly rather than to clarify its use for the SPS standard. This would also improve consistent use across OWS, for example in WPS (where References / ServiceReferences might play a role as well).

 

Multi-Language Support via AcceptLanguages Parameter

Preface

Clause 7.3.6 in OWS Common 1.2 mentions the inclusion of an acceptLanguages parameter in all OWS requests. This parameter is defined in detail for the GetCapabilities operation. A client may provide a list of languages in preferred order and the service creates a response using the supported language that has highest client preference - if none of the requested languages is supported an exception is thrown.

Issue description

There are several issues here:

  1. The examples in section 7.3.6 show when an exception is thrown in two situations. However, nothing is said about which exception code should be used to describe which situation. These situations should be documented as clearly as possible in the standard.
  2. Right now the description of the acceptLanguages parameter allows only one language in the response - however, at SPS we could support responses with messages in multiple languages (e.g. both in French and English). The description in OWS Common 1.2 should thus be relaxed to support provision of more than one language (in properties that are designed for that purpose) if supported by the service and requested by the client. This might require another parameter to indicate whether multi-language response is desired by the client or not - same for the service to indicate support for this functionality.
  3. The encoding of the OWSServiceMetadata (type in UML) as GetCapabilitiesBaseType in owsGetCapabilities.xsd (notice the clash of naming here) shows a "Languages" element which looks like another section that can be queried by a client to know about all languages supported by a service. However, the UML model of GetCapabilities and OWSServiceMetadata on page 144 (figure C.2) does not show this section (neither in the "Section" code list nor as property of OWSServiceMetadata). However, with respect to multi-language support in all OWS operations, this section should be queryable. The UML model and XML encoding thus need to be updated:
    • add "languages" code to "Section" code list
    • add property "languages" to OWSServiceMetadata
    • make "Languages" (or LanguagesMetadata) a type in the UML model - for example like OperationsMetadata - with according encoding as global XML element.
    • preferably, rename OWSServiceMetadata to CapabilitiesBase or vice versa so that UML model and XML encoding have a better match.
    • add abstract element "CapabilitiesBase" to XML encoding in owsGetCapabilities.xsd (pending name changes - see above) of type CapabilitiesBaseType to enable correct substitution of this abstract class by OWS - right now a correction of the automatically encoded service model from SPS is needed because no such element type exists which the SPS Capabilities element can state as its substitution group.

 

Request Base Type

Preface

In clause 9.2, basic functionality for all OWS requests is described. The acceptLanguages parameter is listed in table 29 and included in example KVP and XML encodings. KVP is fine.

Issue description

There are several issues here:

  1. The XML complexType "RequestBaseType" shown in 9.2.3 is NOT included in the schema of OWS Common 1.2 - this requires all specifications to copy the type definition in their own schema instead of just extending the type from OWS Common, which would be preferable. Thus, this abstract type - and an according abstract element - should be added to the schema of OWS Common.
  2. The UML class of "RequestBase" shown in 9.2.1 contains the mandatory service and version parameters. In addition, it contains a property named "request" which usually is given implictly by the name of the class that is derived from "RequestBase".
    • Therefore, the "request" property should be removed from the UML model - it seems to be a relic in support of KVP, though a trivial rule can be designed for the KVP encoding of an operation to require that the KVP parameter list includes a request parameter with the value being the name of the operations request class (e.g. "Submit" in SPS ... or "GetCapabilities" for the well-known operation). ... if the removal of the "request" property from RequestBase is accepted, then that property should also be removed from the UML model of the GetCapabilities operation (see figure C.2).
    • The UML of "RequestBase" is also not showing the acceptLanguages parameter. This property should be added, cardinality being 0..1 and type being CharacterString (or GenericName so that the codeSpace could be indicated if needed - this could for example point to the specification / dictionary where the language code is defined).

Related issue (minor - but to be considered at least for the following version of OWS Common)

Basically, as the namespace of an OWS nowadays not only identifies the service type but the version as well, one could think about removing the "service" and "version" properties in RequestBase completely. The reason is that all XML encoded service requests would use that namespace in the root element of the request anyway. For KVP encoded requests the properties could be added again. It seems like a KVP binding should list all possible parameters and their encoding in a separate table anyway - especially because some complex properties contained in the UML model of a service request would need special treatment in KVP encoding.

In the UML model, the package information could / would(?) carry the information of service type and version. Then the question is if common OWS operation parameters (like for example the acceptLanguages parameters) would not better be put into common extension elements of operation requests and responses (like defined in the SWE Service Model).

It is unlikely that such a change can/will be made to OWS Common 1.2, but it should be considered for the following version of OWS Common.

 
Clarification of profile property

Preface

The ServiceIdentification section - see 7.4.4 - now contains a profile property of cardinality 0..*. Table 11 states that the definition of this property is: "Identifier of OGC Web Service (OWS) Application Profile".

Issue description

This property and its definition seem to be outdated with respect to "The Specification Model" (see OGC 08-131r3), especially that specifications are going to be structured in conformance classes that are supported by implementations (or not).

The "profile" property should be revised to support this new concept.

Possible impact

With respect to SPS, it would be desirable to indicate which profile(s) / set of conformance classes a specific service instance supports. This is especially true as the SPS EO profile will extend the SPS functionality and thus clients could readily determine that the EO profile is supported by a service or not. In addition, service requests and responses now allow additional parameters via extension elements (see SWE Service Model specification, work in progress and foreseen to be ready at Nov 19th 09). With a revised "profile" element, a service could indicate which extensions it supports.

 

Profile version identification

Preface

The OWS Common 1.2 SWG Scope of Work includes the need to

Define a URN to Identify Service Type

The current ServiceType syntax (https://portal.opengeospatial.org/twiki/bin/view/Member/OGCUrnIntro) has the form

"urn:ogc:serviceType" ":" name ":" version ":" binding ":" profile, for example

urn:ogc:serviceType:WebMapService:1.3:HTTP:EOP

for the WMS EOP application profile service type. 
 
Issue description
This URN syntax does not allow the version of the profile to be resolved.
 
Possible impact
It would be useful if this issue could be addressed to better support the resolution of (EOP) profiles

 

Service Identity

Preface

The ServiceIdentification section in the Capabilities document does not contain a field for providing an identifier for the service instance that is represented through the Capabilities. The URL of the service can not be used as the identifier in all cases (e.g. in case of URLs using an IP address instead of a domain name). It would be beneficial to be able to reference a certain service instance by a given identifier from within a notification sent by that service. For example, in a notification that contains a CapabilitiesChanged event as message, the service identifier could be used to indicate which service's Capabilities document changed exactly.

Issue description

An optional identifier property should be added to the ServiceIdentification section. The property should be of type GenericName / Code - i.e. with optional codeSpace and required string value.

 

Guidelines for creating and using WSDL
 
Preface
Annex E in OWS Common defines "Guidelines for creating and using WSDL". This Annex is informative. In clause E.2 ("Relationship to OGC service descriptions"), a way is shown with which the WSDL description of a service can be referenced from within the Capabilities document of a service. This is a nice feature.
 
Issue description
However, the XML Schema from OWS Common for the CapabilitiesBaseType and otherwise do not contain such an element at all, though it would be quite helpful. Why is it not included / defined as an optional part of the CapabilitiesBaseType (or sub-component)? It could for example be another - optional - section of the Capabilities document that can be queried by clients.

 

SOAP Version

Preface

Clauses 8.7 and 11.8 are about SOAP bindings of services.

Clause 8.7 states: "Specific OWS servers may optionally implement SOAP version 1.2 transfers of all operation requests as specified in Subclause 11.8."

Clause 11.8 states: "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."

While the first statement would express that SOAP v1.2 is not required by a serivce's SOAP binding, in combination with the second statement it becomes mandatory. While the second statement does not seem to prohibit SOAP v1.1, it clearly states that at least a SOAP binding based upon SOAP v1.2 is required by a service.

Issue description

The question is if such a requirement is necessary. It would also be possible to say that the SOAP version should not be specified by the standard (OWS Common) itself but that it rather should be chosen by an actual implementation. Some existing standards and applications are designed to use SOAP 1.1 while others prefer 1.2, others may support both. For example, the INSPIRE directive seems to rely on SOAP v1.1 in its current form though the switch to 1.2 is foreseen as soon as WS-I BasicProfile 2.0 will change from draft to final version (see clause 5.1 in the INSPIRE Network Services SOAP Framework - http://inspire.jrc.ec.europa.eu/reports/ImplementingRules/network/INSPIRE_NETWORK_SERVICES_SOAP_Framework.pdf)

OWS Common should be agnostic to the SOAP version so that implementations may choose freely.

 

SOAP Exception

Preface

Clause 8.7 "Exception report SOAP encoding" in OWS Common defines a fault structure for delivery of OWS exceptions.

Issue description

The following issues have been identified:

  1. Faults should be expressible in both SOAP 1.1 and SOAP 1.2 - this is related to the topic of "SOAP Version"
  2. soap:Fault/soap:Code - the code value of the SOAP fault is set to soap:Server (by the way, in SOAP 1.2 this would be soap:Receiver, no longer soap:Server - which is used in SOAP 1.1); this should not be restricted to Server allone, because some exceptions detected by the service may also be caused by the client. For example, if the service detects that the request sent by the client is invalid and therefore generates an exception, the code should indicate the client, not the server as causing the exception. In general it would be better to define which code value should be used with which OWS exception code in the SOAP binding of that OWS (if the exception code can clearly be assigned to one of them - otherwise, it should clearly be said that both entities may be responsible ... these occasions should be quite rare, though).
    1. as a sub-issue here, the document does not say anything on possible sub-codes of a fault; these optional elements of a SOAP 1.2 fault could for example be used to contain the OWS exception code - note that the idea of using QNames as type of these exception codes is to identify the namespace where the actual (error) code value is defined, which is not impractical as code reuse and exact definition (if code semantics evolve over time) can be provided using code values together with their namespaces (note that this does not mean that a code value's namespace has to change with each new version of the standard that defines it ... a standard should rather use dictionaries which can be versioned outside the standard itself)
  3. soap:Fault/soap:Detail - the document states that the ows:ExceptionReport shall be used; according to clause 8.2, the exceptions contained in such a report shall be independent errors ... it is questionable if a list of independent exceptions should be returned for the following reasons:
    1. in which situations can independent errors be detected? ... certainly, it would be benefitial to tell a client as much as possible about what errors were detected but is it not rather the case that an application throws one exception as soon as it detected it?
    2. how do multiple exceptions with different codes in one exception report work together with the HTTP codes as defined in section 8.6? For example, if an exception report contained two exceptions with codes OptionNotSupported and MissingParameterValue - what would the HTTP status code of the response then be
      1. Table 28 states the HTTP status code "3xx, 4xx, 5xx" to be used for an exception with code NoApplicableCode - this value is not sufficiently documented. Is an implementation free to choose any of the 3xx, 4xx, 5xx codes it likes?
      2. Some SOAP implementations do not support setting of the HTTP status code in faults they send - OWS Common should therefore not require (instead only recommend) to set the status code on HTTP messages that carry exceptions. "HTTP message" is used explicitly here rather than HTTP response because in a SOAP binding using WS-Addressing, the response to an operation request may actually be sent via another HTTP request asynchronously.
  4. It is not fully clear whether only the ows:ExceptionReport data type can be used to encode exceptions (whether as standalone XML instance or inside a SOAP fault). The wording in the specification suggests that only ows:ExceptionReport shall be used - however, if only one exception would be contained in such a report, then it would make sense to also return an ows:Exception directly, without the surrounding ows:ExceptionReport element.

A solution for issue 3 could be:

  • to require that an exception report only contains one exception (and maybe thereby also allow that an ows:Exception may be used directly - see issue 4.)
  • that the exception which first triggered the 'exception report' determines the HTTP status code - and in the SOAP 1.2 binding also the fault sub-code; the meaning of "first" is defined by the service
  • that an HTTP status code is assigned to exception reports which contain exceptions that would result in a conflicting HTTP status code - the SOAP fault sub-code could be omitted completely in this case or another code value be defined to express that multiple reasons exist why the fault was raised, further defined in the details element

Task 3

 

Task 4

 


Contributors to this page: Johannes Echterhoff
Thomas Lankester
.

Page last modified on Wednesday 18 of November 2009 10:41:49 CET by Johannes Echterhoff.

Category: HMA