Web Feature Service Implementation Specification

OpenGIS Consortium Inc.

Edited by

Panagiotis A. Vretanos

Allan adoyle@intl-interfaces.com Doyle

International Interfaces, Inc.

Edric ekeighan@cubewerx.com Keighan

CubeWerx Inc.

Jonathan jrclark@intergraph.com Clark

Intergraph Corp.

Serge Serge.Margoulies@ionicsoft.com Margoulies

IONIC Software

Peter peterw@lsl.co.uk Woodsford

Laser-Scan Ltd.

1.0.0

Copyright © 1999, 2000, 2001, 2002 CubeWerx Inc.

Copyright © 1999, 2000, 2001, 2002 Intergraph Corp.

Copyright © 1999, 2000, 2001, 2002 IONIC Software s.a.

Copyright © 1999, 2000, 2001, 2002 Laser-Scan Limited

WARNING: The Open GIS Consortium (OGC) releases this specification to the public without warranty. It is subject to change without notice. This specification is currently under active revision by the OGC Technical Committee.

Requests for clarification and/or revision can be made by contacting the OGC at .

Permission to use, copy, and distribute this document in any medium for any purpose and without fee or royalty is hereby granted, provided that you include the above list of copyright holders and the entire text of this NOTICE.

We request that authorship attribution be provided in any software, documents, or other items or products that you create pursuant to the implementation of the contents of this document, or any portion thereof.

