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.

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

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.

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)

All questions regarding this submission should be directed to the editor or the submitters:

Warning

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

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.

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.

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.

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.

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.

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.

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.

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.

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&amp;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.

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

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].

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.

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:

1. listing the feature types to join using the typeNames parameter (see 7.9.2.4.1)
2. 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.

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:

1. 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.
2. 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.
3. 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.

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.

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.

A server may optionally specify one or more of the constraints defined in Table 14 in its capabilities document (see 8.3.3).

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.

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&amp;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.

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.

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]

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.

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.