i. Abstract
The Web Feature Service (WFS) represents a change in the way geographic information is created, modified and exchanged on the Internet. Rather than sharing geographic information at the file level using File Transfer Protocol (FTP), for example, the WFS offers direct fine-grained access to geographic information at the feature and feature property level.
This International Standard specifies discovery operations, query operations, locking operations, transaction operations and operations to manage stored, parameterized query expressions.
Discovery operations allow the service to be interrogated to determine its capabilities and to retrieve the application schema that defines the feature types that the service offers.
Query operations allow features or values of feature properties to be retrieved from the underlying data store based upon constraints, defined by the client, on feature properties.
Locking operations allow exclusive access to features for the purpose of modifying or deleting features.
Transaction operations allow features to be created, changed, replaced and deleted from the underlying data store.
Stored query operations allow clients to create, drop, list and described parameterized query expressions that are stored by the server and can be repeatedly invoked using different parameter values.
This International Standard defines eleven operations:
- GetCapabilities (discovery operation)
- DescribeFeatureType (discovery operation)
- GetPropertyValue (query operation)
- GetFeature (query operation)
- GetFeatureWithLock (query & locking operation)
- LockFeature (locking operation)
- Transaction (transaction operation)
- CreateStoredQuery (stored query operation)
- DropStoredQuery (stored query operation)
- ListStoredQueries (stored query operation)
- DescribeStoredQueries (stored query operation)
In the taxonomy of services defined in ISO 19119, the WFS is primarily a feature access service but also includes elements of a feature type service, a coordinate conversion/transformation service and geographic format conversion service.
ii. Keywords
The following are keywords to be used by search engines and document catalogues.
ogcdoc, OGC document, web feature service, wfs, property, geographic information, resource, geography markup language, GML, Transaction, GetFeature, GetCapabilities, stored query, XML, KVP, encoding, Schema, HTTP, GET, POST, SOAP, request, response, capabilities document, filter encoding, constraint
iii. Preface
Attention is drawn to the possibility that some of the elements of this document may be the subject of patent rights. The Open Geospatial Consortium shall not be held responsible for identifying any or all such patent rights.
Recipients of this document are requested to submit, with their comments, notification of any relevant patent claims or other intellectual property rights of which they may be aware that might be infringed by any implementation of the standard set forth in this document, and to provide supporting documentation.
iv. Submitting organizations
The following organizations submitted this Document to the Open Geospatial Consortium (OGC):
- Bently Systems Inc.
- COMSOFT GmbH
- CSIRO
- CubeWerx Inc.
- Galdos Systems, Inc.
- GEOMATYS
- Institut National de l'information geographique et forestiere (IGN)
- Interactive Instruments GmbH
- Oracle Corporation
- The Carbon Project
- US National Geospatial-Intelligence Agency (NGA)
v. Submitters
All questions regarding this submission should be directed to the editor or the submitters:
Name | Representing | OGC member |
---|---|---|
Darko Androsevic |
Galdos Systems |
Yes |
Stefan Apfel |
Bentley Systems |
Yes |
Ben Caradoc-Davies |
CSIRO |
Yes |
Simon Cox |
CSIRO |
Yes |
John Herring |
Oracle |
Yes |
Frederic Houbie |
GEOMATYS |
Yes |
Baris Kazar |
Oracle |
Yes |
Clemens Portele |
Interactive Instruments GmbH |
Yes |
Dimitri Sarafinof |
IGN |
Yes |
Timo Thomas |
Individual |
Yes |
Josh Vote |
CSIRO |
Yes |
Panagiotis (Peter) A. Vretanos |
CubeWerx Inc. |
Yes |
vi. OGC 09-025r2 (based on OGC 09-025r1 and ISO 19142)
Warning
This document is not an ISO International Standard. It is distributed for review and comment. It is subject to change without notice and may not be referred to as an International Standard.
Recipients of this draft are invited to submit, with their comments, notification of any relevant patent rights of which they are aware and to provide supporting documentation.
vii. OGC Change Requests processed in this corrigendum
CR 342 [14-011]:- [WFS/FES SWG]WFS 2.0, GetFeatureById, exception codes and HTTP status codes
CR 160 [11-083]: Incorrect element referenced in clause 7.6.2.6
CR 159 [11-082] Inconsistent default value for startIndex parameter
CR 187 [11-153] Default value for the count parameter is not clear.
CR 236 [12-113] Inconsistent description of resolveDepth parameter
CR 261: [12-172]: Allow fes:expression as second parameter for DistanceBufferType and BBOXType
CR 303 [13-048r1]: WFS support for non-CRS srsName and multiple dimension geometries
CR 188 [11-152]: Allow use of http URIs to identify CRS
viii. Foreword
OGC Declaration
Attention is drawn to the possibility that some of the elements of this document may be the subject of patent rights. The Open Geospatial Consortium Inc. shall not be held responsible for identifying any or all such patent rights.
Recipients of this document are requested to submit, with their comments, notification of any relevant patent claims or other intellectual property rights of which they may be aware that might be infringed by any implementation of the standard set forth in this document, and to provide supporting documentation.
ISO Declaration:
ISO (the International Organization for Standardization) is a worldwide federation of national standards bodies (ISO member bodies). The work of preparing International Standards is normally carried out through ISO technical committees. Each member body interested in a subject for which a technical committee has been established has the right to be represented on that committee. International organizations, governmental and non-governmental, in liaison with ISO, also take part in the work. ISO collaborates closely with the International Electrotechnical Commission (IEC) on all matters of electrotechnical standardization.
International Standards are drafted in accordance with the rules given in the ISO/IEC Directives, Part 2.
The main task of technical committees is to prepare International Standards. Draft International Standards adopted by the technical committees are circulated to the member bodies for voting. Publication as an International Standard requires approval by at least 75 % of the member bodies casting a vote.
Attention is drawn to the possibility that some of the elements of this document may be the subject of patent rights. ISO shall not be held responsible for identifying any or all such patent rights.
ISO 19142 was prepared by Technical Committee ISO/TC 211, Geographic Information/Geomatics, in collaboration with the Open Geospatial Consortium, Inc. (OGC). The Web Feature Service (WFS) was originated within OGC.
ix. Introduction
The Web Feature Service (WFS) represents a change in the way geographic information is created, modified and exchanged on the Internet. Rather than sharing geographic information at the file level using File Transfer Protocol (FTP), for example, the WFS offers direct fine-grained access to geographic information at the feature and feature property level. Web feature services allow clients to only retrieve or modify the data they are seeking, rather than retrieving a file that contains the data they are seeking and possibly much more. That data can then be used for a wide variety of purposes, including purposes other than their producers’ intended ones.
In the taxonomy of services defined in ISO 19119, the WFS is primarily a feature access service but also includes elements of a feature type service, a coordinate conversion/transformation service and geographic format conversion service.
Geographic information — Web feature service
1. Scope
This International Standard specifies the behaviour of a service that provides transactions on and access to geographic features in a manner independent of the underlying data store. It specifies discovery operations, query operations, locking operations, transaction operations and operations to manage stored parameterized query expressions.
Discovery operations allow the service to be interrogated to determine its capabilities and to retrieve the application schema that defines the feature types that the service offers.
Query operations allow features or values of feature properties to be retrieved from the underlying data store based upon constraints, defined by the client, on feature properties.
Locking operations allow exclusive access to features for the purpose of modifying or deleting features.
Transaction operations allow features to be created, changed, replaced and deleted from the underlying data store.
Stored query operations allow clients to create, drop, list and described parameterized query expressions that are stored by the server and can be repeatedly invoked using different parameter values.
NOTE This International Standard does not address the access control issues.
This International Standard defines eleven operations:
- GetCapabilities (discovery operation)
- DescribeFeatureType (discovery operation)
- GetPropertyValue (query operation)
- GetFeature (query operation)
- GetFeatureWithLock (query & locking operation)
- LockFeature (locking operation)
- Transaction (transaction operation)
- CreateStoredQuery (stored query operation)
- DropStoredQuery (stored query operation)
- ListStoredQueries (stored query operation)
- DescribeStoredQueries (stored query operation)
2. Conformance
Table 1 specifies the conformance classes defined by this International Standard and the tests specified in Annex A that shall be satisfied in order to comply with each class. The only mandatory class, that all implementation of this standard must provide is the "Simple WFS" class. All other classes are optional.
Table 1 also lists:
a) Which, if any, filter encoding (see ISO 19143OGC 09-026r2 with Corrigendum, Clause 2) conformance tests need to be satisfied with each WFS conformance class.
b) Which, if any, GML (see ISO 19136:2007) conformance tests need to be satisfied with each WFS conformance class.
Conformance class name | Operation or behaviour | WFS Conformance Test | FES Conformance Test(s) | GML Conformance Test(s) |
---|---|---|---|---|
Simple WFS |
The server shall implement the following operations: GetCapabilities, DescribeFeatureType, ListStoredQueries, DescribeStoredQueries, GetFeature operation with only the StoredQuery action. One stored query, that fetches a feature using its id, shall be available but the server may also offer additional stored queries. Additionally the server shall conform to at least one of the HTTP GET, HTTP POST or SOAP conformance classes. |
A.1.1 |
OGC 09-026r2, A.1 |
ISO 19136:2007, A.1.1, A.1.4, A.1.5, A.1.7, B.3, B.5, B.2.3 |
Basic WFS |
The server shall implement the Simple WFS conformance class and shall additionally implement the GetFeature operation with the Query action and the GetPropertyValue operation. |
A.1.2 |
OGC 09-026r2, A.2, A.4. A.5, A.6, A.7, A.12, A.14 |
ISO 19136:2007, B.4 |
Transactional WFS |
The server shall implement the Basic WFS conformance class and shall also implement the Transaction operation. |
A.1.3 |
|
|
Locking WFS |
The server shall implement the Transactional WFS conformance class and shall implement at least one of the GetFeatureWithLock or LockFeature operations. |
A.1.4 |
|
|
HTTP GET |
The server shall implement the Key-value pair encoding for the operations that the server offers. |
A.1.5 |
|
|
HTTP POST |
The server shall implement the XML encoding for the operations that the server implements. |
A.1.6 |
|
|
SOAP |
The server shall implement XML encoded requests and results within SOAP Envelopes. |
A.1.7 |
|
|
Inheritance |
The server shall implement the schema-element() function for XPath expressions. |
A.1.8 |
OGC 09-026r2, A.15 |
|
Remote resolve |
The server shall implement the ability to resolve remote resource references. |
A.1.9 |
|
ISO 19136:2007, B.2.1 |
Response paging |
The server shall implement the ability to page through the set of response features or values. |
A.1.10 |
|
ISO 19136:2007, B.3 |
Standard joins |
The server shall implement join predicates using all Filter operators except the spatial and temporal operators. |
A.1.11 |
OGC 09-026r2, A.5, A.6 |
|
Spatial joins |
The server shall implement join predicates using spatial operators. |
A.1.12 |
OGC 09-026r2, A.7, A.8 |
|
Temporal joins |
The server shall implement join predicates using temporal operators. |
A.1.13 |
OGC 09-026r2, A.9, A.10 |
|
Feature versions |
The server shall implement the ability to navigate feature versions. |
A.1.14 |
OGC 09-026r2, A.11 |
|
Manage stored queries |
The server shall implement the CreateStoredQuery and the DropStoredQuery operations. |
A.1.15 |
OGC 09-026r2, A.1 |
|
3. Normative References
The following normative documents contain provisions, which, through reference in this text, constitute provisions of this document. For dated references, subsequence amendments to, or revisions of, any of these publications do not apply. For undated references, the latest edition of the normative document referred to applies.
- ISO/TS 19103:2005,
- Geographic information — Conceptual schema language
- ISO 19136:2007,
- Geographic information — Geography Markup Language (GML)
ISO 19143:2010OGC 09-026r2,- Geographic information — Filter Encoding with Corrigendum
- IETF RFC 2616,
- Hypertext Transfer Protocol – HTTP/1.1 (June 1999)
- IETF RFC 4646,
- Tags for Identifying Languages (September 2006)
- OGC 06-121r3,
- OGC Web Services Common Specification, OGC® Implementation Standard (9 February 2009)
- OGC 07-092r3,
- Definition identifier URNs in OGC namespace, OGC® Best Practices (15 January 2009)
- W3C SOAP,
- Simple Object Access Protocol (SOAP) 1.2, W3C Note (27 April 2007)
- W3C WSDL,
- Web Services Description Language (WSDL) 1.1, W3C Note (15 Mar 2001)
- W3C XML Namespaces,
- Namespaces in XML, W3C Recommendation (14 January 1999)
- W3C XML Path Language,
- XML Path Language (XPath) 2.0, W3C Recommendation (23 January 2007)
- W3C XML Schema Part 1,
- XML Schema Part 1: Structures, W3C Recommendation (2 May 2001)
- W3C XML Schema Part 2,
- XML Schema Part 2: Datatypes, W3C Recommendation (2 May 2001)
4. Terms and Definitions
For the purposes of this document, the following terms and definitions apply.
- 4.1 attribute <XML>
name-value pair contained in an element(4.6)
[ISO 19136:2007, definition 4.1.3]
NOTE In this document an attribute is an XML attribute unless otherwise specified.
- 4.2 client
-
software component that can invoke an operation (4.17) from a server(4.28)
[ISO 19128:2005, definition 4.1]
- 4.3 coordinate
-
one of a sequence of n numbers designating the position of a point in n-dimensional space
[ISO 19111:2007, definition 4.5]
- 4.4 coordinate reference system
-
coordinate system (4.5) that is related to an object by a datum
[ISO 19111:2007, definition 4.8]
- 4.5 coordinate system
-
set of mathematical rules for specifying how coordinates (4.3) are to be assigned to points
[ISO 19111:2007, definition 4.10]
- 4.6 element <XML>
-
basic information item of an XML document containing child elements, attributes (4.1) and character data
[ISO 19136:2007, definition 4.1.23]
- 4.7 feature
-
abstraction of real world phenomena
[ISO 19101:2002, definition 4.11]
NOTE A feature can occur as a type or an instance. The term "feature type" or "feature instance" should be used when only one is meant.
- 4.8 feature identifier
-
identifier that uniquely designates a feature (4.7) instance
- 4.9 filter expression
-
predicate expression encoded using XML
[
ISO 19143OGC 09-026r2, definition 4.11] - 4.10 interface
-
named set of operations (4.17) that characterize the behaviour of an entity
[ISO 19119:2005, definition 4.2]
- 4.11 join predicate
-
filter expression (4.9) that includes one or more clauses that constrain properties from two different entity types
[
ISO 19143OGC 09-026r2, definition 4.16]NOTE In this International Standard, the entity types will be feature (4.7) types.
- 4.12 join tuple
-
set of two or more object instances that satisfy a filter that includes join predicates (4.11)
NOTE In this International Standard, the object instances will be feature (4.7) instances.
- 4.13 local resource
-
resource that is under the direct control of a system
NOTE In this International Standard, the system is a web feature service and the resource is held in a data store that is directly controlled by that service.
- 4.14 locator attribute
-
attribute (4.1) whose values is a reference to a local resource (4.13) or remote resource(4.20)
NOTE In XML, this attribute is commonly called an href and contains a URI reference to the remote resource (see W3C XLink).
- 4.15 Multipurpose Internet Mail Extensions (MIME) type
-
media type and subtype of data in the body of a message that designates the native representation (canonical form) of such data
[IETF RFC 2045:1996]
- 4.16 namespace <XML>
-
collection of names, identified by a URI reference which are used in XML documents as element (4.6) names and attribute (4.1) names
[W3C XML Namespaces:1999]
- 4.17 operation
-
specification of a transformation or query that an object may be called to execute
[ISO 19119:2005, definition 4.3]
- 4.18 property
-
facet or attribute of an object, referenced by a name
[
ISO 19143:2010OGC 09-026r2, definition 4.21] - 4.19 resource
-
asset or means that fulfils a requirement
[
ISO 19143OGC 09-026r2, definition 4.23]NOTE In this International Standard, the resource is a feature (4.7), or any identifiable component of a feature (e.g. a property of a feature)
- 4.20 remote resource
-
resource that is not under direct control of a system
NOTE In this International Standard, the system is a web feature service. The resource is not held in any data store that is directly controlled by that service and thus cannot be directly retrieved by the service.
- 4.21 request
-
invocation of an operation (4.17) by a client(4.2)
[ISO 19128:2005, definition 4.10]
- 4.22 relocate
-
<reference> update a reference to a resource that has been moved or copied to a new location
EXAMPLE A server (4.28) is generating a response (4.24) to a GetFeature request(4.21), it has to copy a referenced feature (4.7) into the response document and the server has to "relocate" the original link contained in the referencing feature to the copy placed in the response document.
- 4.23 resolve
-
retrieval of a referenced resource and its insertion into a server-generated response document
NOTE The insertion may be accomplished by either replacing the reference in-line with a copy of the resource or by relocating the reference to point to a copy of the resource that has been placed in the response document.
- 4.24 response
-
result of an operation (4.17) returned from a server (4.28) to a client(4.2)
[ISO 19128:2005, definition 4.11]
- 4.25 response model
-
schema (4.26) defining the properties of each feature (4.7) type that can appear in the response (4.24) to a query operation(4.17)
NOTE This is the schema of feature types that a client (4.2) can obtain using the DescribeFeatureType operation (see Clause 9).
- 4.26 schema
-
formal description of a model
[ISO 19101:2002, definition 4.25]
NOTE In general, a schema is an abstract representation of an object’s characteristics and relations to other objects. An XML schema represents the relationship between the attributes (4.1) and elements (4.6) of an XML object (for example, a document or a portion of a document).
- 4.27 schema <XML Schema>
-
collection of schema (4.26) components within the same target namespace(4.16)
[ISO 19136:2007, definition 4.1.54]
EXAMPLE Schema components of W3C XML Schema are types, elements(4.16), attributes(4.1), groups, etc.
- 4.28 server
-
particular instance of a service(4.29)
[ISO 19128:2005, definition 4.12]
- 4.29 service
-
distinct part of the functionality that is provided by an entity through interfaces(4.10)
[ISO 19119:2005, definition 4.1]
- 4.30 service metadata
-
metadata describing the operations (4.17) and geographic information available at a server(4.28)
[ISO 19128:2005, definition 4.14]
- 4.31 traversal
-
<XML>
using or following an XLink link for any purpose
[W3C XLink:2001]
- 4.32 tuple
-
ordered list of values
[ISO 19136:2007, definition 4.1.63]
NOTE In this International Standard, the order list will generally be a finite sequence for features (4.7), each of a specific feature type.
- 4.33 Uniform Resource Identifier
-
unique identifier for a resource, structured in conformance with IETF RFC 2396
[ISO 19136:2007, definition 4.1.65]
NOTE The general syntax is <scheme>::<scheme-specified-part>. The hierarchical syntax with a namespace (4.16) is <scheme>://<authority><path>?<query>
5. Conventions
5.1 Abbreviated terms
- CGI
- Common Gateway Interface
- CRS
- Coordinate Reference System
- DCP
- Distributed Computing Platform
- EPSG
- European Petroleum Survey Group
- FES
- Filter Encoding Specification
- GML
- Geography Markup Language
- HTTP
- Hypertext Transfer Protocol
- HTTPS
- Secure Hypertext Transfer Protocol
- IETF
- Internet Engineering Task Force
- KVP
- Keyword-value pairs
- MIME
- Multipurpose Internet Mail Extensions
- OGC
- Open Geospatial Consortium
- OWS
- OGC Web Service
- SQL
- Structured Query Language
- SOAP
- Simple Object Access Protocol
- UML
- Unified Modelling Language
- URI
- Uniform Resource Identifier
- URL
- Uniform Resource Locator
- URN
- Uniform Resource Name
- VSP
- Vendor Specific Parameter
- WFS
- Web Feature Service
- WSDL
- Web Services Description Language
- XML
- Extensible Markup Language
5.2 Use of examples
This International Standard makes extensive use of XML examples. They are meant to illustrate the various aspects of a web feature service specified in this International Standard. The bulk of the examples can be found in Annex B with some examples embedded in the body of the specification. All examples reference fictitious servers and data. Thus, this International Standard does not assert that any XML or keyword-value pair encoded examples, copied from this International Standard, will necessarily execute correctly or validate using a particular XML validation tool.
5.3 XML schemas
Throughout this International Standard XML Schema (see W3C XML Schema Part 1, W3C XML Schema Part 2) fragments are used to define the XML encoding of WFS operations. These fragments are gathered into a single validated schema file in Annex C.
5.4 UML Notation
5.4.1 Class diagrams
Figure 1 describes the Unified Modelling Language (UML) notations used in this International Standard for UML class diagrams.
In these class diagrams, the following stereotypes of UML classes are used:
c) <<DataType>> A descriptor of a set of values that lack identity (independent existence and the possibility of side effects). A DataType is a class with no operations, whose primary purpose is to hold the information.
d) <<Enumeration>> A data type whose instances form a list of alternative literal values. Enumeration means a short list of well-understood potential values within a class.
e) <<CodeList>> A flexible enumeration for expressing a long list of potential alternative values. If the list alternatives are completely known, an enumeration shall be used; if the only likely alternatives are known, a code list shall be used.
f) <<Interface>> A definition of a set of operations that is supported by objects having this interface. An Interface class cannot contain any attributes.
g) <<Type>> A stereotyped class used for specification of a domain of instances (objects), together with the operations applicable to the objects. A Type class may have attributes and associations.
h) <<Union>> A list of alternate attributes where only one of those attributes may be present at any time.
See also ISO/TS 19103:2005, 6.8.2 and D.8.3.
In this International Standard, the following standard data types are used:
a) CharacterString – A sequence of characters
b) LocalisedCharacterString – A CharacterString associated with a locale
c) Boolean – A value specifying TRUE or FALSE
d) URI – An identifier of a resource that provides more information
e) Integer – An integer number
5.4.2 State machine notation
The approach to dynamic modelling used is that described by the UML Reference Manual. The main technique is the state machine view. A summary of the UML notation for state diagrams is shown in Figure 2.
6. Basic service elements
6.1 Introduction
This clause describes aspects of a Web Feature Service’s behaviour that are independent of particular operations or are common to several operations or interfaces.
6.2 Version numbering and negotiation
6.2.1 Version number form and value
Version numbers shall be encoded as described in 7.3.1 of OGC 06-121r3. Implementations of this International Standard shall use the value "2.0.02.0.2" as the protocol version number.
6.2.2 Appearance in service metadata and in requests
A web feature server that conforms to this International Standard shall list the version "2.0.02.0.2" in its service metadata (see 8.3). A server may support several versions whose values clients can discover according to a set of version negotiation rules (see OGC 06-121r3, 7.3.2).
The version number used in requests to a server shall be equal to a version number that the server has declared it supports (except during negotiation as described in 6.2.3). If the server receives a request with a version number that it does not support, the server shall raise an InvalidParameterValue exception (see 7.5).
The version number 2.0.02.0.2 shall be specified for any request that conforms to this International Standard.
6.2.3 Version number negotiation
All WFS implementations shall support version negotiation according to the rules described in OGC 06-121r3:2009, 7.3.2.
6.2.4 Request encoding
This International Standard defines two methods of encoding WFS requests. The first uses XML as the encoding language. The second encoding uses keyword-value pairs (KVP) to encode the various parameters of a request.
EXAMPLE An example of a keyword-value pair is "REQUEST=GetCapabilities" where "REQUEST" is the keyword and "GetCapabilities" is the value.
The KVP encoding is a subset of the XML encoding since KVP encoding is not amenable for encoding certain WFS operations, such as the Transaction operation. In both cases, the response to a request or exception reporting shall be identical.
Table 2 correlates WFS operations and their encoding semantics as defined in this International Standard.
Operation | Request Encoding |
---|---|
GetCapabilities |
XML & KVP |
DescribeFeatureType |
XML & KVP |
GetPropertyValue |
XML & KVP |
GetFeature |
XML & KVP |
GetFeatureWithLock |
XML & KVP |
LockFeature |
XML & KVP |
Transaction |
XML |
CreateStoredQuery |
XML |
DropStoredQuery |
XML & KVP |
ListStoredQueries |
XML & KVP |
DescribeStoredQueries |
XML & KVP |
6.2.5 KVP parameter encoding rules
6.2.5.1 Introduction
Aspects of KVP encoding WFS requests are described in 6.2.5.2 and 6.2.5.3.
6.2.5.2 Parameter ordering and case
Parameter names shall not be case sensitive, but parameter values shall be case sensitive. In this International Standard, parameter names used in KVP encoding are typically shown in uppercase for typographical clarity, not as a requirement.
Parameters in a request may be specified in any order.
A web feature service shall be prepared to encounter parameters that are not part of this International Standard. In terms of producing results per this International Standard, a web feature service shall ignore such parameters.
6.2.5.3 Parameter lists
Parameters consisting of lists shall be encoded as described in OGC 09-026r2, 5.5.
EXAMPLE In the case where multiple join queries (see 7.9.2.5.3) are KVP-encoded, parentheses are used to isolate the various parameters so that their values align correctly. This is illustrated by the following example:
TYPENAMES=(ns1:F1,ns2:F2)(ns1:F1,ns1:F1)&ALIASES=(A,B)(C,D)&FILTER=(<Filter>
… for A,B … </Filter>)(<Filter>…for C,D…</Filter>)
This KVP-encoded fragment encodes two join queries. The first query joins the feature types "ns1:F1" and "ns2:F2" which have been aliased to "A" and "B". The second query joins the feature types "ns1:F1" and "ns1:F1" (a self-join) which have been aliased to "C" and "D". The FILTER parameter encodes two filters, one for each query, delimited with parentheses. All the parameter values align 1:1. This fragment is equivalent to the following two individual KVP-encoded fragments:
TYPENAMES=ns1:F1,ns2:F2&ALIASES=A,B&FILTER=<Filter>…for A,B…</Filter>
TYPENAMES=ns1:F1,ns1:F1&ALIASES=C,D&FILTER=<Filter>…for C,D…</Filter>
6.3 Namespaces
Namespaces (see W3C XML Namespaces) are used to discriminate XML vocabularies from one another. For the WFS there are four normative namespace definitions, namely:
- (http://www.opengis.net/wfs/2.0) - for the WFS interface vocabulary
- (http://www.opengis.net/gml/3.2) - for the GML vocabulary (see ISO 19136:2007)
- (http://www.opengis.net/fes/2.0) - for the OGC Filter vocabulary (see OGC 09-026r2, 5.4)
- (http://www.opengis.net/ows/1.1) - for the OWS Common vocabulary (see OGC 06-121r3)
In addition, WFS implementations may make use of one or more GML Application Schemas and these schemas will, in turn, use one or more application namespaces (e.g. http://www.someserver.example.com/myns). While many of the examples in this International Standard use a single namespace, multiple namespaces may be used, as shown in 11.3.3.
For XML-encoded requests, the namespaces used in the request shall be encoded using the notation "xmlns:prefix=namespace_uri" in the root element of the request (see W3C XML Namespaces).
For KVP-encoded requests, the NAMEPSPACES parameter (see 7.6.6) shall be used to declare any namespaces used in the request.
6.4 Service bindings
The main body of this International Standard defines the encoding of WFS request and response messages, independent of any particular communication protocol. However, implementations of this International Standard shall support one of HTTP GET, HTTP POST or SOAP over HTTP POST (see Clause 2). Annex D contains a detailed discussion of these service bindings.
7. Common elements
7.1 Encoding of features
Servers that conform to this International Standard shall operate upon features encoded using GML. The version of GML that shall be supported is ISO 19136:2007. However the operations in this International Standard are defined in a manner that allows them to work with pervious and future versions of GML. So, servers may implement support for additional versions of GML, other than ISO 19136:2007. Servers shall advertise all supported versions of GML in their capabilities document using the inputFormat and outputFormat parameter domains (see Table 12).
Servers may also support additional non-GML feature encodings that shall also be listed in the servers capabilities document (see Table 12). However, this International Standard does not describe how a server would operate upon such encodings.
7.2 Resource Identifiers
7.2.1 Assigning resource identifiers
Each feature instance in a WFS shall be assigned a persistent unique resource identifier which is assigned by the server when the feature is created.
This identifier shall be invariant under all WFS operations including delete which means that a resource identifier cannot be reused once it has been assigned.
Resource identifiers are not intended to associate WFS resources with real world objects and the values do not have to be meaningful outside the scope of a web feature service instance.
7.2.2 Encoding resource identifiers
For features encoded using GML, the resource identifier shall be encoded in the XML attribute gml:id. This International Standard does not describe how resource identifiers are encoded for other output formats.
Within filter expressions, specific feature instances can be identified using the fes:ResourceId element. If the server supports versioning, specific versions of a feature can be referenced using the versionAction attribute contained within an fes:ResourceId element (see OGC 09-026r2, 7.11.2).
7.2.3 Version identification
If the server supports versioning of features, then the server shall maintain version information about each feature instance. This International Standard makes no assumptions about how that version information is maintained. Functions defined in the Filter Encoding Standard (see OGC 09-026r2, 7.11.2) allow version navigation based on the resource identifier.
7.3 Property references
7.3.1 XPath subset
GML allows features to have complex or aggregate non-geometric properties. A problem thus arises about how components of the complex value of such properties are referenced in the various places where value references are required (e.g. query and filter expressions). When the feature content that a WFS offers is encoded using XML, a WFS shall use XPath (see W3C XML Path Language) expressions for referencing the properties and components of the value of properties of a feature. The minimum mandatory subset of XPath that servers shall support is described in OGC 09-026r2, 7.4.4.
Supporting the schema-element() XPath function is optional. However, if the server conforms to the Inheritance conformance class (see Table 1) then the server shall also support the schema-element() function (see OGC 09-026r2, 7.4.4.).
7.3.2 Accessor function
In GML, a feature property may contain its value as content encoded inline or reference its value with a simple XLink (see ISO 19136:2007, 7.2.3). This means that in the course of evaluating an XPath expression, a server may need to resolve a resource reference. To accommodate this requirement, all WFS implementations shall provide a concrete implementation of an XPath accessor function called wfs:valueOf().
The argument to the function shall be the name of a property of a feature and the response shall be the value of the property. The value could simply be a text node or a list of element nodes that is the value of the named property.
The function shall resolve all locally referenced resources and if the server advertises in its capabilities document that it can resolve remote references (see Table 13), the function shall resolve all remote resource references as well. In the event that the server only supports locally referenced resources, and it encounters a remotely referenced resource, the server shall raise an OptionNotSupported exception (see OGC 06-121r3:2009, Table 25).
When to use the valueOf() function in an XPath expression can be determined by inspecting the application schema of the server. If a property is declared so as to allow value references (see ISO 19136:2007, 7.2.3.3, 7.2.3.7) then the wfs:valueOf() function should be specified in an XPath expression (see B.2.2, B.4.5).
7.4 Predicate expression encoding
A number of operations defined in this International Standard, contain predicate expressions that identify a subset of features to be operated upon. Such predicate expressions may enumerate a specific set of features to operate on or a set of features may be defined by specifying constraints on the properties and/or components of the value of properties of a feature type.
XML-encoded predicate expressions shall be encoded using the fes:Filter element as described in OGC 09-026r2, sub clause 7.2.
KVP-encoded predicate expressions shall be encoded using the parameters describes in OGC 09-026r2, Table 2.
The specific set of predicates that a web feature service implements shall be advertised in the server’s capabilities document using the filter capabilities section (see 8.3.3).
All implementations of this International Standard shall, at a minimum, implement the Query conformance class (see OGC 09-026r2, Table 1).
All implementations of this International Standard that implement the Basic WFS conformance class (see Table 1) shall also implement the Minimum Spatial Filter conformance class (see OGC 09-026r2, Table 1).
7.5 Exception reporting
In the event that a web feature service encounters an error while processing a request or receives an invalid request, it shall generate an XML document indicating that an error has occurred. The format of the XML error response is specified by, and shall validate against, the exception response schema defined in Clause 8 of the OWS Common Implementation Specification (see OGC 06-121r3:2009).
An ows:ExceptionReport element may contain one or more WFS processing exceptions specified using the ows:Exception element. The mandatory version attribute is used to indicate the version of the service exception report schema. This value shall be "2.0.02.0.2". The optional language attribute may be used to indicate the language used. The code list for the language parameter is defined in IETF RFC 4646.
Individual exception messages are contained within the ows:ExceptionText element. The mandatory code attribute shall be used to associate an exception code with the accompanying message.
The optional locator attribute may be used to indicate where an exception was encountered in the request that generated the error. Table 3 indicates what value the locator parameter should have for each exception code.
exceptionCode values | Meaning of code | "locator" value | Conformance Class |
---|---|---|---|
CannotLockAllFeatures |
A locking request with a lockAction of ALL failed to lock all the requested features. |
If the operation includes the optional "handle" parameter, report its value as the value of the "location" parameter. |
Locking WFS |
DuplicateStoredQueryIdValue |
The identifier specified for a stored query expression is a duplicate. |
The "locator" parameter shall contain the value of the duplicate identifier. |
Manage stored queries |
DuplicateStoredQueryParameterName |
This specified name for a stored query parameter is already being used within the same stored query definition. |
The "locator" parameter shall list the name of the duplicate stored query parameter. |
Manage stored queries |
FeaturesNotLocked |
For servers that do not support automatic data locking (see 15.2.3.1), this exception indicates that a transaction operation is modifying features that have not previously been locked using a LockFeature (see Clause 12) or GetFeatureWithLock (see Clause 13) operation. |
If the operation includes the optional "handle" parameter report its value as the value of the "location" parameter. |
Locking WFS |
InvalidLockId |
The value of the lockId parameter on a Transaction operation is invalid because it was not generated by the server. |
The "locator" parameter shall contain the value of the invalid lockId. |
Locking WFS |
InvalidValue |
A Transaction (see Clause 15) has attempted to insert or change the value of a data component in a way that violates the schema of the feature. |
The "locator" parameter shall contain the name of the property being incorrectly modified. |
Transactional WFS |
LockHasExpired |
The specified lock identifier on a Transaction or LockFeature operation has expired and is no longer valid. |
The "locator" parameter shall contain the value of the expired lock identifier. |
Locking WFS |
OperationParsingFailed |
The request is badly formed and failed to be parsed by the server. |
The "locator" parameter shall contain the value of the "handle" parameter if one is available. Otherwise the "locator" parameter shall contain the name of the badly formed operation. |
All (see Table 1) |
OperationProcessingFailed |
An error was encountered while processing the operation. |
The "locator" parameter shall contain the value of the "handle" parameter if one is available. Otherwise the "locator" parameter shall contain the name of the operation that failed. |
All (see Table 1) |
ResponseCacheExpired |
The response cache used to support paging has expired and the results are no longer available. |
If the operation includes the optional "handle" parameter, report its value as the value of the "locator" parameter. |
Response paging |
NotFound[1] |
The specified feature, identified using its feature identifier, was not found by the server. |
The "locator" parameter shall contain the value of the invalid identifier. |
Simple WFS |
Servers shall implement the generic exception codes in Table 25 of OGC 06-121r3:2009 for all conformance classes defined in this International Standard.
Note: The OperationNotSupported exception defined in Table 25 of OGC 06-121r3:2009 should only be raised if the operation being invoked is defined in this standard but is not implemented by the server. If the operation being invoked is not defined in this standard then the server should raise an InvalidParameterValue exception; in this case the locator parameter should contain the value "request" and the handle parameter should contain the name of the invalid operation.
Multiple exceptions may be reported in a single exception report so server implementations should endeavour to report as many exceptions as necessary to clearly describe a problem.
EXAMPLE If parsing an operation fails because the value of a parameter is invalid, the server should report an OperationParsingFailed exception and an InvalidParameterValue exception.
Annex B contains examples of exception reports.
7.6 Common request parameters
7.6.1 Introduction
Request parameters common to all or several operations defined in this International Standard are described in 7.6.2 to 7.6.6.
7.6.2 Base request type
7.6.2.1 Request Semantics
The base request type (see Figure 3) is an abstract type from which all WFS operations, except the GetCapabilities operation, are sub typed.
7.6.2.2 XML encoding
The following XML Schema fragment specifies the XML encoding of the type BaseRequest:
<xsd:complexType name="BaseRequestType" abstract="true">
<xsd:attribute name="service" type="xsd:string"
use="required" fixed="WFS"/>
<xsd:attribute name="version" type="xsd:wfs:stringVersionStringType"
use="required"fixed="2.0.0"/>
<xsd:attribute name="handle" type="xsd:string"/>
</xsd:complexType>
<xsd:simpleType name="VersionStringType">
<xsd:restriction base="xsd:string">
<xsd:pattern value="2\.0\.\d+"/>
</xsd:restriction>
</xsd:simpleType>
7.6.2.3 KVP encoding
Table 4 defines the KVP-encoding of the base request type.
The value of the mandatory REQUEST keyword shall indicate which service operation is being invoked.
NOTE XML-encoded requests do not have a REQUEST parameter because the name of the root element encodes the name of the service operation being invoked.
URLComponent | Operation | O/Ma | Description |
---|---|---|---|
SERVICE |
All operations. |
M |
See 7.6.2.4. |
VERSIONb |
All operations except GetCapabilities. |
M |
See 7.6.2.5. |
a O = Optional, M = Mandatory b VERSION is mandatory for all operations except the GetCapabilities operation. |
7.6.2.4 service parameter
In XML this parameter shall be encoded using an attribute named service (see 7.6.2.2).
In the KVP encoding, this parameter shall be encoded using the SERVICE keyword (see 7.6.2.3).
The mandatory service parameter shall be used to indicate which of the available service types, at a particular server, is being invoked. When invoking a web feature service, the value of the service parameter shall be "WFS".
7.6.2.5 version parameter
In XML this parameter shall be encoded using an attribute named version (see 7.6.2.2).
In KVP encoding this parameter shall be encoded using the VERSION keyword (see 7.6.2.3).
All WFS requests (except the GetCapabilities operation) shall include a parameter called version.
The version parameter shall be used to indicate to which version of the WFS specification the request encoding conforms and is used in version negotiation as described in 6.2.3. When encoding a WFS request in accordance with this International Standard, the value of the version attributed shall be fixed to 2.0.02.0.2, which corresponds to the version of this International Standard.
7.6.2.6 handle parameter
In XML this parameters shall be encoded using an attribute named handle (see 7.6.2.2).
This parameter is not defined for KVP encoding.
The handle parameter may optionally be specified on a request.
The purpose of the optional handle parameter is to allow a client application to associate a mnemonic name with a request for error handling purposes.
If a handle is specified for an operation and an exception is encountered (see 7.5) processing that operation, a Web Feature Service shall assign the value of the handle attribute to the locator attribute in the ows:Exception[2]Text element (see OGC 06-121r3:2009, Clause 8) in order to identify the operation or action that generated the exception. If a handle is not specified, the server may omit the locator attribute in the ows:ExceptionText element or may use some other means, such as line numbers, to locate the exception within the operation. The handle attribute is particularly useful when used with the Transaction operation (see Clause 15) which can contain many actions. Specifying a handle for each action allows the server to exactly locate an exception within a Transaction operation.
7.6.3 Standard presentation parameters
7.6.3.1 Parameter Semantics
Standard presentation parameters (see Figure 4) are used to control how query results are presented in a response document. These parameters may appear in the GetPropertyValue (see Clause 10), GetFeature (see Clause 11) and GetFeatureWithLock (see Clause 13) operations.
7.6.3.2 XML encoding
The following fragment defines the XML encoding to the standard presentation parameters:
<xsd:attributeGroup name="StandardPresentationParameters">
<xsd:attribute name="startIndex"
type="xsd:nonNegativeInteger" default="0"/>
<xsd:attribute name="count"
type="xsd:nonNegativeInteger"/>
<xsd:attribute name="resultType"
type="wfs:ResultTypeType" default="results"/>
<xsd:attribute name="outputFormat"
type="xsd:string" default="application/gml+xml; version=3.2"/>
</xsd:attributeGroup>
<xsd:simpleType name="ResultTypeType">
<xsd:restriction base="xsd:string">
<xsd:enumeration value="results"/>
<xsd:enumeration value="hits"/>
</xsd:restriction>
</xsd:simpleType>
7.6.3.3 KVP encoding
Table 5 defines the KVP encoding of the standard presentation parameters.
URLComponent | Operation | O/Ma | Default | Description |
---|---|---|---|---|
STARTINDEX |
GetPropertyValue, GetFeature, GetFeatureWithLock |
O |
|
See 7.6.3.4. |
COUNT |
GetPropertyValue, GetFeature, GetFeatureWithLock |
O |
|
See 7.6.3.5. |
OUTPUTFORMAT |
DescribeFeatureType, GetPropertyValue, GetFeature, GetFeatureWithLock |
O |
application/gml+xml; version=3.2 |
See 7.6.3.7. |
RESULTTYPE |
GetPropertyValue, GetFeature, GetFeatureWithLock |
O |
results |
See 7.6.3.6. |
a O = Optional, M = Mandatory |
7.6.3.4 startIndex parameter
For XML-encoded requests this parameter shall be encoded using an attribute named startIndex (see 7.6.3.2).
For KVP-encoded requests this parameter shall be encoded using the STARTINDEX keyword (see 7.6.3.3).
The optional startIndex parameter indicates the index within the result set from which the server shall begin presenting results in the response document.
7.6.3.5 count parameter
For XML-encoded requests this parameter shall be encoded using an attribute named count (see 7.6.3.2).
For KVP-encoded requests this parameter shall be encoded using the COUNT keyword (see 7.6.3.3).
The optional count parameter limits the number of explicitly requested values (i.e. features or property values) that are presented in a response document.
Only values of the types explicitly requested as the value of the typeNames parameter (see 7.9.2.4.1) shall be counted in the tally. Nested values contained within the explicitly requested value types shall not be counted.
EXAMPLE The tally of features in the following XML fragment is 4. The embedded reference to the feature with gml:id="2" and the feature with gml:id="5", which is that value abc:Prop4, are not included in the tally.
<?xml version="1.0"?>
<wfs:FeatureCollection
timeStamp="2010-08-01T22:47:02"
numberMatched="4" numberReturned="4"
xmlns:myns="http://www.someserver.example.com/myns"
xmlns:wfs="http://www.opengis.net/wfs/2.0"
xmlns:gml="http://www.opengis.net/gml/3.2"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.someserver.example.com/myns ./myns.xsd
http://www.opengis.net/wfs/2.0
http://schemas.opengis.net/wfs/2.0.0/2.0/wfs.xsd
http://www.opengis.net/gml/3.2
http://schemas.opengis.net/gml/3.2.1/gml.xsd">
<wfs:member>
<myns:Feature gml:id="1">
…
</myns:Feature>
</wfs:member>
<wfs:member>
<myns:Feature gml:id="2">
…
</myns:Feature>
</wfs:member>
<wfs:member>
<myns:Feature gml:id="3">
…
</myns:Feature>
</wfs:member>
<wfs:member>
<myns:Feature gml:id="4">
<myns:Property1> … <myns:Property1>
<myns:Property2> … <myns:Property2>
<myns:Property3 xlink:href="#2"/>
<myns:Property4>
<myns:Feature gml:id="5">
…
</myns:Feature>
</myns:Property4>
</myns:Feature>
</wfs:member>
</wfs:FeatureCollection>
In the case of a join query (see 7.9.2.5.3.1), each tuple of explicitly requested value types shall be counted as one in the tally. Nested value members contained within any of the explicitly requested value types of the tuple do not count.
The count value applies to the entire result set (i.e. the result set generated by processing one or more Query actions) and the constraint shall be applied to the values in the order in which they are presented. Once the count limit is reached, request processing may terminate and the response document, containing at most count values, shall be presented to the client.
There is no predefined default value defined for the count parameter and the absence of the parameter shall mean that all values in the result set shall be presented to the client subject to any server a[5] configured limits. If the server does have a server configured count limit, that limit shall be advertised in the server’s capabilities document using the CountDefault constraint (see Table 14).
7.6.3.6 resultType parameter
For XML-encoded requests this parameter shall be encoded using an attribute named resultType (see 7.6.3.2).
For KVP-encoded requests this parameter shall be encoded using the RESULTTYPE keyword (see 7.6.3.3).
A WFS can respond to a query operation in one of two ways (excluding an exception response). It may either generate a complete response document containing resources that satisfy the operation or it may simply generate an empty response container that indicates the count of the total number of resources that the operation would return. Which of these two responses a WFS generates is determined by the value of the optional resultType parameter.
The possible values for this parameter are "results" and "hits".
If the value of the resultType parameter is set to "results" the server shall generate a complete response document containing resources that satisfy the operation. The root element of the response container shall include a count of the number of resources actually presented in the response document (see 7.7.4.3). The root element of the response container shall also include a count of the total number of resources that the operations actually found which will always be equal to or greater than the number of resource presented in the response document (see 7.7.4.2).
If the value of the resultType attribute is set to "hits" the server shall generate an empty response document containing no resource instances and the root element of the response container shall contain the count of the total number of resources that the operation found (see 7.7.4.2). The value for the number of resources presented in the response document (see 7.7.4.3) shall be set to zero.
7.6.3.7 outputFormat parameter
For XML-encoded requests this parameter shall be encoded using an attribute named outputFormat (see 7.6.3.2).
For KVP-encoded requests this parameter shall be encoded using the OUTPUTFORMAT keyword (see 7.6.3.3).
The optional outputFormat parameter specifies the format used to encode resources in the response to a query operation. The default value is "application/gml+xml; version=3.2" indicating that resources in the response document shall be encoded using GML (see ISO 19136:2007).
Every WFS that conforms to this International Standard shall support this default value.
A server may advertise additional values for the outputFormat parameter in its capabilities document (see 8.3.3) indicating that multiple output formats, including previous versions of GML, are supported. However, This International Standard does not assign any specific meaning to these additional values. In cases where additional outputFormat values are specified in the server’s capabilities document, this International Standard recommends that a descriptive narrative be included for each value listed.
7.6.4 Standard resolve parameters
7.6.4.1 Parameter Semantics
Servers that conform to this International Standard shall implement the ability to resolve local resource references.
Servers may optionally implement the ability to, upon request, resolve remote resource references and shall advertise this ability using the ImplementsRemoteResolve constraint in their capabilities document (see Table 13).
How resource references are handled by a server is controlled by the resolve, resolveDepth and resolveTimeout parameters as described in 7.6.4.2 to 7.6.4.7.
The standard resolve parameters (see Figure 5) may appear in the GetPropertyValue (see Clause 10), GetFeature (see Clause 11) and GetFeatureWithLock (see Clause 13) operations.
7.6.4.2 XML encoding
The following fragment defines the XML encoding for the set of standard resolve parameters:
<xsd:attributeGroup name="StandardResolveParameters">
<xsd:attribute name="resolve"
type="wfs:ResolveValueType" default="none"/>
<xsd:attribute name="resolveDepth"
type="wfs:positiveIntegerWithStar" default="*"/>
<xsd:attribute name="resolveTimeout"
type="xsd:positiveInteger" default="300"/>
</xsd:attributeGroup>
<xsd:simpleType name="ResolveValueType">
<xsd:restriction base="xsd:string">
<xsd:enumeration value="local"/>
<xsd:enumeration value="remote"/>
<xsd:enumeration value="all"/>
<xsd:enumeration value="none"/>
</xsd:restriction>
</xsd:simpleType>
<xsd:simpleType name="positiveIntegerWithStar">
<xsd:union memberTypes="xsd:positiveInteger wfs:StarStringType"/>
</xsd:simpleType>
<xsd:simpleType name="StarStringType">
<xsd:restriction base="xsd:string">
<xsd:enumeration value="*"/>
</xsd:restriction>
</xsd:simpleType>
7.6.4.3 KVP encoding
Table 6 defines the KVP encoding of the standard resolve parameters.
URLComponent | Operation | O/Ma | Default | Description |
---|---|---|---|---|
RESOLVE |
GetPropertyValue, GetFeature, GetFeatureWithLock |
O |
None |
See 7.6.4.4. |
RESOLVEDEPTH |
GetPropertyValue, GetFeature, GetFeatureWithLock |
O |
* |
See 7.6.4.5. RESOLVE parameter shall have a value other than "none". |
RESOLVETIMEOUT |
GetPropertyValue, GetFeature, GetFeatureWithLock |
O |
Server Specific (see ResolveTimeoutDefault, Table 14) |
See 7.6.4.6. RESOLVE parameter shall have a value other than "none". |
a O = Optional, M = Mandatory |
7.6.4.4 resolve parameter
For XML-encoded requests this parameter shall be encoded using an attribute named resolve (see 7.6.4.2).
For KVP-encoded requests this parameter shall be encoded using the RESOLVE keyword (see 7.6.4.3).
The optional resolve parameter controls whether and which (i.e. local or remote) resource references are resolved by an operation.
The value domain of the resolve parameter is: "local", "remote", "all" or "none". Depending on which capabilities a server implements, it may support some or all of this value domain. Which resolve parameter values a server supports shall be advertised in the server’s capabilities document (see 8.3.3).
A resolve parameter value of "local" means that an operation shall only resolve local references.
A resolve parameter value of "remote" means that an operation shall only resolve remote resource references.
A resolve parameter value of "all" means that an operation shall resolve all resource references.
A resolve parameter value of "none" means that an operation shall not resolve any resource references. This is also the default value if the resolve parameter is not specified.
7.6.4.5 resolveDepth parameter
For XML-encoded requests this parameter shall be encoded using an attribute named resolveDepth (see 7.6.4.2).
For KVP-encoded requests this parameter shall be encoded using the RESOLVEDEPTH keyword (see 7.6.4.3).
The optional resolveDepth parameter indicates the depth to which nested resource references shall be resolved in a response document.
The range of valid values for this parameter consists of non-negativepositive[6] integers plus "*".
A value specified for the resolveDepth parameter shall only be used if the resolve parameter (see 7.6.4.4) is specified on the operation or action where the resolveDepth parameter appears and the value of the resolve parameter is not set to "none".
If a value is not specified for the resolve parameter or if the value of the resolve parameter is set to "none", the server shall ignore any value specified for the resolveDepth parameter.
If the value of the resolveDepth parameter is specified as "0" a server shall not resolve any resource references.[7]
If the value of the resolveDepth parameter is specified as "1", a server shall resolve the immediate resource references and include their value in the response document. However, if those resolved resources contain any nested resource references, those nested references shall not be resolved.
If the value of the resolveDepth parameter is specified as "*" a server shall resolve all immediate resource references and all nested resource references.
Having resolved references to the specified resolveDepth a server shall arrange that any deeper nested references shall be relocated to point to their intended resources.
EXAMPLE 1 This may require that references to local resources within the data store of a WFS be converted to remote reference back to the same server in a response document.
In the event that a circular reference is detected by the server before reaching the specified resolveDepth, the server shall abort further nested resource resolution and arrange for the last reference in the chain to reference the appropriate, already resolved, resource.
EXAMPLE 2 Consider the following chain of resource references: A -> B -> C -> D -> E -> B. If the resolveDepth values is set to 8, a server would resolve all resources to E (i.e. 4 levels) and then arrange for resource E to point to the already resolved resource B. At that point the server shall cease resource resolution since the remaining resources, to a depth of 8 levels, have already been resolved due to the circular reference.
7.6.4.6 resolveTimeout parameter
For XML-encoded requests the resolveTimeout parameter shall be encoded using an attribute named resolveTimeout (see 7.6.4.2).
For KVP-encoded requests the resolveTimeout parameter shall be encoding using the RESOLVETIMEOUT keyword (see 7.6.4.3).
The optional resolveTimeout parameter controls how long a server shall wait to receive a response when resolving resource references.
The resolveTimeout parameter is of type xsd:positiveInteger and specifies the expiry time in seconds. If the resolveTimeout parameter is not specified, the server wait time is implementation dependent and shall be advertised in the server’s capabilities document using the ResolveTimeoutDefault constraint (see Table 14).
A value specified for the resolveTimeout parameter shall only be used if the resolve parameter is specified on the request element that includes the resolveTimeout parameter and the value of the resolve parameter is not set to "none".
If the value of the resolve parameter is set to "none", the server shall ignore any value specified for the resolveTimeout parameter.
7.6.4.7 Unresolvable references
In the event that a server cannot resolve a resource reference, the server shall simply report the original unresolved URI in the response. This is not considered an exception.
7.6.5 Standard input parameters
7.6.5.1 Parameter Semantics
Standard input parameters (see Figure 6) are a set of parameters used to assert the encoding of resources upon input and the CRS of any geometric values those resources might contain.
These parameters can be specified on the Insert (see 15.2.4), Update (see 15.2.5) and Replace (see 15.2.6) actions of the Transaction operation (see Clause 15).
7.6.5.2 XML encoding
The following fragment defines the XML encoding for the standard input parameters.
<xsd:attributeGroup name="StandardInputParameters">
<xsd:attribute name="inputFormat" type="xsd:string"
default="application/gml+xml; version=3.2"/>
<xsd:attribute name="srsName" type="xsd:anyURI"/>
</xsd:attributeGroup>
7.6.5.3 KVP encoding
The standard input parameters are not defined for KVP-encoded requests because a KVP encoding is not defined for the Transaction operation (see Clause 15).
7.6.5.4 inputFormat parameter
For XML-encoded requests the inputFormat parameter shall be encoded using an attribute named inputFormat (see 7.6.5.2).
The inputFormat parameter is not defined for KVP encoded requests.
The inputFormat parameter may be used to assert the feature encoding used to express features upon input using the Insert action of the Transaction operation (see 15.2.4.1) or when features are updated using the Update (see 15.2.5.1) or Replace (see 15.2.6.1) actions.
For servers that implement the Transactional WFS conformance class (see Table 1), the default value of the inputFormat attribute shall be "application/gml+xml; version=3.2" indicating that input features are encoded using GML (see ISO 19136:2007).
A server may advertise additional values for the inputFormat parameter in its capabilities document (see 8.3) indicating that multiple input formats, including previous versions of GML, are supported. However, This International Standard does not assign any specific meaning to these additional values. In cases where additional inputFormat values are specified in the server’s capabilities document, this International Standard recommends that a descriptive narrative be included for each value listed.
7.6.5.5 srsName parameter
For XML-encoded requests the srsName parameter shall be encoded using an attribute named srsName (see 7.6.5.5).
The standard input parameter, srsName, is not defined for KVP encoded requests.
The srsName parameter may be specified as a parameter of the Transaction operation (see Clause 15) or as a parameter on the transaction actions Insert (see 15.2.4.1), Update (see 15.2.5.1) or Replace (see 15.2.6.1).
If specified as a parameter of the Transaction operation, the value of the srsName attribute shall assert the default CRS used to encode feature geometries within the Transaction (see 15.2.2).
If an srsName value is specified as a parameter of the Transaction actions Insert, Update or Replace its value shall supersede any CRS value specified using the srsName parameter on the Transaction operation.
The srsName (see ISO 19136:2007, 10.1.3.1) parameter may also be used to assert the CRS of an individual geometry and supersedes any previous CRS assertions.
If specified, the value of the srsName parameter shall be equivalent to the default CRS value specified using the wfs:DefaultCRS element in the capabilities document (see 8.3) or any of the wfs:OtherCRS values (see Table 11) for the relevant feature type.
If the specified CRS is not supported for the specified feature type, the WFS shall raise an InvalidParameterValue exception (see Table 3).
If the srsName parameter is not specified, the WFS shall interpret this to mean that geometries are encoded in the default CRS as specified using the wfs:DefaultCRS element in the capabilities document (see 8.3.3).
7.6.6 Additional common keywords for KVP-encoded requests
Table 7 defines additional keywords for KVP-encoded WFS requests.
URLComponent | Operation | O/Ma | Description |
---|---|---|---|
NAMESPACES |
All operations |
O |
Used to specify namespaces and their prefixes. The format shall be xmlns(prefix,escaped_url) where escaped_url is defined in (see OGC 06-121r3:2009, 11.3). If the prefix is not specified then the default namespace shall be assumed. More that one namespace may be bound by specifying a comma separated list of xmlns() values. This parameter is not defined for XML encoded requests because XML has another mechanism for asserting namespaces (see 6.3). |
VSPs |
|
O |
A server may implement additional KVP parameters that are not part of this International Standard. These are known as vendor-specific parameters. VSPs allow vendors to specify additional parameters that will enhance the results of requests. A server shall produce valid results even if the VSPs are missing, malformed or if VSPs are supplied that are not known to the server. Unknown VSPs shall be ignored. A server may choose not to advertise some or all of its VSPs. If VSPs are included in the Capabilities XML (see 8.3), the ows:ExtendedCapabilities element (see OGC 06-121r3:2009, 7.4.6) shall be extended accordingly. Additional schema documents may be imported containing the extension(s) of the ows:ExtendedCapabilities element. Any advertised VSP shall include or reference additional metadata describing its meaning (see 8.4). WFS implementers should choose VSP names with care to avoid clashes with WFS parameters defined in this International Standard. |
a O = Optional, M = Mandatory |
7.7 Standard response parameters
7.7.1 Parameter Semantics
Standard response parameters (see Figure 7) are response parameters used in the definition of the response collection for the GetPropertyValue (see Clause 10), GetFeature (see Clause 11) and GetFeatureWithLock (see Clause 13) operations.
7.7.2 XML encoding
The following XML Schema fragment defines the XML encoding of the standard response parameters:
<xsd:attributeGroup name="StandardResponseParameters">
<xsd:attribute name="timeStamp" type="xsd:dateTime" use="required"/>
<xsd:attribute name="numberMatched" type="xsd:nonNegativeIntegerOrUnknown" use="required"/>
<xsd:attribute name="numberReturned" type="xsd:nonNegativeInteger" use="required"/>
<xsd:attribute name="next" type="xsd:anyURI"/>
<xsd:attribute name="previous" type="xsd:anyURI"/>
</xsd:attributeGroup>
<xsd:simpleType name="nonNegativeIntegerOrUnknown">
<xsd:union>
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:enumeration value="unknown"/>
</xsd:restriction>
</xsd:simpleType>
<xsd:simpleType>
<xsd:restriction base="xsd:nonNegativeInteger"/>
</xsd:simpleType>
</xsd:union>
</xsd:simpleType>
7.7.3 KVP encoding
Only an XML encoding is defined for WFS response messages.
7.7.4 Parameter discussion
7.7.4.1 timeStamp parameter
The timeStamp parameter shall be used by a WFS to indicate the time and date when a response collection was generated.
7.7.4.2 numberMatched parameter
The numberMatched parameter shall be used in a response document to report the total number of features or values, of the types requested in an operation, that are in the result set. This value does not necessarily have to match the number of feature or values actually presented in the response document (see 7.7.4.3). If a server is unable to report the total number of matched features or values then it shall use the value "unknown" to indicate this.
By setting the value of the resultType parameter (see 7.6.3.6) to "hits" a count of the total number of features or values that an operation would return can be obtained without having to incur the cost of transmitting the result set. For servers that support response paging (see 7.7.4.4) the value of the next parameter shall be set to then fetch the first subset of response features or values.
7.7.4.3 numberReturned parameter
The numberReturned parameter shall be used to indicate a count of the number of features or values that are presented within a response document.
See 7.6.3.4 for value counting rules.
If a value is specified for the count parameter (see 7.6.3.5), the value of the numberReturned parameter shall be equal to or less than the specified value of the count parameter.
If the value of the count parameter is not explicitly specified in the operation, a default value may be configured and advertised in the server’s capabilities document (see 8.3) and shall have the same effect on numberReturned as if it were specified in the operation.
If the count parameter is not specified, either explicitly or through a server configuration, the value of the numberReturned response parameter shall be equal to the value of numberMatched response parameter.
7.7.4.4 Response paging
7.7.4.4.1 Introduction
Response paging is the ability of a client to scroll through a set of response features or values, N features or values at-a-time much like one scrolls through the response from a search engine one page at a time.
Servers that support response paging shall advertise this fact in their capabilities document using the ImplementsResultPaging constraint (see Table 13).
Response paging is accomplished using the previous and next parameters defined on the response collections (see 10.3.1, 11.3.1).
In order for paging to be triggered, either the count (see 7.6.3.5) parameter shall be set on the request or the server shall implement a default value for this parameter that shall be advertised in the server’s capabilities document (see Table 14).
The value of the previous or next attribute shall be server generated URIs that retrieves the corresponding set or results. The specific format of these URIs is implementation dependant as are the details of how or if the server caches the results of an operation in order to be able to present them to the client one subset at a time.
Upon resolving the previous or next URIs, servers shall either generate a valid response collection containing the next or previous set of features or values (or join tuples in the case of a join), or an exception message indicating that the result set is no longer available; perhaps because the client waited too long before following the previous or next links and the results have, in the meantime, been purged from the server’s cache. In this case, the server shall generate a ResponseCacheExpired exception (see Table 3).
Servers shall advertise how long result sets are cached for the purpose of response paging using the ResponseCacheTimeout constraint in their capabilities document (see Table 14).
EXAMPLE To illustrate the use of these parameters, consider the following GetFeature (see Clause 11) request:
<GetFeature service="WFS" version="2.0.02.0.2" count="100"
xmlns="http://www.opengis.net/wfs/2.0"
xmlns:cw="http://www.someserver.example.com/cw"
xmlns:fes="http://www.opengis.net/ogc/1.1"
xmlns:gml="http://www.opengis.net/gml/3.2">
<Query typeNames="cw:MyFeatureType"/>
</GetFeature>
The sequence of interactions with the server proceeds as follows:
a) A client sends the request to a server that supports paging.
b) The server responds with a wfs:FeatureCollection element containing the first 100 records in the result set. The next attribute is set so that the client can retrieve the next 100 features, but the previous attribute is not set since this is the first set of features in the response set.
c) The client traverses the next URI.
d) The server responds with another wfs:FeatureCollection element containing the next 100 features in the result set. In this case, the server sets both the previous and next attribute values so that the client can retrieve the previous 100 features or the next 100 features in the result set of the GetFeature request originally posted in (a).
e) The client continues to traverse each next URI, until a <wfs:FeatureCollection> response is received without the next attribute set. This indicates the last set of features , from the original request posted in (a), has been retrieved.
f) Similarly, a client can traverse the previous URI until a <wfs:FeatureCollection> response is received that does have the previous attribute set indicating the first set of 100 features has been retrieved.
7.7.4.4.2 Transactional consistency of response paging
7.7.4.4.2.1 Declaring transactional consistency
Servers, in their capabilities document, shall advertise whether they support transactional consistency for response paging using the PagingIsTransactionSafe constraint (see Table 14).
7.7.4.4.2.2 Response paging with transactional consistency
Servers that declare transactional consistency shall maintain transactional consistency between paging iterations. Thus, the view of the data that a client sees while paging through the response set shall be consistent with respect to the time that the originating request was executed.
7.7.4.4.2.3 Response paging without transactional consistency
Servers that do not declare transactional consistency shall not be required to maintain transactional consistency or state between paging iterations. Thus it is possible for new features to be added, updated or removed from the complete result set between iterations. As a consequence it is possible to have a result set element be skipped or duplicated between iterations.
7.8 Use of the schemaLocation attribute
Any GML document generated by a WFS shall reference an appropriate GML application schema document so that the output can be validated. This shall be accomplished using the schemaLocation attribute, as defined in the XML Schema specification (see W3C XML Schema Part 1).
EXAMPLE The following XML fragment shows the use of the schemaLocation attribute on the root element indicating the location of the an XML Schema document that can be used for validation:
<?xml version="1.0" ?>
<wfs:FeatureCollection
xmlns="http://www.someserver.example.com/myns"
xmlns:myns="http://www.someserver.example.com/myns"
xmlns:gml="http://www.opengis.net/gml/3.2"
xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance
xsi:schemaLocation="http://www.someserver.example.com/myns
http://www.someserver.example.com/wfs.cgi?request=DescribeFeatureType&typenames=TreesA_1M,RoadL_1M"> …
In this example, the service uses a DescribeFeatureType operation (see Clause 9) to call back to itself to reference a schema document where the TreesA_1M and RoadL_1M elements are declared.
7.9 Query expressions
7.9.1 Introduction
A query expression is an action that directs a server to search its data store for resources that satisfy some filter expression encoded within the query. Query expressions search for resources of a single type or they can join two or more resource types and thus search for tuples of resources.
In this International Standard, the queryable resources are features (see 7.1 and OGC 09-026r2, 6.3.3.1.1).
A query expression resolves to a set of features or feature tuples that satisfy its filter expression. The result set is, in turn, operated upon by some operation defined in this International Standard.
EXAMPLE The GetFeature operation (see Clause 11) uses a query expression to identify a subset of features to present to a client in a response document. Similarly, the LockFeature operation (see Clause 12) uses a query expression to identify a subset of features to lock.
This International Standard defines two types of query expressions; ad hoc query expressions and stored query expressions.
Ad hoc query expressions are encoded in XML using the element wfs:Query. They are called "ad hoc" because the query is not stored by the server and is only known at runtime.
Stored query expression are encoded in XML using the wfs:StoredQuery element. A stored query expressions is a query that has been previously saved in the server’s data store and can be executed at any time using the query’s identifier.
Both query expression types are derived from the abstract query expression elements defined in Clause 6 of OGC 09-026r2.
7.9.2 Ad hoc query expression
7.9.2.1 Request Semantics
An ad hoc query expression may be used in a GetPropertyValue (see Clause 10), GetFeature (see Clause 11), GetFeatureWithLock (see Clause 13) or LockFeature (see Clause 12) operation to identify the set of features to be operated upon.
As shown in Figure 8, an ad hoc query expression contains a typeNames parameter, projection clause, a selection clause and a sorting clause.
The mandatory typeNames parameter lists the name of one or more feature types to query.
The optional projection clause identifies a subset of optional feature properties that shall be presented in the result set. The projection clause for XML-encoded ad hoc query expressions may also be used to control, on a per-property basis, how resource references (see 7.6.4) are resolved in the response document.
NOTE How resource references are resolved in a response document can only be controlled at the operation level for KVP-encoded requests. This is accomplished using the RESOLVE, RESOLVEDEPTH and RESOLVETIMEOUT keywords (see 7.6.4.3). This is in contrast to XML-encoded requests where resource resolution can be controlled at the operation and property levels.
The optional selection clause specifies criteria that conditionally select features from a server’s data store.
The optional sorting clause specifies how the features in the response document should be ordered.
An ad hoc query also allows a CRS to be asserted and used when presenting feature geometries in a response document.
7.9.2.2 XML encoding
The following XML Schema fragment defines the XML encoding for an ad hoc query expression:
<xsd:element name="Query" type="wfs:QueryType"
substitutionGroup="fes:AbstractAdhocQueryExpression"/>
<xsd:complexType name="QueryType">
<xsd:complexContent>
<xsd:extension base="fes:AbstractAdhocQueryExpressionType">
<xsd:attribute name="srsName" type="xsd:anyURI"/>
<xsd:attribute name="featureVersion" type="xsd:string"/>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
The wfs:Query element includes the typeNames parameter inherited from the fes:AbstractAdhocQueryExpressionType type (see OGC 09-026r2, 6.3.2).
7.9.2.3 KVP encoding
Table 8 defines the KVP-encoding for ad hoc query expressions.
Table 8 includes parameters from 7.9.2.4 and OGC 09-026r2, Table 2, which are necessary to KVP-encode an ad hoc query expression.
URL Component | O/Ma | Description |
---|---|---|
TYPENAMES |
Mb |
See 7.9.2.4.1. |
ALIASES |
O |
See 7.9.2.4.3. |
SRSNAME |
O |
See 7.9.2.4.4. |
Projection clause |
O |
See Table 9. |
FILTER |
O |
See OGC 09-026r2, 6.3.3. |
FILTER_LANGUAGE |
O |
See OGC 09-026r2, 6.3.3. |
RESOURCEID |
O |
See OGC 09-026r2, 6.3.3. |
BBOXc |
O |
See OGC 06-121r3:2009, 10.2.3. |
SORTBY |
O |
See OGC 09-026r2, Clause 8 The SORTBY parameter is used to specify a list of property names whose values should be used to order (upon presentation) the set of feature instances that satisfy the query. The value of the SORTBY parameter shall have the form "PropertyName [ASC|DESC][,PropertyName [AASC|DESC],…]" where the letters ASC are used to indicate an ascending sort and the letters DESC are used to indicate a descending sort. If neither ASC nor DESC are specified, the default sort order shall be ascending. An example value might be: "SORTBY=Field1 DESC,Field2 DESC,Field3". In this case the results are sorted by Field 1 descending, Field2 descending and Field3 ascending |
a. O = Optional , M = Mandatory b. The TYPENAMES parameter is mandatory in all cases except when the RESOURCEID parameter is specified (see 7.9.2.4.1). c. The default CRS for a KVP-encoded BBOX operator shall be the DefaultCRS value specified in the server’s capabilities document (see Table 11 and 7.9.2.4.4.1)[9] |
If multiple KVP-encoded query expressions appear in a WFS request, the parameter values for each query expression shall be isolated from one another using parentheses (see 6.2.5.3). If an optional parameter is specified for one query expression, then a value shall be specified for that parameter for all query expressions encoded in the request.
Only one of a set of mutually exclusive parameters shall be specified in a KVP-encoded request that encodes multiple query expressions; for the chosen parameter, a value shall be specified for each encoded query expression.
EXAMPLE If a KVP-encoded request contains multiple query expressions and one of those query expressions uses the FILTER keyword to encode the predicate, then all the query expressions in the request must use the FILTER keyword. You cannot, for example, have a KVP-encoded request with multiple query expressions where one query uses the FILTER keyword to encode the predicate and another query expression uses the RESOURCEID keyword.
If used in a request, the BBOX keyword shall only encode a single bounding box (see 06-121r3:2009, 10.2.3). However, that bounding box predicate shall apply to all query expressions encoded in the request (see B.8.5.4). This is in contrast to the FILTER and RESOURCEID keywords which can encoding multiple predicates corresponding to each query expression encoded in a KVP-encoded request (see B.8.4.15).
As is the case for XML-encoded requests, multiple KVP-encoded query expressions encoded in a single WFS operation shall be considered independent of each other.
7.9.2.4 Parameter discussion
7.9.2.4.1 typeNames parameter
For XML-encoded ad hoc query expressions, the typeNames parameter shall be encoded using the typeNames attribute on the wfs:Query element. This attribute is inherited from the abstract element:
fes:AbstractAdhocQueryExpressionType (see OGC 09-026r2, 6.3.2).
For KVP-encoded ad hoc query expressions the typeNames parameter shall be encoded using the TYPENAMES keyword (see Table 8). The TYPENAMES parameter is mandatory in all cases except when the RESOURCEID parameter is specified. In this case the TYPENAMES parameter may be omitted because each feature instance can be identified by its resource identifier alone (see 7.2). If both the TYPENAMES and RESOURCEID parameters are specified then all the feature instances identified by the RESOURCEID parameter shall be of the type specified by the TYPENAMES parameter; otherwise the server shall raise an InvalidParameterValue exception (see OGC 06-121r3:2009, Table 25) where the "locator" attribute (see OGC 06-121r3:2009, 8.4) value shall be set to "RESOURCEID".
The typeNames parameter (see OGC 09-026r2, 6.3.3.1.1) shall be used within an ad hoc query expression to encode the names of one or more correlated feature types to be queried. Individual feature type names shall be encoded as QName (see W3C XML Schema Part 2).
The value of each QName listed as a value of the typeNames parameter shall match one of the feature type names advertised in the server’s capabilities document (see 8.3).
7.9.2.4.2 schema-element() function
If the list of values for the typeNames parameters contains a single name then the schema-element() function can be used to trigger a sequence of queries on the specified feature type and any feature type whose object elements are in the substitution group of the specified feature type.
EXAMPLE typeNames="schema-element(ns1:Vehicle)" might, along with ns1:Vehicle, query the feature types ns1:Cars, ns1:Boats, etc.
7.9.2.4.3 aliases parameter
For XML-encoded ad hoc query expressions the aliases parameter shall be encoded using the aliases attribute on the wfs:Query element. The aliases attribute is inherited from the abstract element:
fes:AbstractAdhocQueryExpressionType type (see OGC 09-026r2, 6.3.2).
For KVP-encoded ad hoc query expressions the aliases parameter shall be encoded using the ALIASES keyword.
The optional aliases parameter may be used within a query expression to specify a list of alternate names for the feature type names specified as the value of the typeNames parameter. A feature type alias may be used anywhere the feature type name may be used within the context of a query expression.
The number of list elements in the value of the aliases parameter shall match the number of corresponding feature type names in the value of the typeNames parameter and shall be correlated 1:1.
EXAMPLE 1
TYPENAMES=(ns1:FeatureType1,ns2:FeatureType2)(ns2:FeatureType2,ns2:FeatureType3)&ALIASES=(A,B)(C,D)
This KVP-encoded example encodes two ad hoc query expressions, each performing a join. The first expression is joining the feature types ns1:FeatureType1 and ns2:FeatureType2 which are aliased to A and B. The second expression is joining the feature type ns2:FeatureType2 and ns2:FeatureType3 which are aliased to C and D.
Each alias specified in the value of aliases parameter shall be unique within the context of a single query expression.
If the aliases parameter is used, an alias shall be specified for each feature type name listed as the value of typeNames parameter.
Aliases are typically used in query expressions that perform a join operation (see 7.9.2.5.3.1), to support self-joins. That is a join of one feature type back to itself.
EXAMPLE 2
typeNames="myns:Feat1 myns:Feat1" aliases="a b"
This XML-encoded example show the encoding of the typeName parameter. The first feature type, myns:Feat1, is aliased to the name "a" and the second feature type, myns:Feat1, is aliased to the name "b". Thus properties from the first instance of myns:Feat1 can be referenced in a request as "/a/property_name" and properties from the second instance of myns:Feat1 can be referenced in a request as "/b/property_name" where the token "property_name" is used as a place holder for the name of any property of the feature myns:Feat1.
7.9.2.4.4 srsName parameter
7.9.2.4.4.1 Description[10]
The optional srsName attribute may be used to assert a specific WFS-supported CRS transformation to be applied to the compatible (see 7.9.2.4.4.2) geometries of the features returned in a response document.
The value of the srsName parameter may be the wfs:DefaultCRS or any of the wfs:OtherCRS values listed for the feature type in a server’s capabilities document (see 8.3.3). If no srsName value is supplied, then the compatible feature geometries shall be encoded in the response document using the advertised wfs:DefaultCRS value.
This attribute has no meaning for feature types with no spatial properties and shall be ignored.
Servers that advertise more than one wfs:OtherCRS value in their capabilities document (see 8.3.3) shall be able to transform between the CRS used to store featuresgeometries and any compatible CRS requested using the srsName attribute.
Servers that implement this International Standard shall be able to process srsName attribute values using the following format model:
urn:ogc:def:objectType:authority:version:<EPSG code>(see OGC 07-092r2)
http://www.opengis.net/def/crs/[epsg|ogc]/0/{code}
In this format model, objectType shall have the value of "crs", authority shall have the value "crs" and the valuetoken "{code}"<EPSG Code>iis a placeholder for the actualEPSG crs code value as defined by the authority "epsg" or "ogc".
EXAMPLE srsName="urn:ogc:def:crs:EPSG::26986http://www.opengis.net/def/crs/epsg/0/26986".
The format model from the previous version of this standard:
urn:ogc:def:objectType:authority:version:<EPSG code> (see OGC 07-092r2)
where objectType shall have the value "crs", authorify shall have the value "EPSG" and the value <EPSG Code> is a placeholder for the actual EPSG code is still allowed but is deprecated[11].
7.9.2.4.4.2 Compatibility of coordinate reference systems
Coordinate reference systems that differ in dimensionality or that have no defined datum transformation between them may be incompatible for the purposes of geometry coordinate conversion. Where the request srsName references a CRS that is incompatible with the storage CRS of a geometry property, the service shall encode that geometry property using some other CRS identified with an srsName attribute on that property; there is no requirement that this srsName attribute be wfs:DefaultCRS or one of those listed in wfs:OtherCRS.
If a filter predicate compares two geometries with incompatible CRS, the server shall generate an InvalidParameterException.
EXAMPLE: A feature with both 2D and 3D geometry properties is requested with srsName set to a 2D CRS; the 2D property is encoded in the requested CRS, and the 3D property is encoded with some 3D CRS identified in the srsName of the geometry.
EXAMPLE: A 1D geometry property whose coordinate is the path length along a LineString (itself defined in 3D with some CRS) with gml:id="geom.123" in the same response is encoded with srsName="#geom.123".
EXAMPLE: A 1D geometry property whose coordinate is defined in an external resource is encoded with srsName set to an HTTP URI for that external resource.[12]
7.9.2.4.5 Projection clause
7.9.2.4.5.1 Request Semantics
Every feature representation generated by a WFS shall include all the mandatory properties for the feature type according to the schema description (see Clause 9), and then may include a selection of the other properties, according to the schema description.
If the optional projection clause is not specified on a query the server shall present all available mandatory and non-mandatory properties for each feature in the result set.
If the optional projection clause is specified on a query, and that projection clause only lists one or more non-mandatory properties, the server shall present all the mandatory properties and the specified subset of non-mandatory properties for each feature in the result set.
If the optional projection clause is specified on a query, and that projection clause only lists one or more mandatory properties, the server shall present all the mandatory properties and none of the non-mandatory properties for each feature in the result set.[13]
The projection clause enumerates which of the non-mandatory properties of a feature shall be included in the response to a query.
In the case where a feature property has a cardinality of n..m and that property is to be included in the response, then – unless otherwise specified – all instances or values of that property shall be presented for each feature in the result set.[14]
NOTE There is typically some flexibility in the structure of the description of a feature type of interest, especially concerning the optional or mandatory nature of each property. The W3C XML Schema (see W3C XML Schema Part 1) language, used to define GML application schemas, uses certain notations to indicate whether property elements are mandatory or optional or how many occurrences are valid. Thus, the GML representation of a feature may be schema-valid with only a subset of the possible properties present. A WFS client should be prepared to deal with a situation where it receives more property values than it requests using a projection clause.
7.9.2.4.5.2 XML encoding
The following XML-schema fragment defined the XML encoding for the wfs:PropertyName element:
<xsd:element name="PropertyName"
substitutionGroup="fes:AbstractProjectionClause">
<xsd:complexType>
<xsd:simpleContent>
<xsd:extension base="xsd:QName">
<xsd:attributeGroup ref="wfs:StandardResolveParameters"/>
<xsd:attribute name="resolvePath" type="xsd:string"/>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
</xsd:element>
7.9.2.4.5.3 KVP encoding
Table 9 defines the KVP-encoding of a projection clause.
URL Component | O/Ma | Description |
---|---|---|
PROPERTYNAME |
O |
A list of non-mandatory properties to include in the response. If more that one feature type name is specified as the value of the TYPENAMES keyword (in a non-join query), a corresponding list of parameter lists shall be specified (see 6.2.5.3). Each sub list shall correspond 1:1 with each feature type name listed as the value of the TYPENAMES parameter. |
StandardResolveParameters |
|
See Table 6. |
a O = Optional, M = Mandatory |
7.9.2.4.6 Parameter discussion
7.9.2.4.6.1 PropertyName parameter
For XML-encoded requests, the projection clause shall be encoded using one or more wfs:PropertyName elements. The value of each wfs:PropertyName element is a QName whose value shall match the name of one of the property names of one of the feature types listed in the typeNames attribute of the parent wfs:Query element in the GML representation of the relevant feature.
For KVP-encoded requests the projection clause shall be encoded using the keyword PROPERTYNAME (see Table 9). The value of the PROPERTYNAME keyword is a list or multiple lists of QName whose values shall match the name of one of the property names of one of the feature types listed as the value of the TYPENAMES keyword. Multiple lists of property names corresponding to multiple query expressions shall be isolated from one another by enclosing them within parentheses (see 6.2.5.3).
7.9.2.4.6.2 Standard resolve parameters
For XML-encoded requests, the standard resolve parameters shall be encoded using the attributes named resolve, resolveDepth and resolveTimeout (see 7.6.4.2) on the wfs:PropertyName element. For XML-encoded requests the standard resolve parameters on the projection clause control, on a per-property basis, how resource references are to be resolved within a response document. A value for these parameters specified on the wfs:PropertyName element shall supersede a value, if specified, on any enclosing parent element.
For KVP-encoded requests, the standard resolve parameters shall be encoded using the keywords RESOLVE, RESOLVEDEPTH and RESOLVETIMEOUT (see 7.6.4.3). For KVP-encoded requests, how resource references are resolved in a response document cannot be controlled on a pre-property basis and so no equivalent KVP-encoding for the standard resolve parameters is specified at this level. Instead, the keywords RESOLVE, RESOLVEDEPTH and RESOLVETIMEOUT may be used in KVP-encoded requests to control how resource references are resolved in a response document for all feature properties
7.9.2.4.7 Resolution path
For XML-encoded requests the resolvePath parameter shall be encoded as an attribute named resolvePath.
The resolvePath parameter is not defined for KVP-encoded requests.
The resolvePath parameter modifies the behaviour of the resolve parameter. The normal behaviour of the resolve parameter, when its value is set to local, remote or all, is to resolve all resource references to the depth specified by the resolveDepth parameter (see 7.6.4.5).
The resolvePath parameter, however, shall trigger resource resolution in the response document only along a certain property path.
A value specified for the resolvePath parameter shall only be used if the value of the nearest (in scope) resolve parameter is not set to "none". If the value of the nearest resolve attribute is set to "none" any value specified for the resolvePath parameter shall be ignored.
The value of the resolvePath parameter is a path expression but its specific encoding depends on how features are encoded.
For GML, which is the canonical feature encoding in this International Standard, the value of the resolutionPath parameter shall be an XPath (see W3C XML Path Language) expression that results in an object element. Value resolution shall stop at these instances and the value of the resolveDepth parameter shall be ignored.
EXAMPLE 1 The following is an example of the resolvePath attribute used in a query on the feature type Parcel:
Feature Instance examples:
<Parcel gml:id="DEXXXX00000000">
<registerEntry>
<LandRegisterEntry gml:id="DEXXXX00000001">
<relatedTo xlink:href="#DEXXXX00000002"/>
</LandRegisterEntry>
</registerEntry>
</Parcel>
<LandRegisterEntry gml:id="DEXXXX00000002">
<sequenceNumber>1</sequenceNumber>
</LandRegisterEntry>
Query example:
<wfs:Query typeNames="Parcel">
<wfs:PropertyName resolve="all"
resolvePath="valueOf(relatedTo)">valueOf(registerEntry)</wfs:PropertyName>
<fes:Filter>
<!– some filter expression –>
</fes:Filter>
</wfs:Query>
Specifying the resolvePath attribute has the effect that besides all the Parcel features meeting the criteria, also all their associated LandRegisterEntry features and the LandRegisterEntry features associated with them along the "relatedTo" property are returned, as well.
If the schema-element() function is supported by a server in XPath expressions, it shall also be supported in resolvePath parameter. If used, it shall match not only the element name that is the parameter of the schema-element() function, but also all elements directly or indirectly in its substitution group.
EXAMPLE 2 schema-element(gml:AbstractFeature) would match all features.
7.9.2.5 Selection clause
7.9.2.5.1 XML Encoding
For XML-encoded requests, the selection clause shall be encoded using the fes:Filter element (see OGC 09-026r2ISO 19143, Clause 7).
7.9.2.5.2 KVP encoding
For KVP-encoded requests the selection clause shall be encoded using one of the keywords FILTER, RESOURCEID or BBOX (see OGC 09-026r2ISO 19143, Table 2).
In this standard, KVP-encoded examples using the FILTER parameter (see B.8) use literal angle brackets (‘<’,’>’) for the sake of clarity. Actual requests, however, would need to percent-encode these brackets using %3C for ‘<’ and %3E for ‘>’ (see RFC 3986).[15]
7.9.2.5.3 Join processing
7.9.2.5.3.1 Join queries
A WFS may optionally support join queries.
A join operation query finds tuples (i.e. pairs, triples, etc.) of features, among a list of feature types, that satisfy some join condition specified using a filter expression (see OGC 09-026r2, Clause 7). If the join condition is satisfied then that tuple of features shall be in the result set of the query expression.
A join operation query shall be encoded by:
- listing the feature types to join using the typeNames parameter (see 7.9.2.4.1)
- specifying a join predicate between the feature types using a filter expression (see OGC 09-026r2, Clause 7)
Servers that implement join queries shall implement an inner join meaning that only feature tuples that match the join conditions shall be returned in the result set.
EXAMPLE 1 The following query expression uses a join to find the spouse of the person whose Identifier is "12345".
<wfs:Query typeNames="myns:Person myns:Person" aliases="a b">
<fes:Filter>
<fes:And>
<fes:PropertyIsEqualTo>
<fes:ValueReference>a/Identifier</fes:ValueReference>
<fes:Literal>12345</fes:Literal>
</fes:PropertyIsEqualTo>
<fes:PropertyIsEqualTo>
<fes:ValueReference>a/spouse<fes:ValueReference>
<fes:ValueReference>b/Identifier</fes:ValueReference>
</fes:PropertyIsEqualTo>
</fes:And>
</fes:Filter>
</wfs:Query>
In this example a join predicate between "a/spouse" and "b/Identifier" is used to locate the spouse of the person whose identifier is "12345". This is also an example of a self-join since the myns:Person feature type is being joined to itself in order to identify the spouse.
EXAMPLE 2 The following query expression uses a spatial join to find all park features that contain lakes:
<wfs:Query typeNames="myns:Parks myns:Lakes">
<fes:Filter>
<fes:Contains>
<fes:ValueReference>ns1:Parks/geometry</fes:PropertyName>
<fes:ValueReference>ns1:Lakes/geometry</fes:PropertyName>
</fes:Contains>
</fes:Filter>
</wfs:Query>
The list of feature types to join is specified using the typeNames attribute (i.e. typeName="myns:Parks myns:Lakes") on the wfs:Query element. The join predicate is specified using the fes:Filter element and finds all pairs ofns1:Park and ns1:Lake features whose geometries satisfy the spatial operator fes:Contains. The response to a request with a join query is described in 11.3.3.6.
Join queries are categorized as standard, spatial and temporal joins based on the operators that are used in the join predicates.
If all the Filter operators except the spatial and temporal operators may be used in a join predicate, the server implements standard join queries as in in Example 1.
If spatial operators may be used in join predicates, the server implements spatial join queries as in Example 2.
If temporal operators may be used in join predicates, the server implement temporal join queries.
If a web feature service does support joins, it shall advertise this fact using the ImplementsStandardJoins, ImplementsSpatialJoins and ImplementsTemporalJoins constraints in its capabilities document (see 8.3.3).
7.9.2.5.3.2 Shared properties
In response to a join query that contains a projection clause that specifies the name of a property that is shared among two or more joined feature types, as is possible in GML (see ISO19136:2007), that shared property shall appear in all features of the response tuple that contain that property.
EXAMPLE Consider two feature types ns1:A and ns2:B that share a property element called ns3:C. If the projection clause of an ad hoc join query on ns1:A and ns2:B specifies the common property ns3:C, how does a server know if the client means ns3:C from feature type ns1:A or ns3:C from feature type ns2:B? The answer is that the server does not know but also that it does not need to know since ns3:C should appear in both the ns1:A and ns2:B features in the response document.
7.9.2.5.3.3 Use of the schema-element() function in joins
The schema-element() function shall not be used if a join operation is being performed.
In the event that a schema-element() function is specified in a join operation, the WFS shall raise an OperationNotSupported exception (see Table 3) where the "locator" attribute (see OGC 06-121r3:2009, 8.4) value shall be set to "schema-element()".
7.9.2.5.3.4 Coordinate reference system handling
When comparing two geometries having different srsName values in a predicate, the server shall either convert one of the geometries to the CRS of the other geometry or the server shall convert both geometries to a third common CRS before performing the comparison.
In the event that either or both geometries in a predicate do not have a CRS associated with them, the server shall assume that the geometry is in the default CRS asserted for its feature type in the server’s capabilities document. Comparisons of the two geometries can then proceed as described in the previous sentence.
7.9.2.5.3.5 Units of measure handling
This International Standard does not define any support for handling conversions between unit of measure.
7.9.2.5.4 Sorting clause
7.9.2.5.4.1 Request Semantics
The sorting clause of an ad hoc query expression shall be specified using a SortBy value (see Figure 10 and OGC 09-026r2, Clause 8).
7.9.2.5.4.2 XML encoding
In XML, the sorting clause of an ad hoc query expression shall be encoded using the fes:SortBy element (see OGC 09-026r2, Clause 8).
An ad hoc query expression shall have a minimum of zero and a maximum of one fes:SortBy child elements.
7.9.2.5.4.3 KVP encoding
For KVP-encoded request, the sorting clause shall be encoded using the keyword SORTBY keyword (see OGC 09-026r2, Table 2).
7.9.2.5.4.4 Sort processing
A web feature service that receives an ad hoc query expression without a sorting clause, shall generate a response document in which features are presented in whatever order the server chooses. However, to comply with this International Standard, servers shall ensure that whatever order is presented when an ad hoc query, not containing a sort clause, is first executed is preserved across subsequent executions of the same ad hoc query expression on the same set of features.
EXAMPLE A server may choose to sort the features by their gml:id if the client has not specified a specific sorting clause. Subsequent invocations of the same query expression on the same set of data should result in a response document that presents the features in the same order.
In the event that a web feature service receives a request containing an ad hoc query with a sorting clause, the service shall respond by presenting features in the response document in the requested order.
Sorting is only supported within the scope of a single ad hoc query expression. Global sorting over all features in a result set, generated by multiple ad hoc query expressions being encoded in the request, shall not be supported. The trivial exception to this statement, of course, is the case where the request contains a single query expression.
When processing a query with a sorting clause, the sort shall be executed in the context of all the data that matches the request parameters before the response is possibly reduced to a set within the limits of the count attribute (see 7.6.3.5).
7.9.3 Stored query expression
7.9.3.1 Request Semantics
A stored query expression may be used in a GetPropertyValue (see Clause 10), GetFeature (see Clause 11), GetFeatureWithLock (see Clause 13) or LockFeature (see Clause 12) operation to identify a set of features to be operated upon.
A stored query expression (see Figure 11) is a persistent, parameterized, identifiable query expression. A stored query can be repeatedly invoked using its identifier with different values bound to its parameters each time.
All servers shall implement the ability to list, describe and execute stored queries.
All server implementations shall offer a stored query that fetches features based on their identifier. Additional stored queries that are packaged with the server may also be offered.
Clause 14 describes a set of operations for managing stored query expressions.
7.9.3.2 XML encoding
The following XML Schema fragment defines the XML encoding of a stored query expression:
<xsd:element name="StoredQuery" type="wfs:StoredQueryType"
substitutionGroup="fes:AbstractQueryExpression"/>
<xsd:complexType name="StoredQueryType">
<xsd:complexContent>
<xsd:extension base="fes:AbstractQueryExpressionType">
<xsd:sequence>
<xsd:element name="Parameter" type="wfs:ParameterType"
minOccurs="0" maxOccurs="unbounded"/>
</xsd:sequence>
<xsd:attribute name="id" type="xsd:anyURI" use="required"/>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<xsd:complexType name="ParameterType" mixed="true">
<xsd:sequence>
<xsd:any namespace="##other" processContents="lax" minOccurs="0"
maxOccurs="1"/>
</xsd:sequence>
<xsd:attribute name="name" type="xsd:string" use="required"/>
</xsd:complexType>
The abstract type fes:AbstractQueryExpressionType is described in OGC 09-026r2, 6.2.
7.9.3.3 KVP encoding
Table 10 defines the KVP-encoding for a stored query expression.
URL Component | O/Ma | Description |
---|---|---|
STOREDQUERY_ID |
M |
The identifier of the stored query to invoke. |
storedquery_parameter=value |
O |
Each parameter of a stored query shall be encoded in KVP as a keyword-value pair. Stored query parameters shall not have names that conflict with any WFS parameter name. |
a O = Optional, M = Mandatory |
Unlike ad hoc queries, where more than one query can be encoded in a single KVP-encoded request, only one stored query shall be invoked per KVP-encoded request.
7.9.3.4 Stored query identifier
For XML-encoded requests the stored query identifier shall be encoded using the id attribute on the wfs:StoredQuery element.
For KVP-encoded requests the stored query identifier shall be encoded using the STOREDQUERY_ID keyword.
Each stored query shall be assigned an identifier unique to the server that can be used to invoke the query.
7.9.3.5 Stored query parameters
For XML-encoded requests, each stored query parameter shall be encoded using a wfs:Parameter element. The name of the parameter shall be encoded as the value of the name attribute on the wfs:Parameter element. The value of the parameter shall be encoded as the content of the wfs:Parameter element.
For KVP-encoded requests, stored query parameters shall be encoded as keyword-value pairs. The parameter name shall be encoded as the keyword and its value shall be encoded as the value of the keyword-value pair.
EXAMPLE This example does a GetFeature request that invokes the GetTreesByArea stored query with the "AREA" parameter.
http://www.someserver.example.com/wfs.cgi?request=GetFeature&storedquery_id=urn-x:wfs:StoredQueryId:SomeCompanyName:GetTreesByArea&AREA=10000
A server shall ensure that stored query parameters names do not collide with WFS KVP keywords.
Stored query parameters are referenced by name and may thus appear in any order when encoding a stored query invocation.
7.9.3.6 GetFeatureById stored query
All servers shall implement a stored query that accepts a single argument, named "id" of type xsd:string, and returns a single feature whose identifier is equal to the specified value of the id argument.
This stored query shall have the identifier: urn:ogc:def:query:OGC-WFS::GetFeatureByIdhttp://www.opengis.net/def/query/OGC-WFS/0/GetFeatureById[16]
NOTE: The previous identifier for the GetFeatureById stored query, "urn:ogc:def:query:OGC-WFS::GetFeatureById", may still be used but is deprecated.
EXAMPLE The following URL invokes the mandatory GetFeatureById stored query to retrieve and present a single feature from the servers data store:
http://www.someserver.example.com/wfs.cgi?SERVICE=WFS&
VERSION=2.0.02.0.2&
REQUEST=GetFeature&
STOREDQUERY_ID=urn:ogc:def:query:OGC-WFS::GetFeatureById&
http://www.opengis.net/def/query/OGC-WFS/0/GetFeatureById&
ID=INWATERA_1M.1013
8 GetCapabilities operation
8.1 Introduction
The GetCapabilities operation generates a service metadata document describing a WFS service provided by a server.
All web feature services shall implement the KVP-encoding of the GetCapabilities operation.
A web feature service may optionally implement the XML-encoding of the GetCapabilities operation.
8.2 Request
8.2.1 Request Semantics
Figure 12 describes the schema of a GetCapabilities request.
8.2.2 XML encoding
The following XML Schema fragment defines the XML-encoding of the GetCapabilities request:
<xsd:element name="GetCapabilities" type="wfs:GetCapabilitiesType"/>
<xsd:complexType name="GetCapabilitiesType">
<xsd:complexContent>
<xsd:extension base="ows:GetCapabilitiesType">
<xsd:attribute name="service" type="ows:ServiceType" use="required" fixed="WFS"/>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
The base type, ows:GetCapabilitiesType, is defined in the OWS Common Implementation Specification (see OGC 06-121r3:2010, 7.2.4).
8.2.3 KVP encoding
The KVP encoding of the GetCapabilities request shall be as specified in OGC 06-121r3:2009, 7.2.2.
8.3 Response
8.3.1 Response Semantics
Figure 13 describes the schema of a GetCapabilities response.
8.3.2 XML encoding
The root element of the response to a GetCapabilities request is the wfs:WFS_Capabilities element which is declared by the following XML Schema fragment:
<xsd:element name="WFS_Capabilities" type="wfs:WFS_CapabilitiesType"/>
<xsd:complexType name="WFS_CapabilitiesType">
<xsd:complexContent>
<xsd:extension base="ows:CapabilitiesBaseType">
<xsd:sequence>
<xsd:element name="WSDL" minOccurs="0">
<xsd:complexType>
<xsd:complexContent>
<xsd:restriction base="xsd:anyType">
<xsd:attributeGroup ref="xlink:simpleLink"/>
</xsd:restriction>
</xsd:complexContent>
</xsd:complexType>
</xsd:element>
<xsd:element ref="wfs:FeatureTypeList" minOccurs="0"/>
<xsd:element ref="fes:Filter_Capabilities" minOccurs="0"/>
</xsd:sequence>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
The base type, ows:CapabilitiesBaseType, is defined in the OWS Common Implementation Specification (see OGC 06-121r3:2009, 7.2.4).
The elements ows:ServiceIdentification, ows:ServiceProvider and ows:OperationMetadata are inherited from the base type ows:CapabilitiesBaseType.
8.3.3 Capabilities document
In addition to the sections defined in 7.4 of OGC 06-121r3:2009, the capabilities response document shall contain the following sections:
- WSDL section (optional)
This section allows a server to reference an optional WSDL document that describes the operations that the service offers (see Annex E). This section may be included in addition to the OperationsMetadata section for tools that know how to use the WSDL. - FeatureType list section (mandatory)
This section defines the list of feature types that are offered by a web feature service. Lightweight metadata is provided about each feature type as described in Table 11. - Filter capabilities section (mandatory)
The schema of the Filter Capabilities Section is defined in OGC 09-026r2, 7.13, and is used to advertise the expressions that may be used to form query predicates.
In the schema, the wfs:FeatureTypeList and fes:Filter_Capabilities elements are specified as optional (i.e. minOccurs="0"). This is done in order to support the Sections parameter (see 06-121r3:2009, 7.3.3) of the GetCapabilities request which allows abbreviated service metadata documents to be requested. However, when the full service metadata is generated it shall contain a FeatureType list section and a Filter capabilities section.
8.3.4 FeatureTypeList section
The wfs:FeatureTypeList element shall contain a list of feature types, subtyped from gml:AbstractFeatureType, that a WFS offers.
The following XML Schema fragment defines the wfs:FeatureTypeList element:
<xsd:element name="FeatureTypeList" type="wfs:FeatureTypeListType"/>
<xsd:complexType name="FeatureTypeListType">
<xsd:sequence>
<xsd:element name="FeatureType" type="wfs:FeatureTypeType"
maxOccurs="unbounded"/>
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="FeatureTypeType">
<xsd:sequence>
<xsd:element name="Name" type="xsd:QName"/>
<xsd:element ref="wfs:Title" minOccurs="0" maxOccurs="unbounded"/>
<xsd:element ref="wfs:Abstract" minOccurs="0" maxOccurs="unbounded"/>
<xsd:element ref="ows:Keywords" minOccurs="0" maxOccurs="unbounded"/>
<xsd:choice>
<xsd:sequence>
<xsd:element name="DefaultCRS" type="xsd:anyURI"/>
<xsd:element name="OtherCRS" type="xsd:anyURI"
minOccurs="0" maxOccurs="unbounded"/>
</xsd:sequence>
<xsd:element name="NoCRS">
<xsd:complexType/>
</xsd:element>
</xsd:choice>
<xsd:element name="OutputFormats" type="wfs:OutputFormatListType"
minOccurs="0"/>
<xsd:element ref="ows:WGS84BoundingBox"
minOccurs="0" maxOccurs="unbounded"/>
<xsd:element name="MetadataURL" type="wfs:MetadataURLType"
minOccurs="0" maxOccurs="unbounded"/>
<xsd:element name="ExtendedDescription"
type="wfs:ExtendedDescriptionType" minOccurs="0"/>
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="OutputFormatListType">
<xsd:sequence maxOccurs="unbounded">
<xsd:element name="Format" type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="MetadataURLType">
<xsd:attributeGroup ref="xlink:simpleLink"/>
<xsd:attribute name="about" type="xsd:anyURI"/>
</xsd:complexType>
<xsd:complexType name="ExtendedDescriptionType">
<xsd:sequence>
<xsd:element ref="wfs:Element" maxOccurs="unbounded"/>
</xsd:sequence>
</xsd:complexType>
<xsd:element name="Element" type="wfs:ElementType"/>
<xsd:complexType name="ElementType">
<xsd:sequence>
<xsd:element ref="ows:Metadata"/>
<xsd:element ref="wfs:ValueList"/>
</xsd:sequence>
<xsd:attribute name="name" type="xsd:string" use="required"/>
<xsd:attribute name="type" type="xsd:QName" use="required"/>
</xsd:complexType>
<xsd:element name="ValueList" type="wfs:ValueListType"/>
<xsd:complexType name="ValueListType">
<xsd:sequence maxOccurs="unbounded">
<xsd:element ref="wfs:Value"/>
</xsd:sequence>
</xsd:complexType>
<xsd:element name="Value" type="xsd:anyType"/>
The wfs:FeatureTypeList element shall contain one wfs:FeatureType element for each feature type that the service offers. The element contains metadata about the feature type.
Table 11 lists the elements that are used to describe each feature type listed within the wfs:FeatureTypeList element.
Element name | Description |
---|---|
Name |
The namespace-qualified name of the feature type. This element is mandatory. |
Title |
An unordered list of zero or more human-readable titles that briefly identify this feature type in menus. The xml:lang attribute may be used to specify a language for the title. If more than one wfs:Title element is listed, each title shall have a different value for the xml:lang attribute. |
Abstract |
An unordered list of zero or more wfs:Abstract elements. Each wfs:Abstract element is a descriptive narrative for more information about the feature type. The xml:lang attribute may be used to specify a language for the abstract. If more than one wfs:Abstract element is listed, each abstract shall have a different value for the xml:lang attribute. |
Keywords |
The ows:Keywords element contains short words to aid catalogue searching. |
DefaultCRS |
The wfs:DefaultCRS element indicates which coordinate reference
system shall be used by a WFS to express the state of |
OtherCRS |
The wfs:OtherCRS element shall be used to indicate other supported CRSs within transaction and query requests. A 'supported CRS' means that the WFS supports the transformation of compatible spatial properties between the wfs:OtherCRS and the internal storage CRS. The effects of such a transformation shall be considered when determining and declaring the guaranteed data accuracy. |
NoCRS |
The wfs:NoCRS element shall be used for feature types that have no spatial properties, and therefore no CRS whatsoever. It is not a requirement for Features and FeatureCollections to have spatial properties. The wfs:NoCRS element shall never imply, and therefore cannot be used for, semantics of "Unknown CRS". This element is used as an identifying label only, and therefore has no element or attribute content. |
OutputFormats |
The wfs:OutputFormats element shall be a list of MIME types indicating the output formats that may be generated for a feature type. If this optional element is not specified, then all the result formats listed for the GetFeature operation are assumed to be supported. |
WGS84BoundingBox |
The ows:WGS84BoundingBox element may be used to indicate the edges of an enclosing rectangle in decimal degrees of latitude and longitude in WGS84. Its purpose is to facilitate geographic searches by indicating where instances of the particular feature type exist. Since multiple ows:WGS84BoundingBox elements may be specified, a WFS may indicate where various clusters of data exist. This knowledge aids client applications by letting them know where they should query in order to have a high probability of finding feature data. |
MetadataURL |
A WFS may use zero or more wfs:MetadataURL elements to offer detailed metadata about the data in a particular feature type. The xlink:href element shall be used to reference any metadata. The optional about attribute may be used to reference the aspect of the element which includes this wfs:MetadataURL element that this metadata provides more information about. |
ExtendedDescription |
A WFS may add elements to the description of a feature type, without having to redefine the capabilities schema, using the wfs:ExtendedDescription element. The wfs:ExtendedDescription element contains one or more wfs:Element elements. The wfs:Element element includes a name attribute, a type attribute and contains a value list enumerating one or more values for the named extended descriptive element. The name attribute is used to designate the name of the extended descriptive element . The type attribute is used to designate a type for the values in the value list of the extended descriptive element. The type shall be taken from the list of built-in types defined by XML Schema (see W3C XML Schema Part 2). The wfs:Element element also includes an ows:Metadata element that shall be used to reference metadata describing the wfs:Element. The wfs:ExtendedDescription element is intended to be used by communities of interest to customize the description of a feature type for specific purposes or by vendors wishing to add vendor-specific descriptive information to the description of a feature type in a capabilities document. In all cases, clients shall be able to safely ignore all of the extended descriptive elements. Each extended description wfs:Element added to the description of a feature type shall be accompanied by an ows:Metadata element offering descriptive metadata about the added element. |
8.3.5 Parameters domains and constraints
8.3.5.1 Introduction
The ows:Parameter and ows:Constraint elements are defined in the OWS Common Implementation Specification (see OGC 06-121r3:2009, Table 13) and allow valid domain values and constraints to be defined globally for all operations or locally for specific operations that a web feature service offers.
Tables 12, 13 and 14 describe parameter domains and service constraints defined by this standard. Implementations may include additional parameter domains (e.g. for vendor specific parameters) and service constraints, via the ows:Parameter and/or ows:Constraint elements, in their capabilities document. Such additional parameter domains and/or service constraints can be safely ignored by clients if they are not recognised.[73]
8.3.5.2 Parameter domains
Table 12 defines the parameter domains that may be defined in the capabilities document of a web feature service.
Operation Name | Parameter Name | Expected Value Type | Description / Possible Values |
---|---|---|---|
All operations |
version |
string |
Shall include the value " |
GetFeature GetFeatureWithLock Transaction |
srsName |
string URI or MIME type |
List of CRS's that the WFS is capable of handling |
GetCapabilities |
AcceptVersions |
string |
Shall include the value " |
GetCapabilities |
AcceptFormats |
MIME type |
Shall include the value "text/xml". May include other MIME types such as "text/html" or "text/plain" or any other vendor supported MIME type the server is capable of generating. |
GetCapabilities |
Sections |
string |
Zero or more of the following list of values: "ServiceIdentification", "ServiceProvider", "OperationsMetadata", "FeatureTypeList", "Filter_Capabilities" |
DescribeFeatureType |
outputFormat |
string or MIME type |
Shall include the value "application/gml+xml; version=3.2". May include any other string or MIME type that the server supports including previous version of GML. |
GetPropertyValue |
outputFormat |
string |
Shall include the value "application/gml+xml; version=3.2". May include any other string or MIME type that the server supports including previous versions of GML |
GetPropertyValue |
resolve |
string |
Shall include the values "none" and "local". May also include the values "remote" and "all" indicating that the server can resolve remote resource references. |
GetFeature |
outputFormat |
string or MIME type |
Shall include the value "application/gml+xml; version=3.2". May include any other string or MIME type that the server supports including previous versions of GML. |
GetFeature |
resolve |
string |
Shall include the values "none" and "local". May also include the values "remote" and "all" indicating that the server can resolve remote resource references. |
GetFeatureWithLock |
outputFormat |
string or MIME type |
Shall include the values "application/gml+xml; version=3.2". May include any other string or MIME type that the server supports including previous version of GML. |
GetFeatureWithLock |
resolve |
string |
Shall include the values "none" and "local". May also include the values "remote" and "all" indicating that the server can resolve remote resource references. |
CreateStoredQuery |
language |
anyURI |
Shall include the value urn:ogc:def:queryLanguage:OGC-WFS::WFSQueryExpression. May also include other values indicating other languages are supported. This International Standard does not assign any meaning to or describe any additional values that might be listed. |
Transaction |
inputFormat |
string or MIME type |
Shall include the value "application/gml+xml; version=3.2". May include any other string or MIME type that the server supports including previous version of GML. |
Transaction |
vendorId |
string |
Any string that is used as a vendor identifier for the wfs:Native element. |
Servers shall, either locally for each operation or globally for the entire service, populate the parameter domains in Table 12 for all the operations they claim to support in their capabilities document.
In general the domain of a parameter is specific to a web feature service implementation.
EXAMPLE 1 The allowed values for the srsName parameter are dictated by the particular transformations that a WFS supports.
In some cases, however, the domain of a parameter is defined by this International Standard.
EXAMPLE 2 The domain of the resolve parameter (see 7.6.4) is defined in this International Standard as consisting of the values "local", "remote", "all" or "none".
In such cases a web feature service may only restrict the domain. If the full domain is supported, then the parameters domain shall not be listed in the capabilities document.
8.3.5.3 Service and operation constraints
All the service constraints listed in Table 13 shall be specified in the capabilities document (see 8.3.3) of a server with the appropriate value set to indicate whether the server conforms to the corresponding conformance class or not.
Constraint Name | Possible Values and/or Value Types | Description |
---|---|---|
ImplementsBasicWFS |
Boolean value; either "TRUE" or "FALSE" |
Indicates that the server implements the Basic WFS conformance class. |
ImplementsTransactionalWFS |
Boolean value; either "TRUE" or "FALSE" |
Indicates that the server implements the Transactional WFS conformance class. |
ImplementsLockingWFS |
Boolean value; either "TRUE" or "FALSE" |
Indicates that the server implements the Locking conformance class. |
KVPEncoding |
Boolean value; either "TRUE" or "FALSE" |
Indicates that the server implements the HTTP GET conformance class |
XMLEncoding |
Boolean value; either "TRUE" or "FALSE" |
Indicates that the server implements the HTTP POST conformance class |
SOAPEncoding |
Boolean value; either "TRUE" or "FALSE" |
Indicates that the server implements the SOAP conformance class. |
ImplementsInheritance |
Boolean value; either "TRUE" or "FALSE" |
Indicates that the server implements the Inheritance conformance class. |
ImplementsRemoteResolve |
Boolean value; either "TRUE" or "FALSE" |
Indicates that the operation to which the constraint is specified can resolve references that are remote to the server. If the constraint is not specified then the value of FALSE shall be assumed. |
ImplementsResultPaging |
Boolean value; either "TRUE" or "FALSE" |
Indicates that the server supports the ability to pages through a result set count features at a time. |
ImplementsStandardJoins |
Boolean value; either "TRUE" or "FALSE" |
Indicates that the server implements the Standard Joins conformance class |
ImplementsSpatialJoins |
Boolean value; either "TRUE" or "FALSE" |
Indicates that the server implements the Spatial Joins conformance class. |
ImplementsTemporalJoins |
Boolean value; either "TRUE" or "FALSE" |
Indicates that the server implements the Temporal Joins conformance class. |
ImplementsFeatureVersioning |
Boolean value; either "TRUE" or "FALSE" |
Indicates that the server implements the Feature Versions conformance class. |
ManageStoredQueries |
Boolean value; either "TRUE" or "FALSE" |
Indicates that the server implements the Manage Stored Queries conformance class. |
A server may optionally specify one or more of the constraints defined in Table 14 in its capabilities document (see 8.3.3).
Constraint Name | Possible Values and/or Value Types | Default Value | WFS Operation | Description |
---|---|---|---|---|
AutomaticDataLocking |
Boolean value; either "TRUE" or "FALSE" |
FALSE |
Transaction |
Indicates that the transaction operation automatically locks data in order to maintain consistency thus alleviating the client from having to use the LockFeature or GetFeatureWithLock operations to lock the features to be modified. |
PreservesSiblingOrder |
Boolean value; either "TRUE" or "FALSE". |
FALSE |
Transaction |
Specifies whether the server preserves sibling order for properties with cardinality greater than 1. If the value is true, the server shall preserve sibling order. Otherwise sibling order is not guaranteed to be preserved. |
PagingIsTransactionSafe |
Boolean value; either "TRUE" or "FALSE" |
FALSE |
GetFeature GetFeatureWithLock GetPropertyValue |
Specifies whether the server maintains transactional consistency between paging iterations. |
CountDefault |
Integer value greater than or equal to zero. |
|
GetFeature GetFeatureWithLock GetPropertyValue |
Specifies the default value for the count parameter. If the constraint is not specified, and Response Paging is neither supported nor triggered by the request, the entire result shall be returned in one response. Servers are strongly encouraged to advertise a value for CountDefault as a means of self-defence, so that a request may not clog a server |
ResolveTimeoutDefault |
Integer greater than zero. |
|
GetFeature GetFeatureWithLock GetPropertyValue |
Defines the maximum number of seconds a server shall wait before receiving a response while resolving resource references. If the constraint is not specified the server shall wait indefinitely in order to resolves a remote reference. |
SortLevelLimit |
Integer value greater than zero. |
|
GetFeature GetFeatureWithLock |
The SortLevelLimit constraint defines the maximum number of properties that may be simultaneously sorted. In the event that a request contains too many fes:SortProperty elements for a particular service (i.e. exceeds the SortLevelLimit constraint), the service shall respond with an exception as specified in 7.5. If the constraint is not specified then there is no limit to the number of sort properties that may be specified. |
ResolveLocalScope |
Integer greater than zero OR the character "*". |
* |
GetFeature GetFeatureWithLock GetPropertyValue |
Defines the minimum and maximum number of levels, when resolving references to resources that are part of the server's local data store. The value * means to as many as all levels. If the constraint is not specified the default value of "*" shall be assumed. |
ResolveRemoteScope |
Integer greater than zero OR the character "*" |
* |
GetFeature GetFeatureWithLock GetPropertyValue |
Defines the minimum and maximum number of levels, when resolving remote references. The value * means to as many as all levels. If the constrain is not specified the default value of "*" shall be assumed. |
ResponseCacheTimeout |
Integer greater than zero. |
|
GetFeature GetFeatureWithLock GetPropertyValue |
Define the length of time in seconds that responses shall be cached to support paging (see 7.7.4.4). If the constraint is not specified then the response cache never times out. |
QueryExpressions |
QName; one of wfs:Query of wfs:StoredQuery |
|
GetFeature GetFeatureWithLock GetPropertyValue LockFeature |
The names of the supported query expression elements. |
NOTE The constraints may be specified on the indicated operation. If more that one operation is listed, the constraint may be specified on each operation individually (perhaps with different values for each operation) or at the service level indicating that the constraint applies for all listed operations. |
8.4 Extension points
Extension points allow servers to advertise additional values for existing parameters, dynamically add elements to the metadata describing feature types, or execute operations not described in this International Standard. This International Standard contains the following extensions points:
- DescribeFeatureType/@outputFormat (see 9.2.4.2)
- GetFeature/@outputFormat (see 11.2.4.1)
- fes:AbstractQueryExpression (see 10.2.4.4, 11.2.4.3, 12.2.4.1)
- GetFeatureWithLock/@outputFormat (see 13.1)
- Transaction/Insert/@inputFormat (see 15.2.4.2)
- Transaction/Update/@inputFormat (see 15.2.5.2.4)
- Transaction/Replace/@inputFormat (see 15.2.6.2.2)
- wfs:ExtendedDescription element (see Table 11)
- ows:ExtendedCapabilities (see OGC 06-121r3:2009, 7.4.6)
- wfs:Native (see 15.2.8)
- wfs:AbstractTransactionAction (see 15.2.2)
This International Standard assigns no meaning or behaviour to any value advertised for these extension points in the server’s capabilities document except as described herein. However, if additional values or behaviours are advertised in a server’s capabilities document they shall be accompanied by additional metadata describing their meaning.
Metadata may be associated with each wfs:Element element contained within the wfs:ExtendedDescription element using the ows:Metadata element (see OGC 06-121r3:2009, Table 32).
The OGC Web Services Common Specification (see OGC 06-121r3:2009, 7.4.6) contains a complete description of how to associate metadata with parameter values or operations contained within a capabilities document. The following examples illustrate the usage.
EXAMPLE 1 The following XML fragment illustrates how to reference metadata about additional GetFeature output format values.
<Operation name="GetFeature">
<DCP>
<HTTP>
<Get xlink:href="http://www.someserver.example.com/wfs.cgi?"/>
</HTTP>
</DCP>
<Parameter name="outputFormat">
<AllowedValues>
<Value>application/gml+xml; version=3.2</Value>
<Value>application/gml+xml; version=3.1</Value>
<Value>application/gml+xml; version=2.1</Value>
</AllowedValues>
</Parameter>
<Metadata about="application/gml+xml; version=3.1"
xlink:href="http://portal.opengeospatial.org/files/?artifact_id=4700"/>
<Metadata about="application/gml+xml; version=2.1"
xlink:href="http://portal.opengeospatial.org/files/?artifact_id=11339"/>
</Operation>
EXAMPLE 2 The following XML fragment illustrates how to reference metadata about vendor specific operations executed using the wfs:Native element.
<Operation name="Transaction">
<DCP>
<HTTP>
<Get xlink:href="http://www.someotherserver.example.com/transform?"/>
</HTTP>
</DCP>
<Parameter name="Native">
<AllowedValues>
<Value>ALTER SESSION ENABLE PARALLEL DML</Value>
<Value>MySecretAction</Value>
</AllowedValues>
</Parameter>
<Metadata about="ALTER SESSION ENABLE PARALLEL DML"
xlink:href="http://download-uk.oracle.com/docs/cd/A97630_01/server.920/a96540/statements_22a.htm#2053493"/>
<Metadata about="MySecretAction" xlink:href=http://www.yas.com/MySecretActionDescription.html/>
</Operation>
EXAMPLE 3 The following XML fragment illustrates how a vendor specific operation can be advertised in a server’s capabilities document using ows:ExtendedCapabilities element.
<ExtendedCapabilities>
<Operation name="MySecretOperation">
<DCP>
<HTTP>
<Get xlink:href="http://www.someserver.example.com/wfs.cgi?"/>
</HTTP>
</DCP>
<Metadata about="MySecretOperation"
xlink:href="http://www.myserver.com/Operations/MySecretOperation.html"/>
</Operation>
</ExtendedCapabilities>
8.5 Exceptions
In the event that a web feature service encounters an error parsing a GetCapabilities request, it shall raise an OperationParsingFailed exception as described in 7.5.
In the event that a web feature service encounters an error processing a GetCapabilities request, it shall raise an OperationProcessingFailed exception as described in 7.5.
9 DescribeFeatureType operation
9.1 Introduction
The DescribeFeatureType operation returns a schema description of feature types offered by a WFS instance. The schema descriptions define how a WFS expects feature instances to be encoded on input (via Insert, Update and Replace actions) and how feature instances shall be encoded on output (in response to a GetPropertyValue, GetFeature or GetFeatureWithLock operation).
9.2 Request
9.2.1 Request Semantics
Figure 14 describes the schema of a DescribeFeatureType request.
9.2.2 XML Encoding
The following XML Schema fragment defines the XML encoding of a DescribeFeatureType request:
<xsd:element name="DescribeFeatureType" type="wfs:DescribeFeatureTypeType"/>
<xsd:complexType name="DescribeFeatureTypeType">
<xsd:complexContent>
<xsd:extension base="wfs:BaseRequestType">
<xsd:sequence>
<xsd:element name="TypeName" type="xsd:QName"
minOccurs="0" maxOccurs="unbounded"/>
</xsd:sequence>
<xsd:attribute name="outputFormat" type="xsd:string"
default="application/gml+xml; version=3.2"/>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
9.2.3 KVP Encoding
Table 15 defines the KVP encoding for the DescribeFeatureType request.
URL Component | O/Ma | Description |
---|---|---|
Common Keywords |
|
See Table 7. |
TYPENAME |
O |
A comma separated list of feature types to describe. If no value is specified, the complete application schema offered by the server shall be described. |
OUTPUTFORMAT |
O |
Shall support the value "application/gml+xml; version=3.2" indicating that a GML (see ISO19136:2007) application schema shall be generated. A server may support other values to which this International Standard does not assign any meaning. |
a O = Optional, M = Mandatory |
9.2.4 Parameter discussion
9.3.4.1 typeNames parameter
For XML-encoded requests the typeNames parameter shall be encoded using the typeNames attribute on the wfs:DescribeFeatureType element.
For KVP-encoded requests the typeNames parameter shall be encoded using the TYPENAMES keyword.
The typeNames parameter encodes the names of one or more features types that shall be described by the DescribeFeatureType operation.
The set of permissible values for the typeNames parameter shall be the set of feature type names listed in a server’s capabilities document (see 8.3.3).
If the typeName parameter is omitted, the complete application schemas supported by the server shall be returned in response.
9.2.4.2 outputFormat parameter
For XML-encoded requests the outputFormat parameter shall encoded using an attribute of the same name on the wfs:DescribeFeatureType element.
For KVP-encoded requests the outputFormat parameter shall be encoded using the keyword OUTPUTFORMAT (see 7.6.3.3).
The outputFormat parameter is used to indicate the schema description language that shall be used to describe feature types.
The default value of "application/gml+xml; version=3.2" shall be used to indicate that the features types shall be described using a GML (see ISO 19136:2007) application schema. Every WFS that conforms to this International Standard shall support this default value.
A server may advertise additional values for the outputFormat attribute in its capabilities document (see Table 12) indicating that multiple output formats, including previous versions of GML, are supported. However, this International Standard only assigns meaning to the value "application/gml+xml; version=3.2.
If any such additional outputFormat values are listed in the capabilities document, this International Standard recommends that additional metadata (see OGC 06-121r3:2009, Table 32) describing the meaning of the additional values be included in the capabilities document (see 8.3.3).
NOTE Since previous OGC versions of this International Standard (see OGC 02-058 and OGC 04-094) are bound to specific versions of GML, a server may support previous versions of GML by advertising in its capabilities document (see Table 12) that it supports previous OGC versions of this International Standard.
9.4 Response
9.4.1 Introduction
In response to a DescribeFeatureType request, where the value of the outputFormat parameter has been set to "application/gml+xml; version=3.2", a WFS implementation shall return a complete and valid GML (see ISO 19136:2007) application schema that contains the definition of the feature types listed in the request. The document(s) returned by the DescribeFeatureType request may be used to validate feature instances generated by the WFS in the form of feature collections on output or feature instances specified as input for transaction operations.
9.4.2 Supporting multiple namespaces
An XML Schema document can only declare elements in a single namespace (see W3C XML Schema Part 2). In the event that a DescribeFeatureType operation requests that feature types in multiple namespaces be described, the server shall generate the complete schema for one of the requested namespaces and import the remaining namespaces. This International Standard does not mandate which namespace’s schema should be generated and which namespaces should be imported.
EXAMPLE Consider the following request to describe feature types in multiple namespaces :
<?xml version="1.0" ?>
<DescribeFeatureType
version="2.0.02.0.2"
service="WFS"
xmlns="http://www.opengis.net/wfs/2.0"
xmlns:ns01="http://www.server01.com/ns01"
xmlns:ns02="http://www.server02.com/ns02"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.opengis.net/wfs/2.0 http://schemas.opengis.net/wfs/2.0.02.0/wfs.xsd">
<TypeName>ns01:TreesA_1M</TypeName>
<TypeName>ns02:RoadL_1M</TypeName>
</DescribeFeatureType>
A WFS might generate the following response to this request:
<?xml version="1.0" ?>
<xsd:schema
targetNamespace="http://www.server01.com/ns01"
xmlns:ns01="http://www.server01.com/ns01"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
elementFormDefault="qualified"
attributeFormDefault="unqualified">
<import namespace="http://www.server02.com/ns02"
schemaLocation="http://www.yourserver.com/wfs.cgi?
REQUEST=DescribeFeatureType&TYPENAMES=ns02:RoadL_1M"/>
<xsd:element name="TREESA_1M" type="ns01:TREESA_1MType" substitutionGroup="gml:_Feature"/>
<xsd:complexType name="TREESA_1MType">
<xsd:complexContent>
<xsd:extension base="gml:AbstractFeatureType">
<!– list property declarations for feature type TREESA_1M –>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<!– other declarations that are part of this schema –>
</xsd:schema>
9.5 Exceptions
In the event that a web feature service encounters an error parsing a DescribeFeatureType request, it shall raise an OperationParsingFailed exception as described in 7.5.
In the event that a web feature service encounters an error processing a DescribeFeatureType request, it shall raise an OperationProcessingFailed exception as described in 7.5.
10 GetPropertyValue operation
10.1 Introduction
The GetPropertyValue operation allows the value of a feature property or part of the value of a complex feature property to be retrieved from the data store for a set of features identified using a query expression (see 7.9).
10.2 Request
10.2.1 Request Semantics
Figure 15 describes the schema of a GetPropertyValue request.
10.2.2 XML Encoding
The following XML fragment defines the XML encoding for the GetPropertyValue operation:
<xsd:element name="GetPropertyValue" type="wfs:GetPropertyValueType"/>
<xsd:complexType name="GetPropertyValueType">
<xsd:complexContent>
<xsd:extension base="wfs:BaseRequestType">
<xsd:sequence>
<xsd:element ref="fes:AbstractQueryExpression"/>
</xsd:sequence>
<xsd:attribute name="valueReference" type="xsd:string" use="required"/>
<xsd:attribute name="resolvePath" type="xsd:string"/>
<xsd:attributeGroup ref="wfs:StandardPresentationParameters"/>
<xsd:attributeGroup ref="wfs:StandardResolveParameters"/>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
10.2.3 KVP Encoding
Table 16 defines the KVP encoding for the GetPropertyValue operation.
URL Component | O/Ma | Description |
---|---|---|
Common Keywords |
|
See Table 7. |
Adhoc Query Keywords |
|
See Table 8. |
Stored Query Keywords |
|
See Table 10. |
VALUEREFERENCE |
M |
See 10.2.4.3. |
RESOLVEPATH |
O |
See 7.9.2.4.7. |
a O = Optional, M = Mandatory |
10.2.4 Parameter discussion
10.2.4.1 Standard presentation parameters
See 7.6.3.
10.2.4.2 Standard resolve parameters
See 7.6.4.
10.2.4.3 valueReference parameter
The valueReference parameter is an XPath expression (see OGC 09-026r2, 7.4.4) that identifies a node, or child node of a property node of a feature whose value shall be retrieved from a server’s data store and reported in the response document.
The response shall be a text node or a list of element nodes that is the value of the node pointed to by the valueReference parameter.
In the case where the value is a reference to a remote resource, the valueOf() accessor function may be used to resolve the remote value.
There is a difference between how the valueReference parameter with the valueOf() XPath operator (see 7.3.2) behaves and what the standard resolve parameters control. The valueReference is used to express queries to determine the features/values in the result set while the standard resolve parameters (see 7.6.4) are used to determine how property values inside the selected features/values are encoded and presented in response documents.
EXAMPLE Consider the following XML fragment encoding an instances of the feature type myns:Person:
<myns:Person gml:id="p4467"
<gml:identifier
codespace=http://www.canadaSIN.com>424679360</gml:identifier>
<myns:lastName>Smith</myns:lastName>
<myns:firstName>Mary</myns:firstName>
<myns:age>18</myns:age>
<myns:sex>Female</myns:sex>
<myns:spouse xlink:href="#p4456"/>
<myns:location xlink:href = "#p101" />
<myns:mailAddress>
<myns:Address gml:id="a201">
<myns:streetName>Main St.</myns:streetName>
<myns:streetNumber>4</myns:streetNumber>
<myns:city>SomeCity</myns:city>
<myns:province>Someprovince</myns:province>
<myns:postalCode>X1X 1X1</myns:postalCode>
<myns:country>Canada</myns:country>
</myns:Address>
</myns:mailAddress>
<myns:phone>416-123-4567</myns:phone>
<myns:phone>416-890-1234</myns:phone>
<myns:livesIn xlink:href="#h32"/>
<myns:isDriving xlink:href="r1432"/>
</myns:Person>
A value reference of valueReference="lastName" would present the last name of the person, Smith in this example, in the response document.
A value reference of valueReference="myns:mailAddress/myns:Address/myns:city" would present the name of the city in which Mary Smith lives; SomeCity in this example.
A value reference of valueReference="valueOf(myns:location)" would present the location of Mary Smith in the response document by resolving the reference to the value with id "#p101".
10.2.4.4 AbstractQueryExpression parameter
The GetPropertyValue request operates on a set of features identified using a query expression.
This International Standard defines the elements wfs:Query (see 7.9.2.2) and wfs:StoredQuery (see 7.9.3.2) that may be used as query expressions in a GetPropertyValue operation and which are substitutable for fes:AbstractQueryExpression (see OGC 09-026r2, 6.2).
The definition of the wfs:Query element includes a projection clause (see 7.9.2.4.5.1) that specifies the feature properties to be presented in the result set. For GetPropertyValue requests, the projection clause for a query shall be ignored because the request defines the valueReference parameter to specifically identify which values shall appear in the response.[18]
Other elements may be defined as being substitutable for fes:AbstractQueryExpression however, this International Standard only assigns meaning to the wfs:Query and wfs:StoredQuery elements.
The KVP-encoding of an ad hoc query expression is defined in 7.9.2.3.
The KVP-encoding of a stored query expression is defined in 7.9.3.3.
KVP-encoded GetPropertyValue requests shall only contain query expressions of one type; either an ad hoc query expression or a stored query expression.
10.3 Response
10.3.1 Response Semantics
Figure 16 describes the schema of a GetPropertyValue response.
10.3.2 XML encoding
The following XML Schema fragment defines the response to a GetPropertyValue operation:
<xsd:element name="ValueCollection" type="wfs:ValueCollectionType"/>
<xsd:complexType name="ValueCollectionType">
<xsd:sequence>
<xsd:element ref="wfs:member" minOccurs="0" maxOccurs="unbounded"/>
<xsd:element ref="wfs:additionalValues" minOccurs="0"/>
<xsd:element ref="wfs:truncatedResponse" minOccurs="0"/>
</xsd:sequence>
<xsd:attributeGroup ref="wfs:StandardResponseParameters"/>
</xsd:complexType>
<xsd:element name="member" type="wfs:MemberPropertyType"/>
<xsd:complexType name="MemberPropertyType" mixed="true">
<xsd:choice minOccurs="0">
<xsd:any processContents="lax" namespace="##other"/>
<xsd:element ref="wfs:Tuple"/>
<xsd:element ref="wfs:SimpleFeatureCollection"/>
</xsd:choice>
<xsd:attribute name="state" type="wfs:StateValueType"/>
<xsd:attributeGroup ref="xlink:simpleLink"/>
</xsd:complexType>
<xsd:element name="Tuple" type="wfs:TupleType"/>
<xsd:complexType name="TupleType">
<xsd:sequence>
<xsd:element ref="wfs:member" minOccurs="2" maxOccurs="unbounded"/>
</xsd:sequence>
</xsd:complexType>
<xsd:element name="additionalValues">
<xsd:complexType>
<xsd:choice>
<xsd:element ref="wfs:ValueCollection"/>
<xsd:element ref="wfs:SimpleFeatureCollection"/>
</xsd:choice>
</xsd:complexType>
</xsd:element>
<xsd:element name="truncatedResponse">
<xsd:complexType>
<xsd:sequence>
<xsd:element ref="ows:ExceptionReport"/>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:simpleType name="StateValueType">
<xsd:union>
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:enumeration value="valid"/>
<xsd:enumeration value="superseded"/>
<xsd:enumeration value="retired"/>
<xsd:enumeration value="future"/>
</xsd:restriction>
</xsd:simpleType>
<xsd:simpleType>
<xsd:restriction base="xsd:string">
<xsd:pattern value="other:\w{2,}"/>
</xsd:restriction>
</xsd:simpleType>
</xsd:union>
</xsd:simpleType>
The wfs:ValueCollection element contains zero or more wfs:member elements that contain values from the set of values identified using the query expression in the GetPropertyValue operation. Values may encoded inline, within the wfs:member element or referenced via the xlink:href attribute. The xlink:href attribute declared as part of the xlink:simpleLink attribute group on the wfs:member element.
If additional values need to be included in the response document in order to satisfy the resolution of referenced resources (see 7.6.4), these objects shall be placed within the wfs:additionalValues element and resource references in the returned values shall be relocated to point to these local copies of the referenced resources. As specified in 7.6.4.5, the server shall also arrange that all unresolved nested resource references are appropriately relocated to point to the intended resources.
If a server encounters an exception after beginning the transmission of a response document to the client, the server shall terminate the response document by including the wfs:truncatedResponse element that shall contain an ows:ExceptionReport element reporting the exception (see 7.5). If the server successfully transmits the entire response document, the wfs:truncatedResponse element shall not be included in the response.
10.3.3 state parameter
Servers that do not support the Feature versions conformance class (see Table 1) shall not use the state parameter.
Servers that do support the Feature versions conformance class (see Table 1) shall use the state parameter to report the state of a versioned value in a response document. The value domain of state parameter is the string "retired", "superseded", "valid", "future" and any other string prefixed with the token "other:". The token "retired" shall be used to indicate that the value has been deleted from the underlying data store; "superseded" shall indicate that the particular version has been superseded by a newer version in the underlying data store; "valid" shall indicate that the version is the current version in the underlying data store; "future" shall indicate a value which is not yet valid. This may be for legal reasons, it may be used to distribute a proposed value, etc..
Any other string prefixed with the token "other:" may be used to report a server-specific versioned state. This International Standard does not assign any meaning to values prefixed with the token "other:".
10.3.4 Standard response parameters
For a discussion of the standard response parameters see 7.7.
10.4 Exceptions
If a WFS does not implement the GetPropertyValue operation then it shall generate an OperationNotSupported exception, indicating that the operation is not supported, if such a request is encountered.
In the event that a web feature service encounters an error parsing a GetPropertyValue request, it shall raise an OperationParsingFailed exception as described in 7.5.
In the event that a web feature service encounters an error processing a GetPropertyValue request, it shall raise an OperationProcessingFailed exception as described in 7.5.
11 GetFeature operation
11.1 Introduction
The GetFeature operation returns a selection of features from a data store. A WFS processes a GetFeature request and returns a response document to the client that contains zero or more feature instances that satisfy the query expressions specified in the request.
The canonical representation of features uses GML (see ISO 19136:2007), and the form of the GetFeature request is modelled after this representation of the result set. For this reason, it is necessary to have a clear understanding of how the General Feature Model (see ISO 19109) is mapped into the GML representation. The reference description of GML is given by ISO 19136:2007 but the salient aspects are summarized here.
In GML a feature is represented as an XML element. The name of the feature element indicates the Feature Type, conventionally given in UpperCamelCase (see OGC 06-121r3:2009, 11.6.2), such as xmml:BoreHole or myns:SecondaryCollege.
The content of a feature element is a set of elements that describes the feature in terms of a set of properties. Each child element of the feature element is a property. The name of the property indicates what the property means, conventionally given in lowerCamelCase (see OGC 06-121r3:2009, 11.6.2), such as gml:boundedBy or xmml:collarLocation.
The value of a property is given in-line by the content of the property element, or by-reference as the value of a resource identified in a link carried as an XML attribute of the property element. If the in-line form is used, then the content may be a literal (a number, text, etc), or may be structured using XML elements, but no assumptions can be made about the structure of the value of a property. In some cases the value of a property of feature may be another feature, for example a myns:School feature may have a property myns:frontsOn, whose value is a myns:Road, which will itself have further properties, etc.
11.1.1 Request Semantics
Figure 17 describes the schema of a GetFeature request.
11.1.2 XML encoding
The XML encoding of a GetFeature request is defined by the following XML Schema fragment:
<xsd:element name="GetFeature" type="wfs:GetFeatureType"/>
<xsd:complexType name="GetFeatureType">
<xsd:complexContent>
<xsd:extension base="wfs:BaseRequestType">
<xsd:sequence>
<xsd:element ref="fes:AbstractQueryExpression"
maxOccurs="unbounded"/>
</xsd:sequence>
<xsd:attributeGroup ref="wfs:StandardPresentationParameters"/>
<xsd:attributeGroup ref="wfs:StandardResolveParameters"/>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
A GetFeature request contains one or more query expressions. A query expression identifies a set of feature instances that shall be presented to a client in the response document. Query expressions in a GetFeature request shall independent on each other and may be executed in any order. The response collections, however, shall be presented in the order in which the query expressions are encountered in a GetFeature request.
11.1.3 KVP encoding
Table 17 defines the KVP-encoding for a GetFeature request.
URL Component | Description |
---|---|
Common Keywords |
See Table 7 for additional parameters that may be used in a KVP-encoded GetFeature request. |
Standard Presentation Parameters |
See Table 5. |
Standard Resolve Parameters |
See Table 6. |
Adhoc Query Keywords |
See Table 8. |
Stored Query Keywords |
See Table 10. |
11.1.4 Parameter discussions
11.1.4.1 Standard presentation parameters
See 7.6.3.
11.1.4.2 Standard resolve parameters
See 7.6.4.
11.1.4.3 AbstractQueryExpression parameter
The GetFeature request operates on a set of features identified using one or more query expressions.
For XML-encoded requests, this International Standard defines the elements wfs:Query (see 7.9.2.2) and wfs:StoredQuery (see 7.9.3.2) that may be used as query expressions in a GetFeature request and which are substitutable for fes:AbstractQueryExpression (see OGC 09-026r2, 6.2). Multiple wfs:Query and/or wfs:StoredQuery elements may be encoded into a single GetFeature request.
Other elements may be defined as being substitutable for fes:AbstractQueryExpression however, this International Standard only assigns meaning to the wfs:Query and wfs:StoredQuery elements.
The KVP-encoding of an ad hoc query expression is defined in 7.9.2.3. Multiple ad hoc query expressions may be encoded into a KVP-encoded request.
The KVP-encoding of a stored query expression is defined in 7.9.3.3. Only a single stored query expression may be encoded into a KVP-encoded request.
KVP-encoded requests shall only contain query expressions of one type; either ad hoc query expression(s) or a stored query expression.
11.2 Response
11.2.1 Response Semantics
Figure 18 describes the schema of a GetFeature response.
11.2.2 XML encoding
The response to a GetFeature request is an XML document with a root element, wfs:FeatureCollection, described by the following XML Schema fragment:
<xsd:element name="FeatureCollection"
type="wfs:FeatureCollectionType"
substitutionGroup="wfs:SimpleFeatureCollection"/>
<xsd:complexType name="FeatureCollectionType">
<xsd:complexContent>
<xsd:extension base="wfs:SimpleFeatureCollectionType">
<xsd:sequence>
<xsd:element ref="wfs:additionalObjects" minOccurs="0"/>
<xsd:element ref="wfs:truncatedResponse" minOccurs="0"/>
</xsd:sequence>
<xsd:attributeGroup ref="wfs:StandardResponseParameters"/>
<xsd:attribute name="lockId" type="xsd:string"/>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<xsd:element name="additionalObjects">
<xsd:complexType>
<xsd:choice>
<xsd:element ref="wfs:ValueCollection"/>
<xsd:element ref="wfs:SimpleFeatureCollection"/>
</xsd:choice>
</xsd:complexType>
</xsd:element>
<xsd:element name="SimpleFeatureCollection"
type="wfs:SimpleFeatureCollectionType"/>
<xsd:complexType name="SimpleFeatureCollectionType">
<xsd:sequence>
<xsd:element ref="wfs:boundedBy" minOccurs="0"/>
<xsd:element ref="wfs:member" minOccurs="0" maxOccurs="unbounded"/>
</xsd:sequence>
</xsd:complexType>
<xsd:element name="boundedBy" type="wfs:EnvelopePropertyType"/>
<xsd:complexType name="EnvelopePropertyType">
<xsd:sequence>
<xsd:any namespace="##other"/>
</xsd:sequence>
</xsd:complexType>
11.2.3 Parameter discussions
11.2.3.1 lockId parameter
The lockId parameter shall not be populated in response to GetFeature operation.
See 13.3.2 for a discussion of the lockId parameter.
11.2.3.2 state parameter
See the XML fragment in 10.3.2 for the declaration of the wfs:member element which contains the state attribute.
Servers that do not support the Feature versions conformance class (see Table 1) shall not use the state parameter.
Servers that do support the Feature versions conformance class shall use the state parameter to report the state of a versioned feature in a response document. The value domain of state parameter is the string "retired", "superseded", "valid" and any other string prefixed with the token "other:". The token "retired" shall be used to indicate that the features has been deleted from the underlying data store; "superseded" shall indicate that the particular version of a feature has been superseded by a newer version in the underlying data store; "valid" shall indicate that the feature version is the current version in the underlying data store; "future" shall indicate a value which is not yet valid. This may be for legal reasons, it may be used to distribute a proposed value, etc..
Any other string prefixed with the token "other:" may be used to report a server-specific versioned feature state. This International Standard does not assign any meaning to values prefixed with the token "other:".
11.2.3.3 Standard response parameters
See 7.7 for a description of the standard response parameters.
11.2.3.4 Single query response
If a GetFeature operation contains a single query expression a server shall respond with a wfs:FeatureCollection element containing zero or more wfs:member elements each containing or referencing a feature in the response set of a GetFeature operation.
11.2.3.5 Multiple query response
If a GetFeature operation contains multiple query expressions a server shall respond with a wfs:FeatureCollection element containing one or more wfs:member elements each containing a wfs:FeatureCollection element containing the response to one of the query expressions in the request.
Component feature collections may be encoded inline in the response document or referenced or both.
EXAMPLE 1 The following fragment illustrates a response to GetFeature operations that contains multiple query expressions where the component collections are encoded inline.
<?xml version="1.0" encoding="UTF-8"?>
<wfs:FeatureCollection
timeStamp="2008-08-01T22:47:02"
numberMatched="349" numberReturned="300"
xmlns:wfs="http://www.opengis.net/wfs/2.0"
xmlns:gml="http://www.opengis.net/gml/3.2"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.opengis.net/wfs/2.0
http://schemas.opengis.net/wfs/2.0.02.0/wfs.xsd
http://www.opengis.net/gml/3.2
http://schemas.opengis.net/gml/3.2.1/gml.xsd">
<wfs:member>
<wfs:FeatureCollection
timeStamp="2008-08-01T22:47:02"
numberMatched="15" numberReturned="15">
…
</wfs:FeatureCollection>
</wfs:member>
<wfs:member>
<wfs:FeatureCollection
timeStamp="2008-08-01T22:47:04"
numberMatched="257" numberReturned="257">
…
</wfs:FeatureCollection>
</wfs:member>
<wfs:member>
<wfs:FeatureCollection
timeStamp="2008-08-01T22:47:06"
numberMatched="77" numberReturned="28">
…
</wfs:FeatureCollection>
</wfs:member>
</wfs:FeatureCollection>
EXAMPLE 2 The following fragment illustrates a response to GetFeature operations that contains multiple query expressions where the component collections are referenced.
<?xml version="1.0" encoding="UTF-8"?>
<wfs:FeatureCollection
timeStamp="2008-08-01T22:47:02"
numberMatched="349" numberReturned="300"
xmlns:wfs="http://www.opengis.net/wfs/2.0"
xmlns:gml="http://www.opengis.net/gml/3.2"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.opengis.net/wfs/2.0
http://schemas.opengis.net/wfs/2.0.02.0/wfs.xsd
http://www.opengis.net/gml/3.2
http://schemas.opengis.net/gml/3.2.1/gml.xsd">
<wfs:member xlink:href="…"/>
…
<wfs:member xlink:href="…"/>
</wfs:FeatureCollection>
Feature members that satisfy more than one query expression in a GetFeature operation shall appear in one collection and be referenced by all others.
The order of the collections in the response document shall be the same as the order of the query expressions in the GetFeature request; although the queries may be processed in any order the server desires.
11.2.3.6 Join query response
If a GetFeature operations contain a query expression that is performing a join, a server shall use the wfs:Tuple element (see 10.3.2) to report all tuples of features that satisfy the join predicate.
EXAMPLE 1 The following XML fragment shows the response generated by a query expression joining three feature types ns1:FeatureTypeOne, ns1:FeatureTypeTwo and ns2:FeatureTypeThree:
<?xml version="1.0" encoding="UTF-8"?>
<wfs:FeatureCollection
timeStamp="2008-08-01T22:47:02"
numberMatched="200"
numberReturned="200"
xmlns:ns1="http://www.someserver.example.com/ns1"
xmlns:ns2="http://www.someserver.example.com/ns2"
xmlns:wfs="http://www.opengis.net/wfs/2.0"
xmlns:gml="http://www.opengis.net/gml/3.2"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.someserver.example.com/ns1 ./ns1.xsd
http://www.xomeserver.com/ns2 ./ns2.xsd
http://www.opengis.net/wfs/2.0
http://schemas.opengis.net/wfs/2.0.02.0/wfs.xsd
http://www.opengis.net/gml/3.2
http://schemas.opengis.net/gml/3.2.1/gml.xsd">
<wfs:boundedBy>
<gml:Envelope srsName="urn:ogc:def:crs:EPSG::4326http://www.opengis.net/def/crs/epsg/0/4326"><!-- [19] -->
<gml:lowerCorner>-32.7638053894043 104.1429748535156</gml:lowerCorner>
<gml:upperCorner>0 133.3553924560547</gml:upperCorner>
</gml:Envelope>
</wfs:boundedBy>
<wfs:member>
<wfs:Tuple>
<wfs:member>
<ns1:FeatureTypeOne>…</ns1:FeatureTypeOne>
</wfs:member>
<wfs:member>
<ns1:FeatureTypeTwo>…</ns1:FeatureTypeTwo>
</wfs:member>
<wfs:member>
<ns2:FeatureTypeThree>…</ns2:FeatureTypeThree>
</wfs:member>
</wfs:Tuple>
</wfs:member>
<wfs:member>
<wfs:Tuple>
<wfs:member>
<ns1:FeatureTypeOne>…</ns1:FeatureTypeOne>
</wfs:member>
<wfs:member>
<ns1:FeatureTypeTwo>…</ns1:FeatureTypeTwo>
</wfs:member>
<wfs:member>
<ns1:FeatureTypeThree>…</ns1:FeatureTypeThree>
</wfs:member>
</wfs:Tuple>
</wfs:member>
<wfs:member>
<wfs:Tuple>
<wfs:member xlink:href="…"/>
<wfs:member xlink:href="…"/>
<wfs:member>
<ns2:FeatureTypeThree>…</ns2:FeatureTypeThree>
</wfs:member>
</wfs:Tuple>
</wfs:member>
…
</wfs:FeatureCollection>
GetFeature operations that contain a mix of join and non-join query expressions can contain component feature collections containing a mixture of wfs:member and wfs:Tuple elements.
EXAMPLE 2 The following fragment shows a response document for a GetFeature operation that contains a mix of join and non-join query expressions.
<?xml version="1.0" encoding="UTF-8"?>
<wfs:FeatureCollection
timeStamp="2008-08-01T22:47:02"
numberMatched="349"
numberReturned="300"
xmlns="http://www.someserver.example.com/myns"
xmlns:wfs="http://www.opengis.net/wfs/2.0"
xmlns:gml="http://www.opengis.net/gml/3.2"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.someserver.example.com/myns ./RoadRail.xsd
http://www.opengis.net/wfs/2.0
http://schemas.opengis.net/wfs/2.0.02.0/wfs.xsd
http://www.opengis.net/gml/3.2
http://schemas.opengis.net/gml/3.2.1/gml.xsd">
<wfs:boundedBy>
<gml:Envelope srsName="urn:ogc:def:crs:EPSG::4326http://www.opengis.net/def/crs/epsg/0/4326"><!-- [20] -->
<gml:lowerCorner>-32.7638053894043 104.1429748535156</gml:lowerCorner>
<gml:upperCorner>0 133.3553924560547</gml:upperCorner>
</gml:Envelope>
</wfs:boundedBy>
<wfs:member>
<wfs:FeatureCollection
timeStamp="2008-08-01T22:47:02"
numberMatched="15"
numberReturned="15">
<wfs:member>…</wfs:member>
<wfs:member>…</wfs:member>
…
</wfs:FeatureCollection>
</wfs:member>
<wfs:member>
<wfs:FeatureCollection
timeStamp="2008-08-01T22:47:04"
numberMatched="257"
numberReturned="257">
<wfs:member>
<wfs:Tuple>
<wfs:member>…</wfs:member>
<wfs:member>…</wfs:member>
…
</wfs:Tuple>
</wfs:member>
<wfs:member>
<wfs:Tuple>
<wfs:member>…</wfs:member>
<wfs:member>…</wfs:member>
…
</wfs:Tuple>
</wfs:member>
…
</wfs:FeatureCollection>
</wfs:member>
<wfs:member>
<wfs:FeatureCollection
timeStamp="2008-08-01T22:47:06"
numberMatched="77"
numberReturned="28">
<wfs:member>…</wfs:member>
<wfs:member>…</wfs:member>
…
</wfs:FeatureCollection>
</wfs:member>
</wfs:FeatureCollection>
11.2.4 Additional objects
If additional objects need to be included in the response document in order to satisfy the resolution of referenced resources (see 7.6.4), these objects shall be placed within the wfs:additionalObjects element and resource references in the returned features shall be relocated to point to these local copies of the referenced resources. As specified in 7.6.4.5, the server shall also arrange that all unresolved nested resource references are appropriately relocated to point to the intended resources.
11.2.5 GetFeatureById response
Executing a GetFeature operation containing the GetFeatureById stored query (see 7.9.3.6) shall generate a response composed of a single feature encoded according to the values of the outputFormat parameter (see 7.6.3.7). The response shall only contain the feature XML without any of the normal containing elements generated as a result of executing a GetFeature operation (see 11.3.3.4, 11.3.3.5, 11.3.3.6).
In the event that the specified identifier does not correspond to any feature, the server shall respond with a NotFound exception as described in 7.5. Other expection conditions shall be handled as specified in Clause 11.4.[21]
11.2.6 Inheritance rules for srsName values
For convenience in constructing feature collection instances, the value of the srsName attribute on the gml:Envelope which is the value of the wfs:boundedBy property of a response feature collection shall be inherited by all directly expressed geometries in all properties of the members of the collection, unless overruled by the presence of a local srsName. Thus it is not necessary for a geometry to carry a srsName attribute, if it uses the same coordinate reference system as given on the wfs:boundedBy property of the envelope. Inheritance of the coordinate reference system continues to any depth of nesting, but if overruled by a local srsName declaration, then the new coordinate reference system is inherited by all its children in turn.[22]
11.3 Exceptions
In the event that a web feature service encounters an error parsing a GetFeature request, it shall raise an OperationParsingFailed exception as described in 7.5.
In the event that a web feature service encounters an error processing a GetFeature request, it shall raise an OperationProcessingFailed exception as described in 7.5.
12 LockFeature operation
12.1 Introduction
Web connections are inherently stateless. As a consequence of this, the semantics of serializable transactions are not preserved. To understand the issue, consider an update operation.
The client fetches a feature instance. The feature is then modified on the client side, and submitted back to the WFS via a Transaction request for update. Serializability is lost since there is nothing to guarantee that while the feature was being modified on the client side, another client did not come along and update that same feature in the database.
One way to ensure serializability is to require that access to data be done in a mutually exclusive manner; that is, while one transaction accesses a data item, no other transaction may modify the same data item. This may be accomplished by using locks that control access to the data.
The purpose of the LockFeature operation is to expose a long-term feature locking mechanism to ensure consistency. The lock is considered long term because network latency would make feature locks last relatively longer than native commercial database locks.
If a server implements the LockFeature operation, this fact shall be advertised in the server’s capabilities document (see 8.3.3).
12.2 Request
12.2.1 Request Semantics
Figure 19 describes the schema of a LockFeature request.
12.2.2 XML encoding
The following XML Schema fragment defines the XML encoding of a LockFeature request:
<xsd:element name="LockFeature" type="wfs:LockFeatureType"/>
<xsd:complexType name="LockFeatureType">
<xsd:complexContent>
<xsd:extension base="wfs:BaseRequestType">
<xsd:sequence>
<xsd:AbstractQueryExpression minOccurs="0" maxOccurs="unbounded"/><!-- [23] -->
</xsd:sequence>
<xsd:attribute name="lockId" type="xsd:string"/>
<xsd:attribute name="expiry" type="xsd:positiveInteger" default="300"/>
<xsd:attribute name="lockAction" type="wfs:AllSomeType" default="ALL"/>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<xsd:simpleType name="AllSomeType">
<xsd:restriction base="xsd:string">
<xsd:enumeration value="ALL"/>
<xsd:enumeration value="SOME"/>
</xsd:restriction>
</xsd:simpleType>
12.2.3 KVP encoding
Table 18 defines the KVP encoding for the LockFeature operation.
URL Component | O/Ma | Default | Description |
---|---|---|---|
Common Keywords |
|
|
See Table 7. |
Adhoc Query Keywords |
|
|
See Table 8. |
Stored Query Keywords |
|
|
See Table10. |
LOCKID |
O |
|
Specify an existing lock identifier for the purpose of resetting the lock expiry. |
EXPIRY |
O |
300 |
The number of seconds the lock shall persist before being cleared if no Transaction request is received to release the locks. |
LOCKACTION |
O |
ALL |
Specify how the lock shall be acquired. ALL indicates to all feature shall be locked in order for the operation to succeed, otherwise the operation shall raise a CannotLockAllFeatures exception. SOME indicates that the server shall lock as many features as possible; the operation shall always succeed although the returned lockId may not lock anything. |
a O = Optional, M = Mandatory |
12.2.4 Parameter discussions
12.2.4.1 AbstractQueryExpression parameter
The LockFeature request operates on a set of features identified using one or more query expressions.
For XML-encoded requests, this International Standard defines the elements wfs:Query (see 7.9.2.2) and wfs:StoredQuery (see 7.9.3.2) that may be used as query expressions in a LockFeature request and which are substitutable for fes:AbstractQueryExpression (see OGC 09-026r2, 6.2).
Other elements may be defined as being substitutable for fes:AbstractQueryExpression however, this International Standard only assigns meaning to the wfs:Query and wfs:StoredQuery elements.
The KVP-encoding of an ad hoc query expression is defined in 7.9.2.3. Multiple ad hoc query expressions may be encoded into a KVP-encoded request.
The KVP-encoding of a stored query expression is defined in 7.9.3.3. Only a single stored query expression may be encoded into a KVP-encoded request.
KVP-encoded requests shall only contain query expressions of one type; either ad hoc query expression(s) or a stored query expression.
12.2.4.2 lockId parameter
A lockId parameter specified within a LockFeature operations shall be used to reset the expiry time of an existing lock.
A LockFeature request shall include a lockId parameter or one or more fes:AbstractQueryExpression elements but not both.
If both a lockId parameter and one or more fes:AbstractQueryExpression elements are included in a LockFeature request then the server shall raise an OperationParsingFailed exception (see 7.5).[24]
EXAMPLE 1 The following XML-encoded request resets the lock expiry of the specified lock to 600 seconds:
<wfs:LockFeature lockId="1013" expiry="600"/>
Such a LockFeature operation shall be executed before the specified lock has expired; otherwise the server shall raise a LockHasExpired exception (see Table 3).
The expiry shall be reset relative to the time that the original lock was acquired.
EXAMPLE 2 If a lock was originally acquired for 300 seconds, and after 50 seconds the lock expiry is reset of 600 seconds, the lock shall remain valid for an additional 550 seconds.
12.2.4.3 Lock expiry parameter
The expiry parameter may be used to set a limit on how long a WFS shall hold a lock on feature in the event that a transaction is never issued that would release the lock.
The expiry limit is specified in number of seconds.
The expiry timer shall be started once the entire lock request has been processed and the lock response has been completely transmitted to the client.
Once the specified time period has elapsed, a WFS shall release the lock if it exists. Any further transactions issued against that lock using the same lock identifier shall fail and the service shall raise an InvalidParameterValue exception as described in 7.5.
If a value is not specified for the expiry parameter, the default expiry period shall be 300 s.
The expiry time of an existing lock can be extended as described in 12.2.4.2.
12.2.4.4 lockAction parameter
The optional lockAction parameter controls how feature locks are acquired.
A lock action of ALL indicates that the WFS shall acquire a lock on all requested feature instances. If all requested feature instances cannot be locked, then the operation shall fail, the service shall raise a CannotLockAllFeatures exception as specified in 7.5 and no feature instances shall remain locked.
A lock action of SOME indicates that the WFS shall acquire a lock on as many of the requested feature instances as it can.
The default lock action shall be ALL.
Figure 20 presents a state machine for the LockFeature operation.
12.2.5 State machine for WFS locking
This section defines the state machine for the lock state for a service that provides the WFS interface. The state diagram shows the allowed transitions between the states. All other state transitions are disallowed and are consider errors if exhibited by a service.
A service shall support the ability to lock more than one set of features where each feature may only be locked by one lock. Each of the locks is independent when viewed from the service defined by the WFS specification.