No right to create modifications or derivatives of OGC documents is granted pursuant to this license. However, if additional requirements (as documented in the Copyright FAQ at http://www.opengis.org/legal/ipr_faq.htm) are satisfied, the right to create modifications or derivatives is sometimes granted by the OGC to individuals complying with those requirements.

THIS DOCUMENT IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, OR TITLE; THAT THE CONTENTS OF THE DOCUMENT ARE SUITABLE FOR ANY PURPOSE; NOR THAT THE IMPLEMENTATION OF SUCH CONTENTS WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.

COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE DOCUMENT OR THE PERFORMANCE OR IMPLEMENTATION OF THE CONTENTS THEREOF.

The name and trademarks of copyright holders may NOT be used in advertising or publicity pertaining to this document or its contents without specific, written prior permission. Title to copyright in this document will at all times remain with copyright holders.

RESTRICTED RIGHTS LEGEND. Use, duplication, or disclosure by government is subject to restrictions as set forth in subdivision (c)(1)(ii) of the Right in Technical Data and Computer Software Clause at DFARS 252.227.7013

OpenGIS® is a trademark or registered trademark of Open GIS Consortium, Inc. in the United States and in other countries.

This document does not represent a commitment to implement any portion of this specification in any company's products.

OGC® Legal, IPR and Copyright Statements are found at http://www.opengis.org/legal/ipr.htm

The companies listed below have granted the Open GIS Consortium, Inc. (OGC) a nonexclusive, royalty-free, paid up, worldwide license to copy and distribute this document and to modify this document and distribute copies of the modified version.

Revision History
Revision 1.0.02002-09-19
Address RFC comments.
Revision 0.0.14?
Reformat document in ISO format; Relate document to OGC abstract specification (specifically Topic 12 / 19119); Include rules for property naming; Use XPath expressions for referencing properties in complex attributes; More synchronization between WMS and WFS with respect to keyword-value pair encoding; Add annex for conformance testing.
Revision 0.0.13?
Prepare document for RFC submission; include XML-Schema encoding of WFS interfaces; align URL-encoding with BSM
Revision 0.0.12?
Add complete list of contributors; align with latest GML 2.0 draft specification; add lock controls and versioning.
Revision 0.0.11?
Correct typographical errors.
Revision 0.0.10?
Server FeatureId and Filter elements into their own specification documents.
Revision 0.0.9?
Review U.S.Census revisions
Revision 0.0.8?
Review Galdos revisions
Revision 0.0.7?
Review LaserScan revisions
Revision 0.0.6?
Remove "Small XML-Schema Description Language"
Revision 0.0.5?
Define "Small XML-Schema Description Language"
Revision 0.0.4?
Use GML2 with application defined schema using XML-Schema. Remove dependency on featureType attribute.
Revision 0.0.3?
Define GET request semantics.
Revision 0.0.2?
Update <FeatureId> element to include <Scope>. Make handle attribute #IMPLIED. Add functions on properties and literals to <Filter>.
Revision 0.0.1?
First version derived from the OpenGIS Transaction Encoding Specification [3] and the Spatial Object Transfer Format (SOTF) [4] specification.

Table of Contents

1. Preface
2. Submitting organizations
3. Submission contact points
4. Changes to the OpenGIS Abstract Specification
5. Future work
6. Forward
7. Introduction
8. Scope
8.1. Geographic features
8.2. Processing requests
8.3. Operations
9. Conformance
10. Normative references
11. Terms and definitions
12. Conventions
12.1. Normative verbs
12.2. Abbreviated terms
12.3. Use of examples
13. Basic service elements
13.1. Introduction
13.2. Version numbering and negotiation
13.2.1. Version number form
13.2.2. Version changes
13.2.3. Appearance in requests and in service metadata
13.3. General HTTP request rules
13.3.1. Introduction
13.3.2. HTTP GET
13.3.3. HTTP POST
13.4. General HTTP response rules
13.5. Request encoding
13.6. Namespaces
14. Common elements
14.1. Feature identifier
14.1.1. Globally unique identifiers (Informative)
14.2. Feature state
14.3. Property names
14.4. Property references
14.4.1. Introduction
14.4.2. Xpath expressions
14.5. <Native> element
14.6. Filter
14.7. Exception reporting
14.8. Common XML attributes
14.8.1. Version attribute
14.8.2. Service attribute
14.8.3. Handle attribute
15. DescribeFeatureType operation
15.1. Introduction
15.2. Request
15.3. Response
15.3.1. Supporting multiple namespaces
15.4. Exception
15.5. Examples
16. GetFeature Operation
16.1. Introduction
16.2. Request
16.3. Response
16.4. Exception
16.5. Examples
17. LockFeature operation
17.1. Introduction
17.2. Request
17.2.1. Schema definition
17.2.2. State machine notation from UML
17.2.3. State machine for WFS locking
17.3. Response
17.4. Exception
17.5. Examples
18. Transaction operation
18.1. Introduction
18.2. Request
18.2.1. Schema definition
18.2.2. Attribute descriptions
18.2.3. <Transaction> element
18.2.4. <Insert> element
18.2.5. <Update> element
18.2.6. <Delete> element
18.3. Response
18.4. Exception
18.5. Examples
19. GetCapabilities
19.1. Introduction
19.2. Request
19.3. Response
19.3.1. Response schema
19.3.2. Capabilities
19.3.3. Service section
19.3.4. Capabilities Section
19.3.5. FeatureTypeList section
19.4. Exception
19.5. Examples
20. Keyword-value pair encoding
20.1. Introduction
20.1.1. A note about the examples
20.2. Request parameter rules
20.2.1. Parameter ordering and case
20.2.2. Parameter lists
20.3. Common request parameters
20.3.1. Version parameter
20.3.2. Request parameter
20.3.3. Bounding box
20.3.4. Vendor-specific parameters
20.4. Common parameters
20.5. Response
20.6. Exceptions
20.7. Operations
20.7.1. Introduction
20.7.2. DescribeFeatureType operation
20.7.2.1. Request
20.7.2.2. Examples
20.7.3. GetFeature & GetFeatureWithLock operation
20.7.3.1. Request
20.7.3.2. Examples
20.7.4. LockFeature operation
20.7.4.1. Request
20.7.4.2. Examples
20.7.5. Transaction
20.7.5.1. Request
20.7.5.2. Examples
20.7.6. GetCapabilities Operation
20.7.6.1. Request
20.7.6.2. Response
21. XML Schema definitions (Normative)
21.1. Introduction
21.2. OGC-exception.xsd
21.3. WFS-basic.xsd
21.4. WFS-transaction.xsd
21.5. WFS-capabilities.xsd
22. Conformance tests (normative)
Glossary
Bibliography

One important achievement of the Open GIS Consortium (OGC) Web Mapping Test bed (WMT1) initiative was the development of a large consensus around open web based interface specifications. Such specifications allow software vendors to implement their products using interoperable interfaces and provide end-users a larger pool of interoperable web based tools for geodata access and related geoprocessing services.

During the OGC WMT1 project, two web based draft specification documents were developed:

  1. OpenGIS Web Map Service Implementation Specification [1]

  2. OpenGIS Geography Markup Language (GML) 2.0 Implementation Specification

The first document specifies web interfaces based on a model supporting general request and response rules using Hypertext Transfer Protocol (HTTP) and the eXtensible Markup Language (XML). Web Map Server products have been developed as the result of the adoption by OGC of the OpenGIS Web Map Service Implementation Specification [1]. The interfaces defined in that specification include GetCapabilities, GetMap and GetFeatureInfo. The second document describes an encoding specification for geodata in XML. The encoding described in that specification is intended to enable the transport and storage of geographic information in XML including both properties and the geometry of geographic features.

This document (OpenGIS Web Feature Service Implementation Specification) takes the next logical step and proposes interfaces for describing data manipulation operations on geographic features using HTTP as the distributed computing platform. Data manipulation operations include the ability to:

  1. Create a new feature instance

  2. Delete a feature instance

  3. Update a feature instance

  4. Get or Query features based on spatial and non-spatial constraints

A Web Feature Service (WFS) request consists of a description of query or data transformation operations that are to be applied to one or more features. The request is generated on the client and is posted to a web feature server using HTTP. The web feature server then reads and (in a sense) executes the request.

The following companies submitted this specification to the OGC as a Request for Comment:

CubeWerx Inc. Edric Keighan 200 Rue Montcalm, Suite R-13 Hull, Quebec Canada J8Y 3B5 Intergraph Corp. Jonathan Clark 1881 Campus Commons Drive Reston, VA 20191 U.S.A IONIC Software Serge Margoulies 128 Avenue de l'Observatoire B-4000 LIEGE Belgium Laser-Scan Ltd. Peter Woodsford 101 Cambridgbe Science Park Milton Road Cambridge CB4 0FY U.K.

All questions regarding this submission should be directed to the Editor or to the WWW Mapping SIG chair:

Panagiotis A. Vretanos CubeWerx, Inc. 200 Rue Montcalm, Suite R-13 Hull, Quebec J8Y 3B5 CANADA +1 416 701 1985

Allan Doyle (WWW Mapping SIG Chair) International Interfaces, Inc. 948 Great Plain Ave. PMB-182 Needham, MA 02492 USA +1 781 433 2695

Additional contributors

Rob Atkinson (Social Change Online) Craig Bruce (CubeWerx) Jonathan Clark (Intergraph) Adrian Cuthbert (SpotOn MOBILE) Paul Daisey (U.S. Census) John Davidson John D. Evans (NASA) Ron Fresne (ObjectFX) Ignacio Guerrero (Intergraph) John Herring (Oracle Corp.) Sandra Johnson (Mapinfo) Edric Keighan (CubeWerx) Ron Lake (Galdos Systems Inc.) Jeff Lansing (Polexis) Seb Lessware (Laser-Scan Ltd.) Marwa Mabrouk (ESRI) Serge Margoulies (Ionic) Brian May (CubeWerx) Richard Martell (Galdos Systems Inc.) Aleksander Milanovic (Glados Systems Inc.) Dimitri Monie (Ionic) Paul Pilkington (Laser-Scan Ltd.) Keith Pomakis (CubeWerx) Christopher C. Pried (Polexis) Lou Reich (NASA) Carl Reed (Open GIS Consortium) Martin Schaefer (Cadcorp Ltd.) Lacey T. Sharpe (Intergraph Corp.) Raj R. Singh (Syncline Inc.) Bernard Snyers (Ionic) Daniel Specht (TEC) James T. Stephens (Lockheed Martin) Glenn Stowe (CubeWerx) Tom Strickland (Byers) Shuichi Takino (Dawn Corp.) Milan Trninic (Galdos Systems Inc.) John T. Vincent (Intergraph Corp.) Peter Woodsford (Laser-Scan Ltd.) Arliss Whitesize (BAE Systems) Nami Yamashita (Dawn Corp.)

No further revisions to the OGC Abstract Specification are required. The revisions previously approved for Topic 12, "Service Architecture," including definitions of the terms "operation", "interface" and "service" are relevant to and sufficient for this specification. The essential operation of a web feature service, as a feature access and management service, is described in section 8.3.3 of Topic 12.

Further work is desirable in the next version on the following work items.

  1. XLink traversal capabilities,

  2. UML models,

  3. Change the abstract specification to include complex features.

  4. Develop specific conformance tests.

  5. GML3 integration.

Attention is drawn to the possibility that some of the elements of this standard may be the subject of patent rights. Open GIS Consortium Inc. shall not be held responsible for identifying any or all such patent rights. However, to date, no such rights have been claimed or identified.

This version of the specification cancels and replaces all previous versions.

Normative annexes

Annexes A and B are normative.

The OGC Web Map Service allows a client to overlay map images for display served from multiple Web Map Services on the Internet. In a similar fashion, the OGC Web Feature Service allows a client to retrieve geospatial data encoded in Geography Markup Language (GML) from multiple Web Feature Services.

The requirements for a Web Feature Service are:

  1. The interfaces must be defined in XML.

  2. GML must be used to express features within the interface.

  3. At a minimum a WFS must be able to present features using GML.

  4. The predicate or filter language will be defined in XML and be derived from CQL as defined in the OpenGIS Catalogue Interface Implementation Specification.

  5. The datastore used to store geographic features should be opaque to client applications and their only view of the data should be through the WFS interface.

  6. The use of a subset of XPath expressions for referencing properties.

The purpose of this document is to describe the Web Feature Service interface, as illustrated in figure 1.

Figure 1. Figure 1 - Web feature service

Figure 1 - Web feature service

This document is derived from a large consensus among its contributors and takes its roots from two independently proposed specifications titled OGC Transaction Encoding Specification [3] and Spatial Object Transfer Format (SOTF) [4]. In addition a number of concepts, common among all OGC services, are taken from the Web Map Service Implementation Specification [1].

This document describes the OGC Web Feature Service (WFS) operations. The WFS operations support INSERT, UPDATE, DELETE, QUERY and DISCOVERY operations on geographic features using HTTP as the distributed computing platform.

In the context of this document, a transaction is a logical unit of work that is composed of one or more data manipulation operations. Since the manner in which geographic features are persistently stored is not addressed in this document, no transaction semantics, such as atomic failure, are assumed to exist. It is the function of a web feature service, in its interaction with the data storage system used to persistently store features, to ensure that changes to data are consistent. However, the document also acknowledges the fact that many systems do support standard concurrent transaction semantics and so proposes optional operations that will allow a web feature service to take advantage of such systems (e.g. relational database systems based on SQL).

This document adopts the same concept of a geographic feature as described in the OGC Abstract Specification (http://www.opengis.org/techno/spec.htm) and interpreted in the OpenGIS© Geographic Markup Language(GML) Implementation Specification [2]. That is to say that the state of a geographic feature is described by a set of properties where each property can be thought of as a {name, type, value} tuple. The name and type of each feature property is determined by its type definition. Geographic features are those that may have at least one property that is geometry-valued. This, of course, implies that features can be defined with no geometric properties at all. The geometries of geographic features are restricted to what OGC calls simple geometries. A simple geometry is one for which coordinates are defined in two dimensions and the delineation of a curve is subject to linear interpolation. The traditional 0, 1 and 2-dimensional geometries defined in a 2-dimensional spatial reference system are represented by points, line strings and polygons. In addition, the OGC geometry model allows for geometries that are collections of other geometries - either homogeneous multi-point, multi-line string, and multi-polygon collections or heterogeneous geometry collections. Finally, GML allows features that have complex or aggregate non-geometric properties.

This section of the document outlines, in general terms, the protocol to be followed in order to process web feature service requests. Processing requests would proceed as follows:

  1. A client application would request a capabilities document from the WFS. Such a document contains a description of all the operations that the WFS supports and a list of all feature types that it can service.

  2. A client application (optionally) makes a request to a web feature service for the definition of one or more of the feature types that the WFS can service.

  3. Based on the definition of the feature type(s), the client application generates a request as specified in this document.

  4. The request is posted to a web server.

  5. The WFS is invoked to read and service the request.

  6. When the WFS has completed processing the request, it will generate a status report and hand it back to the client. In the event that an error has occurred, the status report will indicate that fact.

To support transaction and query processing, the following operations are defined:

GetCapabilities

A web feature service must be able to describe its capabilities. Specifically, it must indicate which feature types it can service and what operations are supported on each feature type.

DescribeFeatureType

A web feature service must be able, upon request, to describe the structure of any feature type it can service.

GetFeature

A web feature service must be able to service a request to retrieve feature instances. In addition, the client should be able to specify which feature properties to fetch and should be able to constrain the query spatially and non-spatially.

Transaction

A web feature service may be able to service transaction requests. A transaction request is composed of operations that modify features; that is create, update, and delete operations on geographic features.

LockFeature

A web feature service may be able to process a lock request on one or more instances of a feature type for the duration of a transaction. This ensures that serializable transactions are supported.

Based on the operation descriptions above, two classes of web feature services can be defined:

Basic WFS

A basic WFS would implement the GetCapabilities, DescribeFeatureType and GetFeature operations. This would be considered a READ-ONLY web feature service.

Transaction WFS

A transaction web feature service would support all the operations of a basic web feature service and in addition it would implement the Transaction operation. Optionally, a transaction WFS could implement the LockFeature operation.

Figure 2 is a simplified protocol diagram illustrating the messages that might be passed back and forth between a client application and a web feature service in order to process a typical transaction request. The elements referenced in the diagram are defined in this document.

Figure 2. Protocol diagram

Protocol diagram

Conformance with this specification shall be checked using all the relevant tests specified in Annex D (normative). The framework, concepts, and methodology for testing, and the criteria to be achieved to claim conformance are specified in ISO 19105: Geographic information - Conformance and Testing.

  1. Bradner, Scott, "RFC 2119 Key words for use in RFCs to Indicate Requirement Levels," March 1997, ftp://ftp.isi.edu/in-notes/rfc2119.txt.

  2. Cox, S., Cuthbert, A., Lake, R., and Martell, R. (eds.), "OpenGIS Implementation Specification #02-009: OpenGIS© Geography Markup Language (GML) Implementation Specification, version 2.1.1", April 2002

  3. Vretanos, Panagiotis (ed.), "OpenGIS Implementation Specification #01-067: Filter Encoding Implementation Specification", May 2001

  4. Percivall, George, ed., “The OpenGIS Abstract Specification, Topic 12: OpenGIS Service Architecture”, 2002

  5. Bray, Paoli, Sperberg-McQueen, eds., "Extensible Markup Language (XML) 1.0", 2nd edition, October 2000, W3C Recommendation, http://www.w3.org/TR/2000/REC-xml.

  6. Beech, David, Maloney, Murry, Mendelson, Noah, Thompson, Harry S., “XML Schema Part 1: Structures”, May 2001, W3C Recommendation, http://www.w3c.org/TR/xmlschema-1.

  7. Bray, Hollander, Layman, eds., “Namespaces In XML”, January 1999, W3C Recommendation, http://www.w3.org/TR/2000/REC-xml-names.

  8. Clark, James, DeRose, Steve, “XML Path Language (XPATH), Version 1.0”, November 1999, W3C Recommendation, http://www.w3c.org/TR/XPath.

  9. Fielding et. al., "Hypertext Transfer Protocol – HTTP/1.1," IETF RFC 2616, June 1999, http://www.ietf.org/rfc/rfc2616.txt.

  10. Berners-Lee, T., Fielding, N., and Masinter, L., "Uniform Resource Identifiers (URI): Generic Syntax", IETF RFC 2396, http://www.ietf.org/rfc/rfc2396.txt.

  11. National Center for Supercomputing Applications, "The Common Gateway Interface," http://hoohoo.ncsa.uiuc.edu/cgi/.

  12. Freed, N. and Borenstein N., "Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies", IETF RFC 2045, November 1996, http://www.ietf.org/rfc/rfc2045.txt.

  13. Internet Assigned Numbers Authority, http://www.isi.edu/in-notes/iana/assignments/media-types/.

For the purposes of this document, the following terms and definitions apply.

4.1 operation

pecification of a transformation or query that an object may be called to execute [4]

4.2 interface

a named set of operations that characterize the behavior of an entity [4]

4.3 service

a distinct part of the functionality that is provided by an entity through interfaces [4]

4.4 service instance

an actual implementation of a service; service instance is synonymous with server

4.5 client

a software component that can invoke an operation from a server

4.6 request

an invocation by a client of an operation.

4.7 response

the result of an operation returned from a server to a client.

4.8 capabilities XML

service-level metadata describing the operations and content available at a service instance

4.9 spatial reference system

as defined in ISO19111

4.10 opaque

not visible, accessible or meaningful to a client application

In the sections labeled as normative, the key words "must", "must not", "required", "shall", "shall not", "should", "should not", "recommended", "may", and "optional" in this document are to be interpreted as described in Internet RFC 2119 [1].

CGICommon Gateway Interface
DCPDistributed Computing Platform
DTDDocument Type Definition
EPSGEuropean Petroleum Survey Group
GISGeographic Information System
GMLGeography Markup Language
HTTPHypertext Transfer Protocol
IETFInternet Engineering Task Force
MIMEMultipurpose Internet Mail Extensions
OGCOpen GIS Consortium
OWSOGC Web Service
URLUniform Resource Locator
WFSWeb Feature Service
XMLExtensible Markup Language

This specification makes extensive use of XML examples. They are meant to illustrate the various aspects of a web feature service discussed in this specification. While every effort has been made to ensure that the examples are well formed and valid, this goal was sacrificed for the sake of clarity in many cases. For example, many examples are formatted in a specific way to highlight a particular aspect that would render the example invalid from the perspective of an XML validation tool. Further, most examples reference fictitious servers and data.

Thus, this specification does not assert that any XML or keyword-value pair encoded example, copied from this document, will necessarily execute correctly or validate using a particular XML validation tool. Only sections marked as normative should be expected to be well formed and valid XML or XML Schema documents.

This section describes aspects of OGC Web Feature Service behavior that are independent of particular operations or are common to several operations or interfaces.

The published specification version number contains three positive integers, separated by decimal points, in the form "x.y.z". The numbers "y" and "z" will never exceed 99. Each OWS specification is numbered independently.

A particular specification's version number shall be changed with each revision. The number shall increase monotonically and shall comprise no more than three integers separated by decimal points, with the first integer being the most significant. There may be gaps in the numerical sequence. Some numbers may denote experimental or interim versions. Service instances and their clients need not support all defined versions, but must obey the negotiation rules below.

An OWS Client may negotiate with a Service Instance to determine a mutually agreeable specification version. Negotiation is performed using the GetCapabilities operation [sec. 12] according to the following rules.

All Capabilities XML must include a protocol version number. In response to a GetCapabilities request containing a version number, an OGC Web Service must either respond with output that conforms to that version of the specification, or negotiate a mutually agreeable version if the requested version is not implemented on the server. If no version number is specified in the request, the server must respond with the highest version it understands and label the response accordingly.

Version number negotiation occurs as follows:

  1. If the server implements the requested version number, the server must send that version.

  2. If the client request is for an unknown version greater than the lowest version that the server understands, the server must send the highest version less than the requested version.

  3. If the client request is for a version lower than any of those known to the server, then the server must send the lowest version it knows.

  4. If the client does not understand the new version number sent by the server, it may either cease communicating with the server or send a new request with a new version number that the client does understand, but which is less than that sent by the server (if the server had responded with a lower version).

  5. If the server had responded with a higher version (because the request was for a version lower than any known to the server), and the client does not understand the proposed higher version, then the client may send a new request with a version number higher than that sent by the server.

The process is repeated until a mutually understood version is reached, or until the client determines that it will not or cannot communicate with that particular server.

Example 1. Example 1:

Server understands versions 1, 2, 4, 5 and 8. Client understands versions 1, 3, 4, 6, and 7. Client requests version 7. Server responds with version 5. Client requests version 4. Server responds with version 4, which the client understands, and the negotiation ends successfully.

Example 2. Example 2:

Server understands versions 4, 5 and 8. Client understands version 3. Client requests version 3. Server responds with version 4. Client does not understand that version or any higher version, so negotiation fails and client ceases communication with that server.

At present, the only distributed computing platform (DCP) explicitly supported by OGC Web Services is the World Wide Web itself, or more specifically, Internet hosts implementing the Hypertext Transfer Protocol (HTTP)[9]. Thus the Online Resource of each operation supported by a service instance is located by an HTTP Uniform Resource Locator (URL). The URL may be different for each operation, or the same, at the discretion of the service provider. Each URL must conform to the description in [9], but is otherwise implementation-dependent; only the parameters comprising the service request itself are mandated by the OGC Web Services specifications.

HTTP supports two request methods: GET and POST. One or both of these methods may be defined for a particular OGC Web Service type and offered by a service instance. The use of the Online Resource URL differs in each case.

An Online Resource URL intended for HTTP GET requests, is, in fact, only a URL prefix to which additional parameters must be appended in order to construct a valid Operation request. A URL prefix is defined as an opaque string including the protocol, hostname, optional port number, path, a question mark '?', and, optionally, one or more server-specific parameters ending in an ampersand '&'. The prefix uniquely identifies the particular service instance. A client appends the necessary request parameters as name/value pairs in the form "name=value&". The resulting URL must be valid according to the HTTP Common Gateway Interface (CGI) standard [7], which mandates the presence of '?' before the sequence of query parameters and the '&' between each parameter. As with all CGI applications, the query URL is encoded [10] to protect special characters.

The URL prefix must end in either a '?' (in the absence of additional server-specific parameters) or a '&'. In practice, however, Clients should be prepared to add a necessary trailing '?' or '&' before appending the Operation parameters defined in this specification in order to construct a valid request URL.

Table 1 summarizes the components of an operation request URL.

Table 1. Table 1 – A general OGC Web Service Request

URL ComponentDescription
http://host[:port]/path?{name[=value]&}URL prefix of service operation. [ ] denotes 0 or 1 occurrence of an optional part; {} denotes 0 or more occurrences. The prefix is entirely at the discretion of the service provider.
name=value&One or more standard request parameter name/value pairs defined by an OGC Web Service. The actual list of required and optional parameters is mandated for each operation by the appropriate OWS specification.

An Online Resource URL intended for HTTP POST requests is a complete and valid URL to which Clients transmit encoded requests in the body of the POST document. A WFS must not require additional parameters to be appended to the URL in order to construct a valid target for the Operation request.

Upon receiving a valid request, the service must send a response corresponding exactly to the request as detailed in the appropriate specification. Only in the case of Version Negotiation (described above) may the server offer a differing result.

Upon receiving an invalid request, the service must issue a Service Exception as described in Section 7.7.

Note

As a practical matter, in the WWW environment a client should be prepared to receive either a valid result, or nothing, or any other result. This is because the client may itself have formed a non-conforming request that inadvertently triggered a reply by something other than an OGC Web Service, because the Service itself may be non-conforming.

Response objects must be accompanied by the appropriate Multipurpose Internet Mail Extensions (MIME) type [9] for that object.

Response objects should be accompanied by other HTTP entity headers as appropriate and to the extent possible. In particular, the Expires and Last-Modified headers provide important information for caching; Content-Length may be used by clients to know when data transmission is complete and to efficiently allocate space for results, and Content-Encoding or Content-Transfer-Encoding may be necessary for proper interpretation of the results.

This document defines two methods of encoding WFS requests. The first uses XML as the encoding language. The second method uses keyword-value pairs to encode the various parameters of a request. An example of a keyword value pair is:

"REQUEST=GetCapabilities"

where "REQUEST" is the keyword and "GetCapabilities" is the value. In both cases, the response to a request or exception reporting must be identical.

Table 2 correlates WFS operations and their encoding semantics as defined in this specification.

Table 2. Table 2 – Operation Request Encoding

OperationRequest Encoding
GetCapabilitiesXML & KVP
DescribeFeatureTypeXML & KVP
GetFeature / GetFeatureWithLockXML & KVP
LockFeatureXML & KVP
TransactionXML & limited KVP

KVP = keyword-value pair

This document mandates the use of GML for the XML encoding of the state of geographic features. A complete description of this encoding can be found in document [2].

Namespaces (17) are used to discriminate XML vocabularies from one another. For the WFS there are three normative namespace definitions, namely:

A given WFS implementation will make use of one or more GML Application Schemas and these schemas will use, in turn, one or more application namespaces (e.g. http://www.someserver.com/myns). While many of the examples in this document use a single namespace, multiple namespaces can be used, as shown section 11.2.6.

This document assumes that every feature instance that a particular WFS implementation can operate upon is uniquely identifiable. That is to say, when a WFS implementation reports a feature identifier for a feature instance, that feature identifier is unique to the server and can be used to repeatedly reference the same feature instance (assuming it has not been deleted). It is further assumed that a feature identifier is encoded as described in the OpenGIS© Filter Encoding Implementation Specification [3]. A feature identifier can be used wherever a feature reference is required. For reference purposes, the XML Schema fragment that defines the feature identifier element is copied from the filter encoding specification:

<xsd:element name="FeatureId" type="ogc:FeatureIdType"/>
<xsd:complexType name="FeatureIdType">
   <xsd:attribute name="fid" type="xsd:anyURI" use="required"/>
</xsd:complexType>

The purpose of the feature identifier is to make database operations possible.

For the purposes of a web feature service, a locally unique identifier is sufficient. However, there is a need within OGC web services to have unique identifiers for objects of all kinds. The approach thus far has been to reference objects using independent scope and feature-id components, where the scope it the URL of the server serving a feature and the feature-id is the local identifier for the feature. This approach, however, may be awkward to transport and use in other contexts, such as in a registry if one wanted to create metadata for a single repository data instance (such as a satellite image).

The purpose of this section of the specification is to point out that a single globally-unique string would be more convenient to use in multiple contexts, and that such a string may be generated by a web feature service using some combination of the URL of the service and the local identifier.

This string could be used as if it were fully opaque in many contexts, but it would be more useful if it were actually a URL or URN which could be used to directly access the object it identifies in the native format of the object. The encoding of the URL or URN would be entirely implementation-specific. One note on the use of URNs: not many implementations will actually be able to resolve and fetch data objects; it may be mostly only usable as a unique identifier string.

Using a URL or URN is helpful for applications that need only simple access to the raw objects since no interface details need to be known. This mode of access/identification is also helpful for integration with high-level XML technologies such as RDF or XSLT, and even for debugging purposes.

The definition of features served by a WFS is provided by a GML application schema. Section 8 describes how a client can request an XML document containing the GML application schema definition of one or more feature types served by a WFS. Such application schema definitions shall conform to the OpenGIS Geography Markup Language(GML) Implementation Specification, version 2.1.1 [2].

A client application uses the GML application schema definition of a feature type to refer to feature instances of that feature type, and to refer to the names and types of all the properties of those feature instances. The values of all properties of a feature instance constitute the state of that feature instance. A client application references feature instances by the name of their feature type and the names and values of feature properties. A client application asks a transactional WFS to alter the state of a feature through insert, update, and delete operation requests.

A web feature service refers to feature property names defined in a GML application schema. However, since the state of a feature must be expressed in GML and thus XML, the property names used by a web feature service must also be valid element and attribute names as described in the Extensible Markup Language (XML) 1.0 [5] specification. In addition, property names may be namespace qualified as described in Namespaces in XML [7] . The following definitions are taken from sections 2 & 3 of that document:

[4]  NCName ::=  (Letter | '_') (NCNameChar)*                          
/*  An XML Name, minus the ":" */
[5]  NCNameChar ::=  Letter | Digit | '.' | '-' | '_' | CombiningChar | Extender
[6]  QName ::=  (Prefix ':')? LocalPart
[7]  Prefix ::=  NCName
[8]  LocalPart ::=  NCName

The definitions of the components Letter, Digit, CombiningChar and Extender are defined in annex B of [5].

Example 3. Example

Examples of valid property names are:

Age, Temperature, _KHz, myns:INWATERA_1M.WKB_GEOM

Examples of invalid property names are:

+Domain, 123_SomeName

As mentioned in the introduction, GML allows geographic features to have complex or aggregate non-geometric properties. A problem thus arises about how such properties should be referenced in the various places where property references are required (e.g. query and filter expressions). A WFS must use XPath [8] expressions, as defined in this document, for referencing the properties and sub-properties of a feature encoded as XML elements or attributes.

The XML Path Language [8] specification is a language for addressing parts of a XML document, or in the case of this specification, for referencing feature properties referred to by means of XML elements or attributes.

This specification does not require a WFS implementation to support the full XPath language. In order to keep the implementation entry cost as low as possible, this specification mandates that a WFS implementation must support the following subset of the XPath language:

  1. A WFS implementation must support abbreviated relative location paths.

  2. Relative location paths are composed of one or more steps separated by the path separator '/'.

  3. The first step of a relative location path may correspond to the root element of the feature property being referenced or to the root element of the feature type with the next step corresponding to the root element of the feature property being referenced.

  4. Each subsequent step in the path must be composed of the abbreviated form of the child:: axis specifier and the name of the feature property encoded as the principal node type of element. The abbreviated form of the child:: axis specifier is to simply omit the specifier from the location step.

  5. Each step in the path may optionally contain a predicate composed of the predicate delimiters '[' and ']' and a number indicating which child of the context node is to be selected. This allows feature properties that may be repeated to be specifically referenced.

  6. The final step in a path may optionally be composed of the abbreviated form of the attribute:: axis specifier, '@', and the name of a feature property encoded as the principal node type of attribute.

Example 4. Example

To practically illustrate the use of XPath expressions for referencing the properties of a complex feature (encoded as elements or attributes), consider the fictitious complex feature Person defined by the following XML Schema document:

<?xml version="1.0" ?>
<schema
   targetNamespace="http://www.someserver.com/myns"
   xmlns:myns="http://www.someserver.com/myns"
   xmlns:gml="http://www.opengis.net/gml"
   xmlns:xsd="http://www.w3.org/2001/XMLSchema"
   xmlns="http://www.w3.org/2001/XMLSchema"
   elementFormDefault="qualified"
   version="1.0">

   <import namespace="http://www.opengis.net/gml"
           schemaLocation="../gml/2.1/feature.xsd"/>

   <element name="Person" type="myns:PersonType"
            substitutionGroup="gml:_Feature"/>
   <complexType name="PersonType">
      <complexContent>
         <extension base="gml:AbstractFeatureType">
            <sequence>
               <element name="LastName" nillable="true">
                  <simpleType>
                     <restriction base="string">
                        <maxLength value="30"/>
                     </restriction>
                  </simpleType>
               </element>
               <element name="FirstName" nillable="true">
                  <simpleType>
                     <restriction base="string">
                        <maxLength value="10"/>
                     </restriction>
                  </simpleType>
               </element>
               <element name="Age" type="integer" nillable="true"/>
               <element name="Sex" type="string"/>
               <element name="Spouse">
                  <complexType>
                     <attribute name="sin" type="xsd:anyURI" use="required" />
                  </complexType>
               </element>
               <element name="Location" 
                        type="gml:PointPropertyType"
                        nillable="true"/>
               <element name="Address" type="myns:AddressType" nillable="true"/>
               <element name="Phone" type="xsd:string"
                        minOccurs="0" maxOccurs="unbounded"/>
            </sequence>
            <attribute name="sin" type="xsd:anyURI" use="required"/>
         </extension>
      </complexContent>
   </complexType>

   <complexType name="AddressType">
      <sequence>
         <element name="StreetName" nillable="true">
            <simpleType>
               <restriction base="string">
                  <maxLength value="30"/>
               </restriction>
            </simpleType>
         </element>
         <element name="StreetNumber" nillable="true">
            <simpleType>
               <restriction base="string">
                  <maxLength value="10"/>
               </restriction>
            </simpleType>
         </element>
         <element name="City" nillable="true">
            <simpleType>
               <restriction base="string">
                  <maxLength value="30"/>
               </restriction>
            </simpleType>
         </element>
         <element name="Province" nillable="true">
            <simpleType>
               <restriction base="string">
                  <maxLength value="30"/>
               </restriction>
            </simpleType>
         </element>
         <element name="PostalCode" nillable="true">
            <simpleType>
               <restriction base="string">
                  <maxLength value="15"/>
               </restriction>
            </simpleType>
         </element>
         <element name="Country" nillable="true">
            <simpleType>
               <restriction base="string">
                  <maxLength value="30"/>
               </restriction>
            </simpleType>
         </element>
      </sequence>
   </complexType>
</schema>

Note that the property Address is a complex property of type AddressType. An example instance of the feature Person might be:

<?xml version="1.0" ?>
<myns:Person
   sin="111222333" 
   xmlns:myns="http://www.opengis.net/myns"
   xmlns:gml="http://www.opengis.net/gml"
   xmlns:xlink="http://www.w3.org/1999/xlink"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://www.opengis.net/myns Person.xsd">

   <myns:LastName>Smith</myns:LastName>
   <myns:FirstName>Fred</myns:FirstName>
   <myns:Age>35</myns:Age>
   <myns:Sex>Male</myns:Sex>
   <myns:Spouse sin="444555666" />
   <myns:Location>
      <gml:Point><gml:coordinates>15,15</gml:coordinates></gml:Point>
   </myns:Location>
   <myns:Address>
      <myns:StreetName>Main St.</myns:StreetName>
      <myns:StreetNumber>5</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:Phone>416-123-4567</myns:Phone>
   <myns:Phone>416-890-1234</myns:Phone>
</myns:Person>

Using XPath [8] expressions, each property of a Person feature can be referenced as follows (omitting the namespace qualifiers for clarities sake):

LastName
FirstName
Age
Sex
Source
Location
Address
Address/StreetNumber
Address/StreetName
Address/City
Address/Province
Address/Postal_Code
Address/Country
Phone[1]
Phone[2]

Notice that in this instance, each relative location path begins with the root element of the feature property being referenced. This simply corresponds to the name of the feature property. Optionally, each feature property may be referenced with the relative location path beginning with root element of the feature (i.e. the name of the feature type). Thus the LastName property could be reference as Person/LastName, the City property could be referenced as Person/Address/City and so on.

Each step of the path is composed of the abbreviated child:: axis specifier (i.e. the axis specifier child:: is omitted) and the name of the specified property which is of node type element.

The element Phone appears multiple times and the predicates [1] and [2] are used to indicate the specific elements. The predicate [1] is used to indicate the first occurrence of the Phone element. The predicate [2] is used to indicate the second occurrence of the Phone element.

In addition, the sin [1] attribute on the <Person> and <Spouse> elements can be referenced using the following XPath [8] expressions:

Person/@sin
Person/Spouse/@sin

In these cases the final step of the path contains the abbreviated axis specifier attribute:: (i.e. @) and the node type is attribute (i.e. sin in this case).

It is clear that an open interface can only support a certain common set of capabilities. The <Native> element is intended to allow access to vendor specific capabilities of any particular web feature server or datastore.

The <Native> element is defined by the following XML Schema fragment:

<xsd:element name="Native" type="wfs:NativeType"/>
<xsd:complexType name="NativeType">
   <xsd:any />
   <xsd:attribute name="vendorId" type="xsd:string" use="required"/>
   <xsd:attribute name="safeToIgnore" type="xsd:boolean" use="required"/>
</xsd:complexType>

The <Native> element simply contains the vendor specific command or operation.

The vendorId attribute is used to identify the vendor that recognizes the command or operation enclosed by the <Native> element. The attribute is provided as a means of allowing a web feature service to determine if it can deal with the command or not.

The safeToIgnore attribute is used to guide the actions of a web feature service when the <Native> command or operation is not recognized. The safeToIgnore attribute has two possible values True or False. The values have the following meanings:

safeToIgnore=False

A value of False indicates that the <Native> element cannot be ignored and the operation that the element is associated with must fail if the web feature service cannot deal with it.

safeToIgnore=True

A value of True indicates that the <Native> element can be safely ignored.

Example 5. Example

This example illustrates the use of the <Native> element to enable a special feature of a SQL-based relational database. In this instance, the element indicates that this is an Oracle command and that the command can be safely ignored.

<Native vendorId="Oracle" safeToIgnore="True">
ALTER SESSION ENABLE PARALLEL DML
</Native>

A filter is used to define a set of feature instances that are to be operated upon. The operating set can be comprised of one or more enumerated features or a set of features defined by specifying spatial and non-spatial constraints on the geometric and scalar properties of a feature type. Filter specifications shall be encoded as described in the OGC Filter Encoding Implementation Specification [3].

In the event that a web feature service encounters an error while processing a request or receives an unrecognized request, it shall generate an XML document indicating that an error has occurred. The format of the XML error response is specified by, and must validate against, the exception response schema defined in section A.2.

A <ServiceExceptionReport> element can contain one or more WFS processing exceptions. The mandatory version attribute is used to indicate the version of the service exception report schema. For this version of the specification, this value is fixed at 1.2.0.

Individual exception messages are contained within the <ServiceException> element. The optional code attribute may 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. A number of elements defined in this document include a handle attribute that can be used to associate a mnemonic name with the element. If such a handle exists, its value may be reported using the locator attribute of the <ServiceException> element. If the handle attribute is not specified, then a web feature server implementation may attempt to locate the error using other means such as line numbers, etc...

Example 6. Example

The following is an example of an exception report. This exception indicates that the first insert statement failed because of a missing closing XML tag in the request.

<?xml version="1.0" ?>
<ServiceExceptionReport
   version="1.2.0"
   xmlns="http://www.opengis.net/ogc"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://www.opengis.net/ogc ../wfs/1.0.0/OGC-exception.xsd">
   <ServiceException code="999" locator="INSERT STMT 01">
      parse error: missing closing tag for element WKB_GEOM
   </ServiceException>
</ServiceExceptionReport>

It should be noted that this sample output validates against the exception report schema presented above.

All XML encoded WFS requests include an attribute called version. The mandatory version attribute is used to indicate to which version of the WFS specification the request encoding conforms and is used in version negotiation as described in section 6.2.4. The default value of the version attributed is set to 1.0.0, which corresponds to the version of this document.

All XML encoded WFS requests include an attribute called service. The mandatory service attribute is used to indicate which of the available service types, at a particular service instance, is being invoked. When invoking a web feature service, the value of the service attribute shall be WFS.

The purpose of the handle attribute is to allow a client application to associate a mnemonic name with a request for error handling purposes. If a handle is specified, and an exception is encountered, a Web Feature Service may use the handle to identify the offending element.

The function of the DescribeFeatureType operation is to generate a schema description of feature types serviced by a WFS implementation. The schema descriptions define how a WFS implementation expects feature instances to be encoded on input and how feature instances will be generated on output.

A DescribeFeatureType element contains zero or more TypeName elements that encode the names of feature types that are to be described. If the content of the DescribeFeatureType element is empty, then that shall be interpreted as requesting a description of all feature types that a WFS can service. The XML encoding of a DescribeFeatureType request is defined by the following XML Schema fragment:

   <xsd:element name="DescribeFeatureType" type="wfs:DescribeFeatureTypeType"/>
   <xsd:complexType name="DescribeFeatureTypeType">
      <xsd:sequence>
         <xsd:element name="TypeName" type="xsd:QName"
                      minOccurs="0" maxOccurs="unbounded"/>
      </xsd:sequence>
      <xsd:attribute name="version"
                     type="xsd:string" use="required" fixed="1.0.0"/>
      <xsd:attribute name="service"
                     type="xsd:string" use="required" fixed="WFS"/>
      <xsd:attribute name="outputFormat"
                     type="xsd:string" use="optional" default="XMLSCHEMA"/>
   </xsd:complexType>

The outputFormat attribute, is used to indicate the schema description language that should be used to describe feature type schemas. The only mandatory output format in response to a DescribeFeatureType operation is XML Schema, denoted by the value XMLSCHEMA for the outputFormat attribute. Other vendor specific formats are also possible, but they must be advertised on the capabilities document [sec. 12].

As specified by GML [2], the feature schema definition is entirely at the discretion of the particular WFS implementation that is describing its feature types. The only caveats are:

  1. Feature geometry must be expressed using the GML geometry description. (geometry.xsd).

  2. Spatial Reference Systems must be expressed as defined in the OpenGIS® Geography Markup Language (GML) Implementation Specification, version 2.1.1 [2].

  3. The feature schema must be consistent with the OGC feature model. This means that the feature schema defines properties of the feature. The GML interpretation of this statement is that the elements nested below the root element of a feature type define properties of that feature.

In response to a DescribeFeatureType request, where the value of the outputFormat attribute has been set to XMLSCHEMA, a WFS implementation must be able to present an XML Schema [6] document that is a valid GML [2] application schema and defines the schema of the feature types listed in the request. The document(s) presented 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.

Schema descriptions using other schema description languages, such as DTD, are also possible as long as such capabilities are declared in the capabilities document [sec. 12].

An XML Schema[6] document can only describe elements that belong to a single namespace. This means that a Web Feature Service cannot describe features from multiple namespaces in a single XML Schema document. To overcome this limitation, a WFS may generate an XML Schema document that is a “wrapper” schema that imports the schemas of the features from the various namespaces in the request. For example, consider the following request:

<?xml version="1.0" ?>
<DescribeFeatureType
   version="1.0.0"
   service="WFS"
   xmlns="http://www.opengis.net/wfs"
   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 ../wfs/1.0.0/WFS-basic.xsd">
   <TypeName>ns01:TREESA_1M</TypeName>
   <TypeName>ns02:ROADL_1M</TypeName>
</DescribeFeatureType>

A WFS may generate the following response to this request:

<?xml version="1.0" ?>
<schema
   xmlns="http://www.w3.org/2001/XMLSchema"
   elementFormDefault="qualified"
   attributeFormDefault="unqualified">

   <import namespace="http://www.server01.com/ns01"
           schemaLocation="http://www.myserver.com/wfs.cgi?
                           request=DescribeFeatureType&amp;typeName=ns01:TREESA_1M"/>

   <import namespace="http://www.server02.com/ns02"
           schemaLocation="http://www.yourserver.com/wfs.cgi?
                           request=DescribeFeatureType&amp;typeName=ns02:ROADL_1M"/>

</schema>

In this example, the WFS is using a DescribeFeatureType request to obtain the schemas of the features in the various namespaces. This is simply an example, other methods of obtaining the schemas may be implemented (for example: referencing static schema documents).

In the event that a web feature service encounters an error servicing a DescribeFeatureType request, it shall raise an exception as described Section 7.7.

Example 7. Example 1

Consider geographic features of types TREESA_1M and ROADL_1M that are defined in a SQL database. The description of these feature types is reported by the database to be:

SQL> describe TREESA_1M
Name                   Null?    Type
---------------------- -------- -------------
WKB_GEOM               NOT NULL  LONG RAW
ID                               NUMBER(10)
TREE_TYPE                        VARCHAR2(80)

SQL> describe ROADL_1M
Name                      Null?    Type
------------------------- -------- ------------
WKB_GEOM                  NOT NULL LONG RAW
DESIGNATION                        VARCHAR2(30)
SURFACE_TYPE                       VARCHAR2(30)
NLANES                             NUMBER(2)

In response to the DescribeFeatureType request:

<?xml version="1.0" ?>
<DescribeFeatureType
   version="1.0.0"
   service="WFS"
   xmlns="http://www.opengis.net/wfs"
   xmlns:myns="http://www.myserver.com/myns"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://www.opengis.net/wfs ../wfs/1.0.0/WFS-basic.xsd">
   <TypeName>myns:TREESA_1M</TypeName>
   <TypeName>myns:ROADL_1M</TypeName>
</DescribeFeatureType>

a web feature service may generate the following XML Schema document:

<?xml version="1.0" ?>
<schema
   targetNamespace="http://www.someserver.com/myns"
   xmlns:myns="http://www.someserver.com/myns"
   xmlns:xsd="http://www.w3.org/2001/XMLSchema"
   xmlns="http://www.w3.org/2001/XMLSchema"
   xmlns:gml="http://www.opengis.net/gml"
   elementFormDefault="qualified" version="0.1">

   <import namespace="http://www.opengis.net/gml"
           schemaLocation="../gml/2.1/feature.xsd"/>

   <!-- =============================================
        define global elements
        ============================================= -->
   <element name="TREESA_1M"
            type="myns:TREESA_1M_Type"
            substitutionGroup="gml:_Feature"/>

   <element name="ROADL_1M"
            type="myns:ROADL_1M_Type"
            substitutionGroup="gml:_Feature"/>

   <!-- ============================================
        define complex types (classes)
        ============================================ -->
   <complexType name="TREESA_1M_Type">
      <complexContent>
         <extension base="gml:AbstractFeatureType">
            <sequence>
               <element name="WKB_GEOM"
                        type="gml:PolygonPropertyType" nillable="false"/>
               <element name="ID" nillable="true" minOccurs="0">
                  <simpleType>
                     <restriction base="integer">
                        <totalDigits value="10"/>
                     </restriction>
                  </simpleType>
               </element>
               <element name="TREE_TYPE" nillable="true" minOccurs="0">
                  <simpleType>
                     <restriction base="string">
                        <maxLength value="80"/>
                     </restriction>
                  </simpleType>
               </element>
            </sequence>
         </extension>
      </complexContent>
   </complexType>

   <complexType name="ROADL_1M_Type">
      <complexContent>
         <extension base="gml:AbstractFeatureType">
            <sequence>
               <element name="WKB_GEOM"
                        type="gml:LineStringPropertyType"
                        nillable="false"/>
               <element name="DESIGNATION" nillable="true" minOccurs="0">
                  <simpleType>
                     <restriction base="string">

                        <maxLength value="30"/>
                     </restriction>
                  </simpleType>
               </element>
               <element name="SURFACE_TYPE" nillable="true" minOccurs="0">
                  <simpleType>
                     <restriction base="string">
                        <maxLength value="30"/>
                     </restriction>
                  </simpleType>
               </element>
               <element name="NLANES" nillable="true" minOccurs="0">
                  <simpleType>
                     <restriction base="integer">
                        <totalDigits value="2"/>
                     </restriction>
                  </simpleType>
               </element>
            </sequence>
         </extension>
      </complexContent>
   </complexType>
</schema>

Using this schema description, a client could then express the state of a TREESA_1M feature instance and/or a ROADL_1M feature instance as shown in the following example:

<?xml version="1.0" ?>
<wfs:FeatureCollection
   xmlns="http://www.someserver.com/myns"
   xmlns:myns="http://www.someserver.com/myns"
   xmlns:wfs="http://www.opengis.net/wfs"
   xmlns:gml="http://www.opengis.net/gml"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://www.opengis.net/wfs ../wfs/1.0.0/WFS-basic.xsd
                       http://www.someserver.com/myns ex07.xsd">
   <gml:boundedBy>
      <gml:Box srsName="http://www.opengis.net/gml/srs/epsg.xml#4326">
         <gml:coordinates>-180.0,-90.0 180.0,90.0</gml:coordinates>
      </gml:Box>
   </gml:boundedBy>
   <gml:featureMember>
      <TREESA_1M>
         <WKB_GEOM>
            <gml:Polygon>
               <gml:outerBoundaryIs>
                  <gml:LinearRing>
                     <gml:coordinates decimal="." cs="," ts=" ">-120.000000,65.588264
 -120.003571,65.590782 -120.011292,65.590965 -120.022491,65.595215 -120.031212,65.592880
 -120.019363,65.586121 -120.030350,65.585365 -120.045082,65.581848 -120.059540,65.584938
 -120.067284,65.590500 -120.067284,65.595436 -120.067337,65.613441 -120.067337,65.613777
 -120.060997,65.606346 -120.045517,65.605545 -120.022675,65.599777 -120.003975,65.601036
 -120.000000,65.602081 -120.000000,65.602081 -120.000000,65.588264</gml:coordinates>
                  </gml:LinearRing>
               </gml:outerBoundaryIs>
            </gml:Polygon>
         </WKB_GEOM>
         <ID>0000000002</ID>
         <TREE_TYPE>Maple</TREE_TYPE>
      </TREESA_1M>
   </gml:featureMember>
   <gml:featureMember>
      <ROADL_1M>
         <WKB_GEOM>
            <gml:LineString srsName="http://www.opengis.net/gml/srs/epsg.xml#4326">
               <gml:coordinates decimal="." cs="," ts=" ">-59.478340,-52.226578
 -59.484871,-52.223564 -59.488991,-52.198524 -59.485958,-52.169559 -59.480400,-52.152615
 -59.465576,-52.141491 -59.462002,-52.136417 -59.447968,-52.127190 -59.422928,-52.120701
 -59.411915,-52.117844 -59.397972,-52.116440 -59.371311,-52.121300</gml:coordinates>
            </gml:LineString>
         </WKB_GEOM>
         <DESIGNATION>HYW 401</DESIGNATION>
         <SURFACE_TYPE>ASPHALT</SURFACE_TYPE>
         <NLANES>12</NLANES>
      </ROADL_1M>
   </gml:featureMember>
</wfs:FeatureCollection>

Example 8. Example 2

This example describes a collection type, People, composed of feature instances of the feature type Person, that includes a complex property Address.

In response to the DescribeFeatureType request:

<?xml version="1.0" ?>
<DescribeFeatureType
   version="1.0.0"
   service="WFS"
   outputFormat="XMLSCHEMA"
   xmlns="http://www.opengis.net/wfs"
   xmlns:myns="http://www.myserver.com/myns"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://www.opengis.net/wfs ../wfs/1.0.0/WFS-basic.xsd">
   <TypeName>myns:People</TypeName>
</DescribeFeatureType>

a web feature service might generate an XML Schema document that looks like:

<?xml version="1.0" ?>
<xsd:schema
   targetNamespace="http://www.someserver.com/myns"
   xmlns:myns="http://www.someserver.com/myns"
   xmlns:gml="http://www.opengis.net/gml"
   xmlns:xsd="http://www.w3.org/2001/XMLSchema"
   xmlns="http://www.w3.org/2001/XMLSchema"
   elementFormDefault="qualified" version="0.1">

   <xsd:import namespace="http://www.opengis.net/gml"
               schemaLocation="../gml/2.1/feature.xsd"/>

   <xsd:element name="Person"
                type="myns:PersonType"
                substitutionGroup="gml:_Feature"/>

   <xsd:complexType name="PersonType">
      <xsd:complexContent>
         <xsd:extension base="gml:AbstractFeatureType">
            <xsd:sequence>
               <xsd:element name="LastName" nillable="true">
                  <xsd:simpleType>
                     <xsd:restriction base="string">
                        <xsd:maxLength value="30"/>
                     </xsd:restriction>
                  </xsd:simpleType>
               </xsd:element>
               <xsd:element name="FirstName" nillable="true">
                  <xsd:simpleType>
                     <xsd:restriction base="string">
                        <xsd:maxLength value="10"/>
                     </xsd:restriction>
                  </xsd:simpleType>
               </xsd:element>
               <xsd:element name="Age"
                            type="integer"
                            nillable="true"/>
               <xsd:element name="Sex"
                            type="string"/>
               <xsd:element name="Location"
                            type="gml:PointPropertyType"
                            nillable="true"/>
               <xsd:element name="Address"
                            type="myns:AddressType"
                            nillable="true"/>
            </xsd:sequence>
         </xsd:extension>
      </xsd:complexContent>
   </xsd:complexType>

   <xsd:complexType name="AddressType">
      <xsd:sequence>
         <xsd:element name="StreetName" nillable="true">
            <xsd:simpleType>
               <xsd:restriction base="string">
                  <xsd:maxLength value="30"/>
               </xsd:restriction>
            </xsd:simpleType>
         </xsd:element>
         <xsd:element name="StreetNumber" nillable="true">
            <xsd:simpleType>
               <xsd:restriction base="string">
                  <xsd:maxLength value="10"/>
               </xsd:restriction>
            </xsd:simpleType>
         </xsd:element>
         <xsd:element name="City" nillable="true">
            <xsd:simpleType>
               <xsd:restriction base="string">
                  <xsd:maxLength value="30"/>
               </xsd:restriction>
            </xsd:simpleType>
         </xsd:element>
         <xsd:element name="Province" nillable="true">
            <xsd:simpleType>
               <xsd:restriction base="string">
                  <xsd:maxLength value="30"/>
               </xsd:restriction>
            </xsd:simpleType>
         </xsd:element>
         <xsd:element name="PostalCode" nillable="true">
            <xsd:simpleType>
               <xsd:restriction base="string">
                  <xsd:maxLength value="15"/>
               </xsd:restriction>
            </xsd:simpleType>
         </xsd:element>
         <xsd:element name="Country" nillable="true">
            <xsd:simpleType>
               <xsd:restriction base="string">
                  <xsd:maxLength value="30"/>
               </xsd:restriction>
            </xsd:simpleType>
         </xsd:element>
      </xsd:sequence>
   </xsd:complexType>
</xsd:schema>

A sample instance document that validates against this schema might be:

<?xml version="1.0" ?>
<wfs:FeatureCollection
xmlns="http://www.someserver.com/myns"
xmlns:myns="http://www.someserver.com/myns"
xmlns:wfs="http://www.opengis.net/wfs"
xmlns:gml="http://www.opengis.net/gml"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.opengis.net/wfs ../wfs/1.0.0/WFS-basic.xsd
                    http://www.someserver.com/myns ex10.xsd">
   <gml:boundedBy>
      <gml:Box>
         <gml:coord>
            <gml:X>10</gml:X>
            <gml:Y>10</gml:Y>
         </gml:coord>
       <gml:coord>
            <gml:X>20</gml:X>
            <gml:Y>20</gml:Y>
         </gml:coord>
      </gml:Box>
   </gml:boundedBy>
   <gml:featureMember>
      <Person>
         <myns:LastName>Smith</myns:LastName>
         <myns:FirstName>Fred</myns:FirstName>
         <myns:Age>35</myns:Age>
         <myns:Sex>Male</myns:Sex>
         <myns:Location>
            <gml:Point><gml:coordinates>15,15</gml:coordinates></gml:Point>
         </myns:Location>
         <myns:Address>
            <myns:StreetName>Main St.</myns:StreetName>
            <myns:StreetNumber>5</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>
      </Person>
   </gml:featureMember>
</wfs:FeatureCollection>

The GetFeature operation allows retrieval of features from a web feature service. A GetFeature request is processed by a WFS and an XML document, containing the result set, is returned to the client.

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:sequence>
         <xsd:element ref="wfs:Query" maxOccurs="unbounded"/>
      </xsd:sequence>
      <xsd:attribute name="version"
                     type="xsd:string" use="required" fixed="1.0.0"/>
      <xsd:attribute name="service"
                     type="xsd:string" use="required" fixed="WFS"/>
      <xsd:attribute name="handle"
                     type="xsd:string" use="optional"/>
      <xsd:attribute name="outputFormat"
                     type="xsd:string" use="optional" default="GML2"/>
      </xsd:attribute>
      <xsd:attribute name="maxFeatures" type="xsd:positiveInteger"
                     use="optional"/>
   </xsd:complexType>
   <xsd:element name="Query" type="wfs:QueryType"/>
   <xsd:complexType name="QueryType">
     <xsd:sequence>
       <xsd:element ref="ogc:PropertyName" minOccurs="0" maxOccurs="unbounded"/>
       <xsd:element ref="ogc:Filter" minOccurs="0" maxOccurs="1"/>
     </xsd:sequence>
     <xsd:attribute name="handle"
                    type="xsd:string" use="optional"/>
     <xsd:attribute name="typeName"
                    type="xsd:QName" use="required"/>
     <xsd:attribute name="featureVersion"
                    type="xsd:string" use="optional"/>
   </xsd:complexType>

The <GetFeature> element contains one or more <Query> elements, each of which in turn contain the description of a query. The results of all queries contained in a GetFeature request are concatenated to produce the result set.

The outputFormat attribute defines the format to use to generate the result set. The default value is GML2 indicating that GML [2] shall be used. Vendor specific formats (including non-XML and binary formats), declared in the capabilities document are also possible.

The optional maxFeatures attribute can be used to limit the number of features that a GetFeature request retrieves. Once the maxFeatures limit is reached, the result set is truncated at that point.

Each individual query packaged in a GetFeature request is defined using the <Query> element. The <Query> element defines which feature type to query, what properties to retrieve and what constraints (spatial and non-spatial) to apply to those properties.

The typeName attribute is used to indicate the name of the feature type or class to be queried.

The featureVersion attribute is included in order to accommodate systems that support feature versioning. A value of ALL indicates that all versions of a feature should be fetched. Otherwise, an integer, n, can be specified to return the nth version of a feature. The version numbers start at 1, which is the oldest version. If a version value larger than the largest version number is specified, then the latest version is returned. The default action shall be for the query to return the latest version. Systems that do not support versioning can ignore the parameter and return the only version that they have.

The <PropertyName> element is used to enumerate the feature properties that should be selected during a query and whose values should be included in the response to a GetFeature request. A client application can determine the properties of a feature by making a DescribeFeatureType request before composing a GetFeature request. The DescribeFeatureType operation [sec. 8] will generate a GML application schema defining the schema of the feature type. The client can then select the properties to be fetched. In addition, the client can determine which feature properties are mandatory and must be fetched in order for the WFS to be able to generate an instance of the feature type that will validate againt the generated GML application schema. In the event that a WFS encounters a query that does not select all mandatory properties of a feature, the WFS will internally augment the property name list to include all necessary property names. A WFS client must thus be prepared to deal with a situation where it receives more property values than it requests.

If no <PropertyName> elements are specified, then all feature properties should be fetched.

The <Filter> element can be used to define constraints on a query. Both spatial and/or non-spatial constraints can be specified as described in the Filter Encoding Specification [3]. If no <Filter> element is contained within the <Query> element, then the query is unconstrained and all feature instances should be retrieved.

The <GetFeatureWithLock> element is functionally similar to the <GetFeature> element, except that it indicates to a web feature service to attempt to lock the features that are selected; presumably to update the features.

The format of the response to a GetFeature request is controlled by the outputFormat attribute. The default value for the outputFormat attribute shall be GML2. This will indicate that a WFS must generate a GML document of the result set that conforms to the OpenGIS® Geography Markup Language Implementation Specification, version 2.1.1 [2], and more specifically, the output must validate againt the GML application schema generated by the DescribeFeatureType operation [sec. 8].

Any GML document generated by a WFS implementation, in response to a query where the outputFormat is GML2, must reference an appropriate GML application schema document so that the output can be validated. This can be accomplished using the schemaLocation attribute, as defined in [6]. This attribute provides hints as to the physical location of one or more schema documents which may be used for local validation and schema-validity assessment. The schemaLocation attribute value contains pairs of values. The first member of each pair is the namespace for which the second member is the hint describing where to find to an appropriate schema document. The physical location of the schema documents is specified using a URI [10].

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.opengis.net/myns"
   xmlns:myns="http://www.opengis.net/myns"
   xmlns:gml="http://www.opengis.net/gml"
   xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance
   xsi:schemaLocation="http://www.opengis.net/myns
                       http://www.someserver.com/wfs.cgi?
                       request=DescribeFeatureType&typename=TREESA_1M,ROADL_1M"> …

In this instance, the schema document corresponding to the myns namespace is dynamically generated by making a DescribeFeatureType request back to the server that generated the output, requesting the schema. This DescribeFeatureType operation [sec. 8] requests the schema of the feature types TREESA_1M and ROADL_1M, both in the myns namespace.

It is up to each WFS implementation to arrange that the GML output makes the appropriate schemaLocation reference(s) such that the output can be validated.

For the <GetFeatureWithLock> request, a WFS must generate a result that includes the lock identifier. The lock identifier is encoded using the lockId attribute that is defined on the <wfs:FeatureCollection> element. The following XML fragment illustrates how to include the lockId attribute in the response to the operation:

<wfs:FeatureCollection lockId="00A01"… >
…
</wfs:FeatureCollection>

The ellipses are meant to represent all the other components included in the GetFeatureWithLock response which are identical to the components included in the GetFeature response.

In the event that a web feature service encounters an error servicing a GetFeature request, it shall raise an exception as described in Section 7.7.

This section contains numerous examples of the GetFeature request. Some examples include sample output.

Example 9. Example 1

This example fetches a specific instance of the feature type INWATERA_1M identified by the feature identifier "INWATERA_1M.1234".

<?xml version="1.0" ?>
<wfs:GetFeature
   service="WFS"
   version="1.0.0"
   outputFormat="GML2"
   xmlns:myns="http://www.someserver.com/myns"
   xmlns:wfs="http://www.opengis.net/wfs"
   xmlns:ogc="http://www.opengis.net/ogc"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://www.opengis.net/wfs ../wfs/1.0.0/WFS-basic.xsd">
   <wfs:Query typeName="myns:INWATERA_1M">
      <ogc:Filter>
         <ogc:FeatureId fid="INWATERA_1M.1234"/>
      </ogc:Filter>
   </wfs:Query>
</wfs:GetFeature>

Example 10. Example 2

This example fetches a subset of properties of the feature type INWATERA_1M. The specific instance that is retrieved by the request is identified by the feature identifier "INWATERA_1M.1013".

<?xml version="1.0" ?>
<wfs:GetFeature
   service="WFS"
   version="1.0.0"
   xmlns:wfs="http://www.opengis.net/wfs"
   xmlns:ogc="http://www.opengis.net/ogc"
   xmlns:myns="http://www.someserver.com/myns"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://www.opengis.net/wfs ../wfs/1.0.0/WFS-basic.xsd">
   <wfs:Query typeName="myns:INWATERA_1M">
      <ogc:PropertyName>myns:WKB_GEOM</ogc:PropertyName>
      <ogc:PropertyName>myns:TILE_ID</ogc:PropertyName>
      <ogc:PropertyName>myns:FAC_ID</ogc:PropertyName>
      <ogc:Filter>
         <ogc:FeatureId fid="INWATERA_1M.1013"/>
      </ogc:Filter>
   </wfs:Query>
</wfs:GetFeature>

Example 11. Example 3

In this example, all the properties of feature type INWATERA_1M are fetched for an enumerated list of feature instances. The <FeatureId> element is used to identify each feature to be fetched.

<?xml version="1.0" ?>
<GetFeature
   version="1.0.0"
   service="WFS"
   xmlns="http://www.opengis.net/wfs"
   xmlns:ogc="http://www.opengis.net/ogc"
   xmlns:myns="http://www.someserver.com/myns"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://www.opengis.net/wfs ../wfs/1.0.0/WFS-basic.xsd">
   <Query typeName="myns:INWATERA_1M">
     <ogc:Filter>
        <ogc:FeatureId fid="INWATERA_1M.1013"/>
        <ogc:FeatureId fid="INWATERA_1M.1014"/>
        <ogc:FeatureId fid="INWATERA_1M.1015"/>
      </ogc:Filter>
   </Query>
</GetFeature>

Example 12. Example 4

This example is similar to the previous example except in this case only some of the properties of an enumerated set of features are fetched. The <PropertyName> element is used to list the properties to be retrieved.

<?xml version="1.0" ?>
<GetFeature
   version="1.0.0"
   service="WFS"
   xmlns="http://www.opengis.net/wfs"
   xmlns:ogc="http://www.opengis.net/ogc"
   xmlns:myns="http://www.someserver.com/myns"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://www.opengis.net/wfs ../wfs/1.0.0/WFS-basic.xsd">
   <Query typeName="myns:INWATERA_1M">
      <ogc:PropertyName>myns:WKB_GEOM</ogc:PropertyName>
      <ogc:PropertyName>myns:TILE_ID</ogc:PropertyName>
      <ogc:Filter>
         <ogc:FeatureId fid="INWATERA_1M.1013"/>
         <ogc:FeatureId fid="INWATERA_1M.1014"/>
         <ogc:FeatureId fid="INWATERA_1M.1015"/>
      </ogc:Filter>
   </Query>
</GetFeature>

Example 13. Example 5

Select all instances of the feature type INWATERA_1M to a maximum of 10000 features.

<?xml version="1.0" ?>
<GetFeature
   version="1.0.0"
   service="WFS"
   maxFeatures="10000"
   xmlns="http://www.opengis.net/wfs"
   xmlns:myns="http://www.someserver.com/myns"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://www.opengis.net/wfs ../wfs/1.0.0/WFS-basic.xsd">
   <Query typeName="myns:INWATERA_1M"/>
</GetFeature>

Example 14. Example 6

The following unconstrained request fetches all the instances of an enumerated set of feature types. Notice that the feature types are not all in the same namespace

<?xml version="1.0" ?>
<GetFeature
   version="1.0.0"
   service="WFS"
   xmlns="http://www.opengis.net/wfs"
   xmlns:myns="http://www.someserver.com/myns"
   xmlns:yourns="http://demo.cubewerx.com/yourns"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://www.opengis.net/wfs ../wfs/1.0.0/WFS-basic.xsd">
   <Query typeName="myns:INWATERA_1M"/>
   <Query typeName="myns:BUILTUPA_1M"/>
   <Query typeName="yourns:ROADL_1M"/>
</GetFeature>

Example 15. Example 7

The following example selects the geometry and depth from the HYDROGRAPHY feature for the area of the Grand Banks. The Grand Banks are bounded by the following box: [-57.9118,46.2023,-46.6873,51.8145].

<?xml version="1.0" ?>
<GetFeature
   version="1.0.0"
   service="WFS"
   handle="Query01"
   xmlns="http://www.opengis.net/wfs"
   xmlns:ogc="http://www.opengis.net/ogc"
   xmlns:gml="http://www.opengis.net/gml"
   xmlns:myns="http://www.someserver.com/myns"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://www.opengis.net/wfs ../wfs/1.0.0/WFS-basic.xsd">
   <Query typeName="myns:HYDROGRAPHY">
      <ogc:PropertyName>myns:GEOTEMP</ogc:PropertyName>
      <ogc:PropertyName>myns:DEPTH<