ogc web feature service 3.0 - users guidedocs.opengeospatial.org/drafts/18-000.pdf · the wfs 3.0...
TRANSCRIPT
OGC Web Feature Service 3.0 - UsersGuide
Open Geospatial Consortium
Submission Date: <yyyy-mm-dd>
Approval Date: <yyyy-mm-dd>
Publication Date: <yyyy-mm-dd>
External identifier of this OGC® document: http://www.opengis.net/doc/DP/wfs/3.0
Internal reference number of this OGC® document: 18-000
Version: 3.0.0-SNAPSHOT (2018-03-07)
Category: OGC® Engineering Guidance
Editor: Charles Heazel
OGC Web Feature Service 3.0 - Users Guide
Copyright notice
Copyright © 2018 Open Geospatial Consortium
To obtain additional rights of use, visit http://www.opengeospatial.org/legal/
Warning
This document is not an OGC Standard. This document is distributed for review and comment. Thisdocument is subject to change without notice and may not be referred to as an OGC Standard.
Recipients of this document are invited to submit, with their comments, notification of any relevantpatent rights of which they are aware and to provide supporting documentation.
Document type: OGC® Discussion Paper
Document stage: Draft
Document language: English
1
License Agreement
Permission is hereby granted by the Open Geospatial Consortium, ("Licensor"), free of charge and subject to theterms set forth below, to any person obtaining a copy of this Intellectual Property and any associateddocumentation, to deal in the Intellectual Property without restriction (except as set forth below), including withoutlimitation the rights to implement, use, copy, modify, merge, publish, distribute, and/or sublicense copies of theIntellectual Property, and to permit persons to whom the Intellectual Property is furnished to do so, provided thatall copyright notices on the intellectual property are retained intact and that each person to whom the IntellectualProperty is furnished agrees to the terms of this Agreement.
If you modify the Intellectual Property, all copies of the modified Intellectual Property must include, in addition tothe above copyright notice, a notice that the Intellectual Property includes modifications that have not beenapproved or adopted by LICENSOR.
THIS LICENSE IS A COPYRIGHT LICENSE ONLY, AND DOES NOT CONVEY ANY RIGHTS UNDER ANY PATENTS THATMAY BE IN FORCE ANYWHERE IN THE WORLD.
THE INTELLECTUAL PROPERTY IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULARPURPOSE, AND NONINFRINGEMENT OF THIRD PARTY RIGHTS. THE COPYRIGHT HOLDER OR HOLDERS INCLUDEDIN THIS NOTICE DO NOT WARRANT THAT THE FUNCTIONS CONTAINED IN THE INTELLECTUAL PROPERTY WILLMEET YOUR REQUIREMENTS OR THAT THE OPERATION OF THE INTELLECTUAL PROPERTY WILL BEUNINTERRUPTED OR ERROR FREE. ANY USE OF THE INTELLECTUAL PROPERTY SHALL BE MADE ENTIRELY AT THEUSER’S OWN RISK. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR ANY CONTRIBUTOR OF INTELLECTUALPROPERTY RIGHTS TO THE INTELLECTUAL PROPERTY BE LIABLE FOR ANY CLAIM, OR ANY DIRECT, SPECIAL,INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING FROM ANY ALLEGEDINFRINGEMENT OR ANY LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCEOR UNDER ANY OTHER LEGAL THEORY, ARISING OUT OF OR IN CONNECTION WITH THE IMPLEMENTATION, USE,COMMERCIALIZATION OR PERFORMANCE OF THIS INTELLECTUAL PROPERTY.
This license is effective until terminated. You may terminate it at any time by destroying the Intellectual Propertytogether with all copies in any form. The license will also terminate if you fail to comply with any term or conditionof this Agreement. Except as provided in the following sentence, no such termination of this license shall require thetermination of any third party end-user sublicense to the Intellectual Property which is in force as of the date ofnotice of such termination. In addition, should the Intellectual Property, or the operation of the Intellectual Property,infringe, or in LICENSOR’s sole opinion be likely to infringe, any patent, copyright, trademark or other right of athird party, you agree that LICENSOR, in its sole discretion, may terminate this license without any compensation orliability to you, your licensees or any other party. You agree upon termination of any kind to destroy or cause to bedestroyed the Intellectual Property together with all copies in any form, whether held by you or by any third party.
Except as contained in this notice, the name of LICENSOR or of any other holder of a copyright in all or part of theIntellectual Property shall not be used in advertising or otherwise to promote the sale, use or other dealings in thisIntellectual Property without prior written authorization of LICENSOR or such copyright holder. LICENSOR is andshall at all times be the sole entity that may authorize you or any third party to use certification marks, trademarksor other special designations to indicate compliance with any LICENSOR standards or specifications. This Agreementis governed by the laws of the Commonwealth of Massachusetts. The application to this Agreement of the UnitedNations Convention on Contracts for the International Sale of Goods is hereby expressly excluded. In the event anyprovision of this Agreement shall be deemed unenforceable, void or invalid, such provision shall be modified so asto make it valid and enforceable, and as so modified the entire Agreement shall remain in full force and effect. Nodecision, action or inaction by LICENSOR shall be construed to be a waiver of any rights or remedies available to it.
2
Table of ContentsScope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
1. Audience. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2. References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3. Terms and Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
3.1. dataset. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
3.2. distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
3.3. feature. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
3.4. feature collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
4. Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
4.1. Identifiers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
4.2. UML model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
4.3. Link relations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
4.4. Use of HTTPS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
4.5. API definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
4.5.1. General remarks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
4.5.2. Role of OpenAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
4.5.3. References to OpenAPI components in normative statements . . . . . . . . . . . . . . . . . . . . . . 12
4.5.4. Paths in OpenAPI definitions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
4.5.5. Reusable OpenAPI components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
5. Introduction to Geospatial. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
5.1. The OpenGIS Feature Object Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
5.2. The OpenGIS Geometry Object Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
5.2.1. The Geometry Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
5.2.2. The Point Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
5.2.3. The Curve Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
5.2.4. The LineString Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
5.2.5. The Surface Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
5.2.6. The Polygon Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
5.2.7. The GeometryCollection Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
5.2.8. The GeometryCollection Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
5.2.9. The MultiCurve Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
5.2.10. The MultiSurface Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
5.2.11. The MultiSurface Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
6. Introduction to OpenAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
6.1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
6.2. Basic Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
6.2.1. OpenAPI Document (root) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
6.2.2. Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
3
6.2.3. Paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
6.2.4. Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
6.2.5. Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
6.3. Building the URLs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
6.4. Server Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
6.5. Extensions to OAS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
7. WFS 2.0 vs. WFS 3.0. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
7.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
7.2. WFS as a RESTful service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
7.3. Identifiers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
7.4. Addressability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
7.5. Statelessness . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
7.6. Representation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
7.7. Connectedness . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
7.8. Uniform Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
7.9. Safety and Idempotence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
8. OpenAPI and Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
8.1. Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
8.2. Information Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
8.2.1. Root . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
8.2.2. Service Identification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
8.2.3. Service Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
8.2.4. Operations Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
8.2.5. Feature Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
8.2.6. Filter Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
9. Information Assurance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
9.1. OpenAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
9.1.1. Security Schemes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
9.1.2. Security Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
9.1.3. OpenAPI Security Issues: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
9.2. Access Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
9.2.1. Bootstrap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
9.2.2. Discrete Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
9.2.3. Dynamic Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
10. Conformance Checklists. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
11. Media Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Annex A: Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Annex B: Bibliography . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
4
i. Abstract
The WFS 3.0 standards are simple, concise, and easy to implement. To achieve this simplicity, thestandards assume that implementers are well versed in OGC, spatial principles, REST, OpenAPI, anda host of other issues. That assumption is not always valid. This WFS 3.0 User’s Guide provides aplace to document that foundation knowledge. It also captures additional information which mayprove useful to implementers. By capturing this information in a separate document, implementershave ready access to knowledge which may prove useful without cluttering up the standardsthemselves with non-normative information. It also allows for easy update of this knowledgewithout impacting the standards themselves.
ii. Keywords
The following are keywords to be used by search engines and document catalogues.
ogcdoc, OGC document, web feature service, wfs, feature, property, geographic information, spatialdata, spatial things, dataset, distribution, openapi
iii. Preface
OGC Declaration
Attention is drawn to the possibility that some of the elements of this document may be the subjectof patent rights. The Open Geospatial Consortium Inc. shall not be held responsible for identifyingany or all such patent rights.
Recipients of this document are requested to submit, with their comments, notification of anyrelevant patent claims or other intellectual property rights of which they may be aware that mightbe infringed by any implementation of the standard set forth in this document, and to providesupporting documentation.
iv. Submitting organizations
The following organizations submitted this Document to the Open Geospatial Consortium (OGC):
• HeazelTech LLC
• CubeWerx Inc.
• interactive instruments GmbH
• …..
v. Submitters
All questions regarding this submission should be directed to the editor or the submitters:
Name Affiliation
Charles (Chuck) Heazel HeazelTech LLC
Clemens Portele interactive instruments GmbH
5
Name Affiliation
Panagiotis (Peter) A. Vretanos CubeWerx Inc.
(done)
6
ScopeThe WFS 3.0 standards specify the behavior of a server that provides access to features in a datasetin a manner independent of the underlying data store. It specifies discovery and query operations.
This WFS 3.0 Users Guide provides non-normative information which may be of use toimplementers of the WFS 3.0 standards. As a separate document, it makes this information readilyavailable to users while preserving the simplicity and conciseness of the standards. (done)
7
Chapter 1. AudienceThis document is written for developers who wish to implement the WFS 3.0 standards. It serves asa ready source of non-normative information which may aid in their development efforts. (done)
8
Chapter 2. ReferencesThis User Guide does not contain any normative content. The following documents arefundamental to the understanding of the WFS 3.0 Standards. A working knowledge of their contentis recommended for any implementer of the WFS 3.0 Standards. For undated references, the latestedition of the document is the best resource.
• Open API Initiative: OpenAPI Specification 3.0.1, https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md
• IETF: HTTP/1.1, RFC 2616, http://tools.ietf.org/rfc/rfc2616.txt
• IETF: Web Linking, RFC 5988, http://tools.ietf.org/rfc/rfc5988.txt
• van den Brink, L., Portele, C., Vretanos, P.: OGC 10-100r3, Geography Markup Language (GML)Simple Features Profile, http://portal.opengeospatial.org/files/?artifact_id=42729
• Butler H, Daly M, Doyle A, Gillies S, Hagen S, Schaub T: IETF RFC 7946, The GeoJSON Format,https://tools.ietf.org/rfc/rfc7946.txt
• Schema.org: http://schema.org/docs/schemas.html
• Cox S, Garnett J, Holmes C, Kralidis T, McLeod B, Parsons E, Vowles G: OGC’s Web FeatureService (WFS) Cookbook, https://portal.opengeospatial.org/files/?artifact_id=4265&version=1(validate and update)
9
Chapter 3. Terms and DefinitionsFor the purposes of this document, the following additional terms and definitions apply.
3.1. datasetcollection of data, published or curated by a single agent, and available for access or download inone or more formats [DCAT]
3.2. distributionrepresents an accessible form of a dataset [DCAT]
EXAMPLE: a downloadable file, an RSS feed or a web service that provides the data.
3.3. featureabstraction of real world phenomena [ISO 19101:2002, definition 4.11]
3.4. feature collectiona set of features from a dataset
CAUTION
ISSUE 4We need to make the document understandable to the developers that have nogeo/OGC background, too. What do we need to explain in this section and whatterms should we use in general?
Answer - the definitions in the standards should be kept simple with more detailed informationprovided in the Guide. (needs a re-write based on terms used in this document)
10
Chapter 4. Conventions
NOTEThis sections provides details and examples for any conventions used in thedocument. Examples of conventions are symbols, abbreviations, use of XMLschema, or special notes regarding how to read the document.
4.1. IdentifiersThe normative provisions in this specification are denoted by the URI http://www.opengis.net/spec/wfs-1/3.0.
All requirements and conformance tests that appear in this document are denoted by partial URIswhich are relative to this base.
4.2. UML modelUML diagrams are included in this standard to illustrate the conceptual model that underpins WebFeature Service implementations. The UML model is not normative. The UML profile used isspecified in ISO 19103:2015.
Resources are modelled as UML interfaces.
NOTE The OpenAPI definition is not modelled explicitly.
CAUTIONISSUE 36A draft UML for OpenAPI 3.0 is available and could be reused.
4.3. Link relationsTo express relationships between resources, RFC 5988 (Web Linking) and registered link relationtypes are used.
4.4. Use of HTTPSFor simplicity, this document in general only refers to the HTTP protocol. This is not meant toexclude the use of HTTPS and simply a shorthand notation for "HTTP or HTTPS". In fact, most WFSare expected to use HTTPS, not HTTP.
4.5. API definition
4.5.1. General remarks
11
NOTE
TODOAdd general considerations.Clarify that additional operations, parameters, etc. may be added, either toimplement additional conformance classes or for vendor-specific extensions.
4.5.2. Role of OpenAPI
This document uses OpenAPI 3.0 fragments as examples and to formally state requirements.However, using OpenAPI 3.0 is not required.
The "Core" requirements class, therefore, only requires that a formal API definition is provided at/api.
A separate requirements class is specified for API definitions that follow the OpenAPI specification3.0, but this does not preclude that in the future or in parallel other versions of OpenAPI or otherdescriptions are provided by a server.
NOTEThis approach is used to avoid lock-in to a specific approach to defining an API as itis expected that the landscape will continue to evolve.
In this document, fragments of OpenAPI definitions are shown in YAML since YAML is easier toread than JSON and is typically used in OpenAPI editors.
4.5.3. References to OpenAPI components in normative statements
Some normative statements (requirements, recommendations and permissions) use a phrase that acomponent in the API definition of the server must be "based upon" a schema or parametercomponent in the OGC schema repository.
In this case, the following changes to the pre-defined OpenAPI component are permitted:
• If the server supports an XML encoding, xml properties may be added to the relevant OpenAPIschema components.
• The range of values of a parameter or property may be extended (additional values) orconstrained (if only a subset of all possible values are applicable to the service). An example fora constrained range of values is to explicitly specify the supported values of a string parameteror property using an enum.
• Additional properties may be added to the schema definition of a Response Object.
• Informative text may be changed or added, like comments or description properties.
NOTETODOCheck, that we cover all cases.
For API definitions that do not conform to the OpenAPI Specification 3.0 the normative statementshould be interpreted in the context of the API definition language used.
12
4.5.4. Paths in OpenAPI definitions
All paths in an OpenAPI definition are relative to a base URL of the server.
Example 1. URL of the OpenAPI definition
If the OpenAPI Server Object would look like this:
servers: - url: https://dev.example.org/ description: Development server - url: https://data.example.org/ description: Production server
The path "/mypath" in the OpenAPI definition of a WFS would be the URLhttps://data.example.org/mypath for the production server.
4.5.5. Reusable OpenAPI components
Reusable components for OpenAPI definitions of a WFS are referenced from this document.
NOTE
For now, these components use a base URL of"https://raw.githubusercontent.com/opengeospatial/ogcapi-features/master/", buteventually these will be available using the base URL"http://schemas.opengis.net/wfs/3.0/openapi/". (needs a complete re-write)
13
Chapter 5. Introduction to GeospatialWith thanks to the OGC WFS Cookbook
NOTEThe OGC WFS Cookbook was written in 2003. This content will be reviewed and anychanges made since then applied.
5.1. The OpenGIS Feature Object ModelWFS is about geographic features. The feature model underlies the ISO and OGC view of geographicinformation. The OGC abstract model defines a feature as ?an abstraction of a real worldphenomenon? A feature can be:
• An entity (e.g., a mountain, a pond, a city)
• A space (e.g., a postcode area, the tropics).
• A definable location (e.g., a crossroad, as a particular place where two streets intersect).
A Feature will have a number of properties (simple or complex), some of which may be geometricand spatial. The latter is important. In traditional GIS, an item of interest is usually defined as asingle geometry ? often a point, line or polygon ? with attributes. In the Feature model the item ofinterest is a conceptually meaningful phenomenon within the domain of discourse ? such as aMine, Road or Land-Parcel ? for which one or more properties may be geometric. In a specificfeature, the generic ?property? shown in the model would be replaced by several namedproperties, the values of which would be constrained to be of particular types. The value may bestructured, and in some cases may be another feature. A specific Feature Type is defined in terms ofthis set of named properties that are associated with that type . A Feature instance is thus thefunctional map of its property values. See Figure 5 for an example of features and its properties.
The Feature model also has Feature Collection, which is a collection of Features together with abounding Box element that bounds the set of Features. There is no limit to the number of featuresthat can be contained in a FeatureCollection; it can contain other features and Feature Collections.A Feature Collection must have a boundedBy property. All features inside a FeatureCollectionwould have homogeneous simple properties. One of those properties is typically the geometry ofthe feature. Geometric Property contains Geometry: Point, LineString, Polygon, (Multi-), Box. SeeFigure 6 for an example of Feature Collection.
Feature Collections may or may not have useful identity in themselves. It all depends on how thedata producer has constructed an application schema. Feature Collections can correspond totraditional GIS layers, and as such can have properties like metadata or like a minimum boundingrectangle (MBR), which must be re-computed if one only queries for the members of the featurecollection. Feature Collections can also correspond to tiles in a data set that has been segmented todeal with large data volumes. In both cases, the gml:id of the feature collection becomes a key bit ofinfo for a WFS client.
14
Figure 5: Feature and Properties
Figure 6: Feature Collection
Figure 7 shows the OpenGIS Feature Model. The single-hash mark across a relationship linkindicates a derived association. For example, a Coordinate Geometry is dependent on the ReferenceSystem specified. Another example is that one Feature can be derived from another Feature. Thetriangle at one end of a relationship link indicates a subtype relationship. That is, the GeometricProperty object is a subtype of the Property object. A small rectangle with a label inside that is atone end of a relationship link indicates a named relationship. For example, a Property Set has oneor more Geometric Properties, each of which must be identified by a name. There is also a subsetrelationship, which here means that Geometric Properties make up a subset of all Properties, andthat Coordinate Geometry makes up a subset of any other kinds of Properties.
15
Figure 7: OpenGIS Feature Object Model
Each object has a unique identifier (Object ID or OID), which is assigned and maintained by thesystem. This results in much more efficient selection, comparison, and other processing of objectsin queries and analysis. This is in contrast with relational database systems, in which a record ID isunique within a single table.
Figure 8 shows the basic example of an abstract feature model. To describe an object using thefeature model, its "type" or the "class" to which it belongs is determined first. This fixes whatproperties are associated with it, one or more of which may be geometric. The major advantage inthinking in terms of objects is that features can be abstracted at a higher level. A class of ?road? isan Abstract Data Type (ADT), a higher semantic level than the integers, strings, record-sets orrecords used before.
Figure 8: OpenGIS Feature (abstract)
An example of a concrete feature type class (i.e., Road) is shown in Figure 9.
16
Figure 9: Road Feature
The geospatial context is also important and usually one or more of the properties concernsgeometry, for example, a road will have a shape whose value is a ?Curve.? The original meaning ofthe word geometry denotes a branch of mathematics. Another meaning comes from cartography,referring to the geometric features that cartographers use to map the world. Geometry can bedefined as a point or an aggregate of points representing anything in the world that has a location.
Figure 10 shows some class definitions that might be found in a geographical database. Notice eachof these classes has attributes and methods for locational, graphical, and analytical purposes. Theattribute which describes the shape and location is often called ?geometry? (described in detail inSection 1.2.2, The OpenGIS Geometry Object Model) and is a special basic type whichautomatically and invisibly links into the underlying spatial indexing system.
Figure 10: Geographic Feature Classes
Figure 11 shows how sub-classing can be used to set up two different visual representations for thedifferent types of ?Road? class. Each sub-class has a different display method ?draw?. Notice thateach sub-class inherits all the other attributes and methods from the super-class and so does notneed to redefine them. This could alternatively be designed with only one class, an attributespecifying the type of road, and a display method which had a list of ?if? statements on that road-type attribute (note that this is not so robust for extensions).
17
Figure 11: Object-Oriented Inheritance
5.2. The OpenGIS Geometry Object ModelIn 1997, OGC published the OpenGIS Simple Features Specifications for SQL , which describes a setof SQL geometry types, as well as functions on those types to create and analyze geometry values.In addition, it proposes several conceptual ways for extending an SQL RDBMS to support spatialdata.
Figure 11 shows the OpenGIS geometry object model
Figure 12: OpenGIS Geometry Object Model
18
The OpenGIS geometry class has the following hierarchy:
o Geometry (non-instantiable) o Point (instantiable) o Curve (non-instantiable) ? LineString (instantiable) ? Line ? LinearRing o Surface (non-instantiable) ? Polygon (instantiable) o GeometryCollection (instantiable) ? MultiPoint (instantiable) ? MultiCurve (non-instantiable) o MultiLineString (instantiable) ? MultiSurface (non-instantiable) o MultiPolygon (instantiable)
Some of these classes are abstract (non-instantiable). That is, it is not possible to create an object ofthese classes. Other classes are instantiable and objects may be created of them. Each class hasproperties and instantiable classes may have assertions (rules that define valid class instances).Geometry, Curve, Surface, MultiCurve, and MultiSurface are defined as non-instantiable classes.They define a common set of methods for their subclasses and are included for the reason ofextensibility. Point, LineString, Polygon, GeometryCollection, MultiPoint, MultiLineString, andMultiPolygon are instantiable classes.
5.2.1. The Geometry Class
Geometry is the base class and it is an abstract class. The instantiable subclasses of Geometry arerestricted to zero-, one-, and two-dimensional geometric objects that exist in two-dimensionalcoordinate space. All instantiable geometry classes are defined so that valid instances of a geometryclass are topologically closed (that is, all defined geometries include their boundary). A geometryvalue has the following properties:
• Its type. Each geometry belongs to one of the instantiable classes in the hierarchy.
• Its SRID, or Spatial Reference Identifier. This value identifies the geometry’s associated SpatialReference System that describes the coordinate space in which the geometry object is defined.
• Its coordinates in its Spatial Reference System, represented as double-precision (8-byte)numbers. All non-empty geometries include at least one pair of X,Y coordinates. Emptygeometries contain no coordinates. Coordinates are related to the SRID. For example, indifferent coordinate systems, the distance between two objects may differ even when objectshave the same coordinates, because the distance on the planar coordinate system and thedistance on the geocentric system (coordinates on the Earth’s surface) are different things.
• Its interior, boundary, and exterior. All geometries occupy some position in space. The exteriorof a geometry is all space not occupied by the geometry. The interior is the space occupied bythe geometry. The boundary is the interface between geometry’s interior and exterior.
• Its MBR (Minimum Bounding Rectangle), or Envelope. This is the bounding geometry, formed by
19
the minimum and maximum (X,Y) coordinates: MINX MINY, MAXX MINY, MAXX MAXY, MINXMAXY, MINX MINY
• The quality of being simple or non-simple. Geometry values of some types (LineString,MultiPoint, MultiLineString) are either simple or non-simple. Each type determines its ownassertions for being simple or non-simple.
• The quality of being closed or not closed. Geometry values of some types (LineString,MultiString) are either closed or not closed. Each type determines its own assertions for beingclosed or not closed.
• The quality of being empty or not empty. A geometry is empty if it does not have any points.Exterior, interior and boundary of an empty geometry are not defined (that is, they arerepresented by a NULL value). An empty geometry is defined to be always simple and has anarea of 0.
• Its dimension. A geometry can have a dimension of -1, 0, 1, or 2:
o -1 stands for empty geometries.o 0 stands for geometries with no length and no area.o 1 stands for geometries with non-zero length and zero area.o 2 stands for geometries with non-zero area.
Point objects have a dimension of zero. LineString objects have a dimension of 1. Polygon objectshave a dimension of 2. The dimensions of MultiPoint, MultiLineString, and MultiPolygon objects arethe same as the dimensions of the elements they consist of.
The base Geometry class has subclasses for Point, Curve, Surface and GeometryCollection, whichare explained below.
5.2.2. The Point Class
A Point represents zero-dimensional objects. A Point is a geometry that represents a single locationin coordinate space. Point properties are:
• X-coordinate value.
• Y-coordinate value.
• Point is defined as a zero-dimensional geometry.
• The boundary of a Point is the empty set.
5.2.3. The Curve Class
A Curve represents one-dimensional objects. Its geometry is usually represented by a sequence ofpoints. Particular subclasses of Curve define the type of interpolation between points. Curve is anon-instantiable class. Curve has subclass LineString, with sub-subclasses Line and LinearRing.Curve properties are:
• The coordinates of its points.
• Curve is defined as one-dimensional geometry.
20
• A Curve is simple if it does not pass through the same point twice.
• A Curve is closed if its start point is equal to its end point.
• The boundary of a closed Curve is empty.
• The boundary of a non-closed Curve consists of its two end points.
• A Curve that is simple and closed is a LinearRing (i.e., rivers, roads).
5.2.4. The LineString Class
A LineString is a Curve with linear interpolation between points. LineString properties are:
• Coordinates of LineString segments, defined by each consecutive pair of points.
• A LineString is a Line if it consists of exactly two points.
• A LineString is a LinearRing if it’s both closed and simple.
5.2.5. The Surface Class
A Surface is designed for two-dimensional objects and has subclass Polygon. Surface properties are:
• A Surface is defined as a two-dimensional geometry.
• A simple Surface is a geometry that consists of a single ``patch'' that is associated with a singleexterior boundary and zero or more interior boundaries.
• The boundary of a simple Surface is the set of closed curves corresponding to its exterior andinterior boundaries.
5.2.6. The Polygon Class
A Polygon is a simple geometry made up of the following assertions:
• The boundary of a Polygon consists of a set of LinearRings (that is, LineStrings that are bothsimple and closed) that make up its exterior and interior boundaries.
• No two rings in the boundary cross. The rings in the boundary of a Polygon may intersect at aPoint, but only as a tangent.
• A Polygon may not have cut lines, spikes, or punctures.
• The interior of every Polygon is a connected point set.
• The exterior of a Polygon with one or more holes is not connected. Each hole defines aconnected component of the exterior.
5.2.7. The GeometryCollection Class
A GeometryCollection has specialized zero-, one-, and two-dimensional collection classes namedMultiPoint (i.e., chain of small islands), MultiLineString (i.e., a river or a highway system), andMultiPolygon (i.e., a system of lakes) for modeling geometries corresponding to collections of Points,LineStrings, and Polygons, respectively. MultiCurve and MultiSurface are introduced as abstractsuperclasses that generalize the collection interfaces to handle Curves and Surfaces. All the
21
elements in a GeometryCollection must be in the same Spatial Reference System (that is, in thesame coordinate system). GeometryCollection places no other constraints on its elements, althoughthe subclasses of GeometryCollection described in the following sections may restrict membership.Retrictions may be based on:
• Element type (for example, a MultiPoint may contain only Point elements)
• Dimension
• Constraints on the degree of spatial overlap between elements
5.2.8. The GeometryCollection Class
A MultiPoint is a geometry collection composed of Point elements. The points are not connected orordered in any way. MultiPoint properties are:
• MultiPoint is defined as a zero-dimensional geometry.
• A MultiPoint is simple if no two of its Point values are equal (have identical coordinate values).
• The boundary of a MultiPoint is the empty set.
5.2.9. The MultiCurve Class
A MultiCurve is a geometry collection composed of Curve elements. MultiCurve is a non-instantiable class. MultiCurve properties are:
• A MultiCurve is simple if and only if all of its elements are simple, the only intersectionsbetween any two elements occur at points that are on the boundaries of both elements.
• The boundary of a MultiCurve is obtained by applying the ``mod 2 union rule'' (also known asthe odd-even rule): A point is in the boundary of a MultiCurve if it is in the boundaries of an oddnumber of MultiCurve elements.
• A MultiCurve is closed if all of its elements are closed.
• The boundary of a closed MultiCurve is always empty.
5.2.10. The MultiSurface Class
MultiSurface is a geometry collection composed of surface elements. MultiSurface is a non-instantiable class. Its only instantiable subclass is MultiPolygon. Its assertions are:
• The interiors of any two surfaces in a MultiSurface may not intersect.
• The boundaries of any two elements in a MultiSurface may intersect at most at a finite numberof points.
5.2.11. The MultiSurface Class
MultiPolygon is a MultiSurface object composed of Polygon elements. Its assertions are:
• The interiors of two Polygon values that are elements of a MultiPolygon may not intersect.
• The boundaries of any two Polygon values that are elements of a MultiPolygon may not cross
22
and may touch at only a finite number of points. (Crossing is also forbidden by the precedingassertion).
• A MultiPolygon may not have cut lines, spikes or punctures. A MultiPolygon is a regular, closedpoint set.
• The interior of a MultiPolygon composed of more than one Polygon is not connected. Thenumber of connected components of the interior of a MultiPolygon is equal to the number ofPolygon values in the MultiPolygon.
MultiPolygon properties are:
• A MultiPolygon is defined as a two-dimensional geometry.
• The boundary of a MultiPolygon is a set of closed curves (LineString values) corresponding tothe boundaries of its Polygon elements.
• Each Curve in the boundary of the MultiPolygon is in the boundary of exactly one elementPolygon.
• Every Curve in the boundary of an element Polygon is in the boundary of the MultiPolygon.(done)
23
Chapter 6. Introduction to OpenAPI
6.1. IntroductionThe OpenAPI Specification is a community-driven open specification within the OpenAPI Initiative,a Linux Foundation Collaborative Project.
The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interfacedescription for REST APIs, which allows both humans and computers to discover and understandthe capabilities of a service without requiring access to source code, additional documentation, orinspection of network traffic. When properly defined via OpenAPI, a consumer can understand andinteract with the remote service with a minimal amount of implementation logic. Similar to whatinterface descriptions have done for lower-level programming, the OpenAPI Specification removesguesswork in calling a service.
Use cases for machine-readable API definition documents include, but are not limited to:interactive documentation; code generation for documentation, clients, and servers; andautomation of test cases. OpenAPI documents describe an API’s services and are represented ineither YAML or JSON formats. These documents may either be produced and served statically or begenerated dynamically from an application.
The OpenAPI Specification does not require rewriting existing APIs. It does not require binding anysoftware to a service — the service being described may not even be owned by the creator of itsdescription. It does, however, require the capabilities of the service be described in the structure ofthe OpenAPI Specification. Not all services can be described by OpenAPI — this specification is notintended to cover every possible style of REST APIs. The OpenAPI Specification does not mandate aspecific development process such as design-first or code-first. It does facilitate either technique byestablishing clear interactions with a REST API.
This GitHub project is the starting point for OpenAPI. Here you will find the information you needabout the OpenAPI Specification, simple examples of what it looks like, and some generalinformation regarding the project.
The OpenAPI GitHub project is here.
6.2. Basic StructureThe following is an abbreviated overview of the OpenAPI document structure. The authoritativesource is the OpenAPI 3.0 standard available here.
6.2.1. OpenAPI Document (root)
The OpenAPI document contains descriptive information about the API and serves as the root forthe other parts of the document.
24
6.2.2. Servers
An API is not restricted to a single server. The Servers field provides a description of the serverswhich contribute to this API. This field is a collection of Server Objects. Each Server Objectdescribes one or more of the contributing servers. More detailed descriptions of the Server Objectsand how they are used to build resource URLs is provided below.
6.2.3. Paths
All API resources are accessed through a path. The Paths field defines all of the paths availablethrough this API. The Paths field is collection of Paths Objects. Each Paths Object includes the URLor URL template for this path, any Server Objects specific to this Path, Parameters which areapplicable to this Path, and an Operation Object for each of the HTTP Verbs applicable to this Path.
Operation Objects provide the details needed to create an HTTP request and response. Specifically,they provide definitions of the request message (including parameters) and all possible responses.In addition, they define any operation specific Server Objects or Security Requirements.
6.2.4. Components
In order to keep OpenAPI documents manageable, many parts can be defined once then referencedwherever they are needed. The Components field is where these re-usable components are defined.The following OpenAPI components can be reused:
• Schema Objects
• Response Objects
• Parameter Objects
• Example Objects
• Request Body Objects
• Header Objects
• Security Scheme Objects
• Link Objects
• Callback Objects
Each of these objects has an associated key. The key is then used to reference that object fromanywhere in the OpenAPI document.
6.2.5. Security
The Security field identifies Security Requirements which are applicable to the API as a whole. Thisfield is a collection of Security Requirement Objects. A description of Security Requirement Objects,Security Scheme Objects, and how they work together to describe the security controls of the API isprovided in Section 10.
25
6.3. Building the URLsAn OpenAPI document can describe a large number of URLs. Extracting all of the URLs is a non-trivial task. The OpenAPI objects used to construct URLs are:
• Server Objects (URL template for the root and variables to populate it)
• Paths Objects (URL template for the path and parameters)
• Operation Objects (including parameters)
They are organized as follows:
{Server Object}/{Path Object}/?{Parameters}
IF Server Objects are supplied THEN save them for latter ELSE create a Server Object for the host of the OpenAPI documentDO FOR each Path IF Server Objects are included, THEN Use them instead of those previously identified IF Parameter Objects are included, THEN save them for latter DO FOR Each Operation IF Server Objects are included, THEN Use them instead of those previously identified IF Parameter Objects are included THEN IF this parameter was previously defined THEN replace the previous definition ELSE add this parameter to the set. DO FOR Each Server Object Extract all URL roots DO FOR each URL root Concatenate the URL root and Path to create a working URL Concatenate the working URL with the Parameters Save the completed URL for future use CONTINUE DONE DONEDONE
6.4. Server ObjectsServer Objects may be found at the OpenAPI document, Path Object, and Operation Object level.Given this potentially large number of servers, how do you create the valid paths?
We can assume that the authors of a OAS document are not doing it for their personal enjoyment.Therefore, if a Server Object is included, there must be a reason for its' presence. So the ServerObjects with the most restrictive scope are the ones we should use. Clients should look for ServerObjects in the following order:
26
1. The Operation Object,
2. Then Path Item,
3. The root. The first scope where a Server Object is found dictates the behavior completely.
CAUTIONISSUE 41How does a client determine which security protocols/standards/etc. a serversupports
6.5. Extensions to OASThe OpenAPI Technical Steering Committee (TSC) has added support for "draft" features to the OASdevelopment process. These features will be introduced as OAI approved extensions. Byintroducing new features this way, new features can be designed, documented and thenimplemented by tools that are interested in the feature, without putting the burden ofimplementation on all tooling. If the feature is successfully implemented and there is demonstrablevalue added by the feature, it will become a candidate for inclusion in a future release of thespecification, at which point all tools will be expected to support the feature.
Draft feature extensions are identified by the x-oas-draft- prefix and can only be used whereexisting extensions are permitted. This ensures no existing tooling will affected by the introductionof the draft feature. If the feature is deemed appropriate for inclusion in the OAS, the x-oas-draft-prefix will be removed. Tooling that supports draft features should plan for the future removal ofthe prefix. When tooling adds support for a later version of OAS that includes the finalimplementation of the feature, it MUST not support the use of the draft prefix for that feature. Draftfeatures will only be promoted into minor or major releases of the specification and therefore willbe transparent to OpenAPI description writers and tooling providers who choose not to use thefeature while in its draft state.
Draft features will be documented as GitHub issues and labeled with the draft-feature label and willbe initially labelled as draft:proposal. When the proposal is considered sufficiently stable for pilotimplementation, it will be labeled draft:pilot. If during the development of a draft feature, it isdetermined that the feature needs to change in a way that may break existing draftimplementations, the extension name itself may be versioned with a version suffix. e.g. -v2 When adraft feature becomes part of a future update to the specification any version suffix will beremoved. Draft features that are deemed not appropriate for inclusion MUST be marked with thedraft:abandoned label. Draft-features that are considered suitably specified and have hadsuccessful pilot implementations will be marked with the draft:graduated label.
Not all future new features will be introduced in this way. Some new features impact thespecification in ways that cannot be encapsulated in an extension. However, where a new featurecan be introduced in this way, it should be. (done)
27
Chapter 7. WFS 2.0 vs. WFS 3.0This section describes how WFS 3.0 differs from previous versions of WFS.
7.1. OverviewVersion 2.0 of the WFS standard used a Remote-Procedure-Call-over-HTTP architectural style withXML encoding of the payloads. This was state-of-the-art in the late 1990s and early 2000s, whenWFS was originally designed.
This version 3.0 specifies a modernized service that is better aligned with the current architectureof the Web. Key changes are:
• Architecture: WFS now supports and is consistent with HTTP and HTTPS. In previous versions,HTTP has been used mainly as a tunnel for WFS messages. In addition, the resources providedby the service include hypermedia controls in their representations to guide the user of a WFS.
• Encodings: Previous versions were strongly tied to XML (Capabilities documents, XML schemas,Filter Encoding expressions, GML encoding). This version has been written with HTML, JSONand XML as encodings in mind, because these are common encodings today. No encoding ismandatory and other encodings may be used as well.
• Reuse: The use of WFS-specific resources or components has been minimized and, whereavailable, existing industry-standards that are commonly used by developers are used instead.An example is the use of OpenAPI (the successor of Swagger) instead of OGC-specific"Capabilities" documents.
• Schemas: Previous versions required XML schemas for all feature types and valid XMLdocuments. While the capability to support application schemas has been maintained, it is nolonger mandatory that rigid schemas are provided and used for validation of feature data.
• Modularization: The WFS 2.0 standard, together with the Filter Encoding 2.0 standard, specifiesa powerful, but complex service interface. In order to better support implementations that onlyneed a relatively simple service or client, this version is modularized into multiple parts. Thisfirst part represents a simple interface to access spatial data that is sufficient for cases that donot require support for transactions, complex data structures, rich queries, custom coordinatereference systems, etc. Additional parts will specify extensions to this core to support use casesthat require such capabilities.
• Security: Built-in support for secured services using common security schemes
These changes align WFS with the W3C/OGC best practices for sharing Spatial Data on the Web andthe general W3C best practices for sharing Data on the Web.
As a result of this modernization, WFS 3.0 implementations are not backwards compatible withWFS 2.0 implementations per se. However, it has been a design goal to define WFS 3.0 in a way sothat the WFS 3.0 interface can be mapped to an WFS 2.0 implementation - at least for thecapabilities that were already in scope in WFS 2.0. WFS 3.0 is intended to be simpler and moremodern, but still an evolution from the previous versions and their implementations.
28
7.2. WFS as a RESTful serviceThis version of WFS uses the REST architectural style that is that basis of many current Web APIs.Key characteristics include:
1. URIs: Every URI designates exactly one resource.
2. Addressability: All the interesting aspects of a service (e.g. features) are exposed as resources.
3. Statelessness: Every HTTP request includes all necessary information for the server to fulfil therequest without relying on previous requests.
4. Representation: Each resource offered by the service has a representation that encodes usefulinformation about the state of a resource.
5. Connectedness: Resources will link to each other and alternate representations.
6. Uniform interface: The server offers a uniform interface, using the HTTP verbs, for accessingand manipulating resources.
7. Safety and idempotence: HTTP methods are characterized as safe and/or idempotent.
7.3. IdentifiersResources exposed by a WFS 3.0 include Features, Feature Collections, and Metadata. Each resourceis uniquely identified and accessible via a URI.
Features and Feature Collections use the same logical data model regardless of whether they arehosted on a WFS 2.0 or WFS 3.0. That includes support for the gml:id attribute or an equivalent.Implementers should pay particular attention to this property when designing their systems.
Geospatial data tends to wander. It is common practice to widely distribute this data, sendingcopies wherever they are most convenient for the users. In addition, Features and FeatureCollections are often incorporated into derivative products. The same resource can appear in manydifferent data sets. Finally, there are often legal and historical requirements to identify a specificgeospatial resource decades or even centuries after it was first published. The identifier propertyallows us to track geospatial Features as they migrate through space and time.
Recommended Practice: The identifier (gml:id) property of Features and Feature Collections shouldbe populated with a value which will be globally unique regardless of when, where, or how thatresource is stored.
7.4. AddressabilityWFS 2.0 uses a query-response model to access its' data. The hosted Features and FeatureCollections are not individually addressable. WFS 3.0 provides a path hierarchy to access its' data.Individual Features and Feature Collections are individually accessible as long as you know thepath and the id of the resource.
Note that WFS 2.0 does support a GetFeatureById operation. Conceptually this is equivalent to theWFS 3.0 Path. However, it is implemented as a stored query. As such, the existence and propertiesof a Feature may change from one query to the next.
29
7.5. StatelessnessAs a RESTful service, WFS 3.0 should be stateless. However, paging support similar to that of WFS2.0 is a recommended feature of the core. This feature may require that the service maintain state.
The simplest way to implement WFS paging is to generate a result set in response to the initialrequest, then return portions of that result set in response to "next" requests. If we consider theresult set to be a resource (or a collection of page resources), then we can argue that we have notviolated the statelessness requirement.
This approach can work if the data holdings are stable and static. In a more dynamic environment,the contents of the result set may change between the initial and subsequent requests. Theimplementer has a choice, either return invalid data or re-execute the initial request.
It is a good practice to always return current valid data. However, that would require re-executingthe original request against the updated data holdings. And that requires that the request is cachedon the server. Which means that the server maintains state.
The WFS 3.0 Standard takes no position on this issue. It is a decision of the implementer based onthe nature of their data and requirements of prospective users.
7.6. RepresentationWFS 3.0 does not mandate any representation of the resources it exposes. Rather, it defines eachrepresentation as an extension to the core. Knowledge of the extensions supported by a WFS(though the /conformance path) informs a client of what representations are supported.
Planned Representations are:
• HTML
• GeoJSON
• GML
7.7. ConnectednessThe resources exposed by WFS 3.0 can be classified as:
• Features
• Feature Collections
• Metadata
Features and Feature Collections are discussed in Section 6. Metadata are the resources which tie itall together. Metadata resources perform two functions:
1. They describe the next level of resource
2. They support HATEOAS navigation of the resources
30
For example, metadata describing a Feature would include hyperlinks to all of the encodings of thatFeature.
7.8. Uniform InterfaceWFS 2.0 implements the Remote Procedure Call (RPC) pattern of defining an operation for eachfunction supported by a service. WFS 3.0 does not support service-unique operations. Rather, itfollows the REST pattern of implementing all functions through the HTTP verbs. All WFS 3.0"operations" are the result of applying an HTTP verb to a resource.
Table 1. HTTP Verbs
GET to retrieve resources
POST to create resources
PUT to modify existing resources
DELETE to remove resources
HEAD to test for the existence of resources
OPTIONS to get available options for a resource (e.g.which HTTP methods can be used)
Recommended Practice: OpenAPI allows you to assign a name to each operation. By assigning theappropriate WFS 2.0 operation name to each WFS 3.0 operation, the relationship between the twostandards will be clearer to client developers.
7.9. Safety and IdempotenceHTTP methods are characterized as safe and/or idempotent and servers should be mindful whenprocessing HTTP requests to not violate the safety and/or idempotence of the requested method.Safe methods are methods that do not modify the representation of a resource and so their resultscan be safely cached. Idempotent methods are methods that can be repeatedly processed but theireffect will always be the same. For example, whether a resource is deleted once or a dozen timesthe effect is still the same - the resource remains removed from the system. The following tableprovides an overview of the safety and /or idempotence of each HTTP method used in the RESTbinding:
Table 2. Safety and Idempotence of HTTP methods
HTTP Method Safe Idempotent
GET YES YES
PUT NO YES
POST NO NO
DELETE NO YES
HEAD YES YES
OPTIONS YES YES
31
Example 2. An unsafe implementation of GET
An unsafe implementation of the GET method would be to use the GET method to deleteresource from the server using a URL such as " GET /buildings/1013/delete".
(done)
32
Chapter 8. OpenAPI and Capabilities
8.1. UsageBoth the Capabilities document and an OpenAPI document can be used to describe the operationsand resources provided by a Service or API. In most cases they fill the same role in the Publish-Find-Bind pattern. However, OpenAPI documents have uses which go beyond descriptive metadata.
One of the precepts of API development is that you first design and document your API. OpenAPI isone of the ways an API design can be documented. This has led to a suite of tools which use theOpenAPI document as a design specification. These tools attempt to automate the generation ofsource code based on the design documented in the OpenAPI document. Some of them actuallywork.
So we have to look at OpenAPI as a form of Interface Description Language (IDL). As with olderIDLs (DCE, DCOM, CORBA, etc.) client developers can be expected to harvest the OpenAPI documentand auto-generate client code from it. API developers must take care that the OpenAPI documentsthey publish are complete and comprehensive enough that an auto-generated client will work.
If we view OpenAPI as an IDL, then the capabilities (OpenAPI) document is no longer anafterthought to be thrown together once everything else is done. Rather, it becomes a statement ofthe design itself.
8.2. Information MappingThe WFS 2.0 Capabilities document has five major sections:
• Service Identification,
• Service Provider,
• Operations Metadata,
• Feature Types, and
• Filter Capabilities.
Most of this information is also available from an OpenAPI (OAS) document. This Section willdescribe how the information from each of the sections of the WFS 2.0 Capability document couldbe supported through an OAS document.
8.2.1. Root
Both the Capabilities and OAS document provide basic data to assist clients in understanding thescope of the document. A mapping of that information is provided in Table 1.
Table 3. Root Level Information
Capabilities Path OpenAPI Path Comments
WFS_Capabilities OAS This is the root of our paths
33
Capabilities Path OpenAPI Path Comments
WFS_Capabilities/@version OAS/openapi Indicates the version of WFS orOpenAPI that that was used forthis service/API
WFS_Capabilities/@updateSequence
OAS/info/version Indicates the version of thisCapabilities/OAS document.
8.2.2. Service Identification
A Capabilities document describes a service while an OpenAPI document describes an API. This is acrucial distinction. APIs resist organization into a taxonomy. As a result, the service-oriented fieldsin the SerivceIdentification element cannot be populated in a meaningful way. So we find that theServiceType, ServiceTypeVersion, and Profile elements do not have OpenAPI equivalents. TheService Identification mappings are provided in Table 2.
Table 4. Service Identification Mapping
Capabilities Path OpenAPI Path Comments
WFS_Capabilities/ServiceIdentification
NA
./ServiceIdentification/Title OAS/info/title
./ServiceIdentification/Abstract OAS/info/description
./ServiceIdentification/Keywords
NA OAS tags may be used for thispurpose
./ServiceIdentification/ServiceType
NA
./ServiceIdentification/ServiceTypeVersion
NA
./ServiceIdentification/Profile NA
./ServiceIdentification/Fees OAS/info/termsOfService OpenAPI doesn’t define what aterms of service documentlooks like, but if there are feesassociated with this API, this iswhere they would bedocumented.
./ServiceIdentification/AccessConstraints
Security Requirement andLicense Objects
Discussed below
Access Constraints is one area where OpenAPI comes out ahead. The Capabilities documentprovides an XML string element with little guidance on how to use it. In an OAS document,applicable licenses are identified by name and made available to the client though a URL. OAS isalso capable of providing detailed information about the Authentication and Access Controls whichgovern the API. OpenAPI security support is discussed in detail in section 10 InformationAssurance.
34
8.2.3. Service Provider
Both the Capabilities document and OpenAPI provide information about the Points of Contact forthis service/API as well as information on how to contact them. Of the two, the Capabilitiesdocument is the more complete. However, the relevant OAS objects are extensible which allowsadditional information to be provided if needed.
The Service Provider information mapping is provided in Table 3.
Table 5. Service Provider Mapping
Capabilities Path OpenAPI Path Comments
WFS_Capabilities/ServiceProvider
NA Service Provider root
./ServiceProvider OAS/info/contact See discussion below
./ServiceProvider/ProviderName
NA
./ServiceProvider/ProviderSite OAS/servers/url WFS assumes a single serverwhile an API can expose many.There may be more than oneOAS Server Object. In addition,the url may be a URL templatedescribing multiple servers.
./ServiceProvider/ServiceContact
Contact information is one area where the Capabilities document outshines OAS. Table 4 containsthe Contact Information mapping. Many of the elements in the Capabilities document can only besupported by an OAS document extension.
Table 6. Contact Information Mapping
Capabilities Path Contact Object Field Comments
WFS_Capabilities/ServiceProvider/ServiceContact
NA root for contact information
./ServiceContact/individualName
name
./ServiceContact/positionName name
./ServiceContact/role name
./ServiceContact/contactInfo/Phone
extension
./ServiceContact/contactInfo/Address/electronicMailAddress
./ServiceContact/contactInfo/Address
extension For address informationbeyond the email address
35
Capabilities Path Contact Object Field Comments
./ServiceContact/contactInfo/OnlineResource
url
./ServiceContact/contactInfo/HoursOfService
extension
./ServiceContact/contactInfo/ContactInstructions
extension
8.2.4. Operations Metadata
WFS 2.0 relies on the standard to define the request response pairs. OpenAPI does not assume agoverning standard. Therefore, all of the information you need to generate a request or process aresponse is included in the OAS document.
Capabilities documents provide two levels of metadata. Operations Metadata provides informationwhich is applicable to all operations. Operation (singular) Metadata describes a single operation.
OpenAPI is resource oriented. So it starts with the path to the resource to be manipulated. The PathItem Objects provide information that applies to all operations against this resource. In particular,servers where the resource may be hosted, and parameters which can be used to manipulate theresource.
Path Item Objects also include Operation Objects corresponding to one or more of the HTTP verbs.Operation Objects provide the detailed information required to build an HTTP request and toprocess the expected returns.
Operations metadata are mapped against OpenAPI in Table 5. Operation metadata is mapped inTable 6.
Table 7. Operations Metadata Mapping
Capabilities Path OpenAPI Path Comments
WFS_Capabilities/OperationsMetadata
Path Root
./OperationsMetadata/Operation Path/{verb} Where {verb} = Get or Post
./OperationsMetadata/Parameter
Path/parameters
./OperationsMetadata/Constraint
None If populated, this informationshould be merged with theOperation-level Constraints.
Table 8. Operation Metadata Mapping
Capabilities Path OpenAPI Path Comments
WFS_Capabilities/OperationsMetadata/Operation
Path/{verb} Root
36
Capabilities Path OpenAPI Path Comments
./Operation/@name Path/*/operationId Only valid for Get and Post
./Operation/Parameter Path/parameters
./Operation/Constraint None
./Operation/DCP/HTTP/Get Path/get
./Operation/DCP/HTTP/Get/constraint
Path/get/parameters
./Operation/DCP/HTTP/Get/constraint
Path/get/security For WFS compliant with OWSSecurity.
./Operation/DCP/HTTP/Post Path/post
./Operation/DCP/HTTP/Post/constraint
Path/post/parameters
./Operation/DCP/HTTP/Post/constraint
Path/post/security For WFS compliant with OWSSecurity.
8.2.5. Feature Types
WFS 2.0 advertises the types of features exposed by that service. An API specifies resource types byPath and Operation. So a WFS 3.0 may expose many Feature Types, each on its' own set of Paths.Furthermore, resources exposed by an API are not required to be of a standard format. Therefore,it is not enough for an OpenAPI document to identify the output format, it needs to be able todescribe the output format.
This is arguably the one area where WFS 2.0 and 3.0 are radically different as evidenced in Table 7.
Table 9. Feature Type Mapping
Capabilities Path OpenAPI Path Comments
WFS_Capabilities/FeatureTypeList/FeatureType
Response Object Root
./FeatureType/Name Key If the Response Object isdefined in the ComponentsObject, then it has a keyassociated with it so it can bereferenced.
./FeatureType/Title None
./FeatureType/Abstract ResponseObject/description
./FeatureType/Keywords None
./FeatureType/DefaultCRS None
./FeatureType/OutputFormats ResponseObject/content/MediaTypeObject
Each MediaType Object has anassociate key
37
Capabilities Path OpenAPI Path Comments
./FeatureType/WGS84BoundingBox
None
./FeatureType/MetadataUrl None
The Mediatype Object is responsible for providing a complete description of the response. It hastwo fields for this purpose, the schema field and the encoding field.
The Schema field and associated Schema Object describe the logical structure of the response.OpenAPI uses a modified version of JSON Schema in the Schema Object. However, this has beenextended to also support "Alternative Schema". Alternative Schema allow one or more externaldefinitions of the schema to be used instead of the OAS schema. For example, a GML response canbe described by referencing the XML Schema and Schematron rules as alternative schema for thatresponse.
The Encoding field and associated Encoding Object describes how the response is encoded. Themost important field in the Encoding Object is the ContentType field. This is a text field whichshould be populated with IANA media type for the encoding used.
By specifying both the logical structure (schema) and the encoding of the response, OpenAPI canfully describe a response even if this particular resource has never existed before.
8.2.6. Filter Capabilities
The WFS 3.0 Core does not address Filter capabilities. Therefore we cannot map them into an OASrepresentation. This task will be addressed once the complex feature handling extensions arecomplete. (done)
38
Chapter 9. Information Assurance
9.1. OpenAPIOpenAPI provides two constructs to describe security controls; Security Scheme Objects, andSecurity Requirements.
9.1.1. Security Schemes
A Security Scheme Object provides a detailed description of a type of security control. They do notidentify where in the API the control should be applied. Currently the OpenAPI specificationsupports the following Security Schemes:
• HTTP authentication,
• API key (either as a header or as a query parameter),
• OAuth2’s common flows (implicit, password, application and access code) as defined inRFC6749, and
• OpenID Connect Discovery.
Support for client-side PKI certificates is planned for version 3.1.
Security Scheme Objects reside within the Components Object in the OAS document root. EachSecurity Scheme Object has an associated key. These keys allow a Security Scheme Object to bereferenced from elsewhere in the OAS document. The keys also allow for multiple flavors of ascheme type. For example, the keys "Bobs_API" and "Marys_API" could reference two Schemes oftype API Key that have different implementations (ex. header vs. query).
9.1.2. Security Requirements
Security Requirements Objects are used to identify where in the API a Security Scheme (orschemes) should be applied. These objects consist of a set of key-value pairs. Each key shouldcorrespond to a key for a Security Scheme Object. The Security Requirement is satisfied when all ofthe Security Schemes (identified by the keys) are satisfied. The associated values provide additionalinformation specific to this Security Requirement. Currently values are only defined for oauth2 andopenIDConnect schemes.
Security Requirements can be specified at two levels:
• Root: These Security Requirements apply to the whole document unless over-ridden.
• Operations: These Security Requirements apply to a single operation. These requirementsoverride any requirements specified at the root level.
Rules for Applicability:
1. When more than one Security Requirement is provided, only one has to be satisfied.
2. A Security Requirement may map to more than one Security Scheme. In that case, all of the
39
Schemes must be satisfied.
3. An empty Security Requirement object is valid. This indicates that there are no securitycontrols.
9.1.3. OpenAPI Security Issues:
The following issues have been taken to the OpenAPI Technical Steering Committee for resolution.
1. There is no way to directly associate a Security Requirement with a Server Object. This can leadto problems. Consider the case where an operation contains two Server Objects. These twoservers each implement a different form of authentication. There are Security Requirementobjects for each form of authentication. How does the client know which control goes withwhich server? The answer at this time is that they don’t.
2. The scope of a Security Requirement is ambiguous in regards to resources. If the result of anoperation is a document which contains links to other documents, does the SecurityRequirement apply to the links as well? Under the current version of OpenAPI we cannot tell forsure.
Our recommended way forward is to be aware of security constraints when designing your API.
1. If two servers have different authentication methods, then put them on different paths.
2. Organize your resources so that if a user can access one resource, then they can access alllinked resources as well.
3. Use the appropriate HTTP status codes and messages. If the client cannot authenticate, let themknow what is missing.
9.2. Access ControlThe OpenAPI document provides clients with the information they need to identify themselves tothe API and to prove (authenticate) that identity. But why would the API need this information? Onereason is to make sure that the resources managed by the API are only provided to clients who areauthorized to receive them. Access Controls are the Security Controls which assure that onlyauthorized parties can access each API resource.
Access Controls are an implementation detail which is usually not exposed to the user. However,they do have an impact on the behavior of the API. The following sections discuss some of the wayswhich the choice of access control can affect the client.
9.2.1. Bootstrap
Many users will come to an API with no a-priori knowledge of its' configuration or clientrequirements. The OpenAPI document provides them with the information they need to use theAPI. But what if some of the information in the OpenAPI document is restricted? Clients need theinformation from the OAS document in order to access the OAS document. This is known as a Catch22.
The OpenAPI specification does not restrict an API to just one OAS document. So one approach open
40
is to construct an open OAS document with only the information necessary to access the restrictedOAS document.
An OAS document is required to have the following content:
Table 10. Required OpenAPI Fields
Field Description
openapi The version of OpenAPI used in this document
info/title The title of this API
info/version The version of this OAS document
paths/ An empty paths value is valid
So the following is a valid OAS document:
openapi: 3.0.1info: title: A sample minimal OAS document version: 1.0path:
A bootstrap OAS document would add a bit more such as:
1. A path to the restricted OAS document
2. The Security requirements to access the restricted OAS document
3. The Server where the restricted OAS document resides
The following example "bootstrap" OAS document tells the client that the full OpenAPI documentcan be retrieved from https://secure.example.org/api and that it is protected by OAuth.
41
openapi: 3.0.1servers: - url: 'https://secure.example.org/' description: Restricted access serverinfo: version: "1.0.0" title: A bootstrap OAS document description: >- This is an example of using OAuth2 Password Flow in a specification to describesecurity to your API.security: - password: - readpaths: /api: get: summary: The protected OAS document responses: '200': description: OKcomponents: schemas: {} securitySchemes: password: type: oauth2 flows: password: tokenUrl: 'http://example.com/oauth/token' scopes: read: allows reading resources
9.2.2. Discrete Resources
The most common means of access control is to restrict access to a discrete resource. The UNIX filesystem, for example, can restrict a user’s ability to read, write, execute, or delete a file. Similar filesystem based discretionary access controls are supported by most platforms. It’s a simple matterfor an API to control access to its resources through this platform capability. For example, a userissues a PUT request on a resource. If the file system indicates that resource is read-only, then theuser will receive a 403 (forbidden) response.
Complications arise when a request involves more than one resource. For example, a GET requestagainst a collection (such as a file system directory) could return all of the resources within thatcollection. Assuming that the user has read access to all of the resources. If some, but not all, of theresources are not readable, then the API designer must decide to throw a 403 or return just thoseresources which are readable. Once decided, this behavior should be consistent across the API.
An more challenging case is when a user has access to only a part of a resource. In the bootstrapdiscussion above, the unauthenticated user only has access to a small portion of the OpenAPIdocument. Since each resource is discrete, there is no way to return just part of a resource.
42
Therefore, we need two (or more) copies of each resource with protected content.
An API developer has to decide how they are going to handle multiple copies of the same resource.Three approaches that can be used are:
1. Use different Servers based on security restrictions.
2. Use different resource names based on the security restrictions on the resource.
3. Use different paths based on security restrictions.
Different Servers are a simple solution as long as the security restrictions can be expressed as asmall number of categories. It is not difficult define three servers hosting secret, sensitive, and opendata respectively. On the other hand, this would not work well if each user has user-specificprivileges.
Note: that OpenAPI does not associate Security Requirements with Server Objects. So the securityrestrictions on each server should be included in the description.
Different Resource Names is another simple approach. Like Different Servers, this works best if thesecurity restrictions can be expressed as a small number of categories. Resource names have theadvantage that the user can decide if they will be able to access the resource prior to issuing arequest. In addition, since Security Requirements can be assigned at the Operation level, users willalso know what form of authentication is required to access the resource.
Different Paths is a more generalized version of the Different Resources approach. Its' majoradvantage is that it supports user-specific access controls. For example, the path/collections/{uid}/buildings/items would return the "buildings" features which user {uid} can access.
9.2.3. Dynamic Resources
Consider a relational database (RDMS) with row-based access control. Now package that databasebehind an API. The resources exposed through the API are generated at run time. Upon receiving arequest, the API will select those rows which the user is authorized to access, build the response,and return it to the user. This approach takes the API design completely out of the picture. Servers,paths, and resource names are the same for the highly privileged and the unprivileged users. Allthat changes is the content of the resource returned.
There is an important property to this approach which must be considered. Different users, usingthe same URL, will get different results. So a URL cannot be used as a unique identifier for theresource. (done)
43
Chapter 10. Conformance ChecklistsWFS 3.0 Core Conformance Checklist
Derived from the [WFS 3.0, Part 1, version 3.0.0-draft.1](https://rawcdn.githack.com/opengeospatial/ogcapi-features/3.0.0-draft.1/docs/17-069.html#_requirement_class_core).
• (recommended) checkboxes aren’t strictly necessary for conformance
• (optional) checkboxes have value but may be ignored without problem
7.2 [API landing page](https://rawcdn.githack.com/opengeospatial/ogcapi-features/3.0.0-draft.1/docs/17-069.html#_api_landing_page) * [ ] GET request at / served * [ ] Response content is based on[landingPage.yaml](https://raw.githubusercontent.com/opengeospatial/ogcapi-features/master/core/openapi/schemas/landingPage.yaml) and minimally includes links to: * [ ] /api * [ ] /conformance *[ ] /collections
7.3 [API Definition](https://rawcdn.githack.com/opengeospatial/ogcapi-features/3.0.0-draft.1/docs/17-069.html#_api_definition_2) * [ ] GET request at /api served * [ ] Response content is the apidefinition document * [ ] (recommended) Response content is OpenAPI format * If multiple formatsare provided, use content negotiation
7.4 [Declaration of conformance classes](https://rawcdn.githack.com/opengeospatial/ogcapi-features/3.0.0-draft.1/docs/17-069.html#_declaration_of_conformance_classes) * [ ] GET request at/conformance served * [ ] Response content is based on OpenAPI schema[confClasses.yaml](https://raw.githubusercontent.com/opengeospatial/ogcapi-features/master/core/openapi/schemas/confClasses.yaml). * [ ] conformsTo in response contains * [ ]http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/core * [ ] (recommended)http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/html * [ ] (recommended)http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/geojson * [ ] (recommended)http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/oas30
7.5 [HTTP 1.1](https://rawcdn.githack.com/opengeospatial/ogcapi-features/3.0.0-draft.1/docs/17-069.html#_http_1_1) * [ ] Conforms to [HTTP 1.1](https://rawcdn.githack.com/opengeospatial/ogcapi-features/3.0.0-draft.1/docs/17-069.html#rfc2616), including correct use of [statuscodes](https://rawcdn.githack.com/opengeospatial/ogcapi-features/3.0.0-draft.1/docs/17-069.html#http_status_codes), headers, etc. * [ ] Conforms to [HTTP over TLS](https://rawcdn.githack.com/opengeospatial/ogcapi-features/3.0.0-draft.1/docs/17-069.html#rfc2818), if HTTPS is used * [ ](recommended) Supports [entity tags](https://rawcdn.githack.com/opengeospatial/ogcapi-features/3.0.0-draft.1/docs/17-069.html#rfc2616)
7.7 [Support for cross-origin requests](https://rawcdn.githack.com/opengeospatial/ogcapi-features/3.0.0-draft.1/docs/17-069.html#cross_origin) * [ ] (recommended) If the server will be accessed fromthe browser, allow cross-origin requests.
7.8 [Encodings](https://rawcdn.githack.com/opengeospatial/ogcapi-features/3.0.0-draft.1/docs/17-069.html#_encodings_2) * [ ] (recommended) HTML5 * [ ] (recommended) GeoJSON * See [MediaTypes](https://rawcdn.githack.com/opengeospatial/ogcapi-features/3.0.0-draft.1/docs/17-069.html#mediatypes) for guidance * For multiple encodings, the server needs a mechanism to mintencoding-specific links, such as /my/url.geojson or /my/url?f=geojson
44
7.9 [Coordinate reference systems](https://rawcdn.githack.com/opengeospatial/ogcapi-features/3.0.0-draft.1/docs/17-069.html#_coordinate_reference_systems) * [ ] Geometries are served inWGS84 longitude/latitude unless another is requested (similar to EPSG/SRID 4326, but with axisorder longitude/latitude). * There is currently no mechanism to request another CRS.
7.10 [Link headers](https://rawcdn.githack.com/opengeospatial/ogcapi-features/3.0.0-draft.1/docs/17-069.html#_link_headers) * [ ] (recommended) All links in response payloads are included as Linkheaders as well.
7.11 [Feature collections metadata](https://rawcdn.githack.com/opengeospatial/ogcapi-features/3.0.0-draft.1/docs/17-069.html#_feature_collections_metadata) * [ ] GET request at /collectionsserved * [ ] Response content based on [collections.yaml](https://raw.githubusercontent.com/opengeospatial/ogcapi-features/master/core/openapi/schemas/collections.yaml) * [ ] Response"links" property includes: * [ ] rel "self" * [ ] rel "alternate" for each additional encoding available * [] (recommended) For each external link defining structure or semantics of data contained incollections, include a link w/ rel "describedby" * [ ] Response "collections" property includes anentry for each feature collection. * [ ] For each supported encoding include a link w/ rel "items" tothe feature collection * [ ] If response provides an "extent" property it is formatted as a boundingbox of the form [SWlong, SWlat, NElong, NElat] for the spatial and [begin, end] for the temporalextent * [ ] All links include "rel" * [ ] All links include "type" specifying content type
7.12 [Feature collection metadata](https://rawcdn.githack.com/opengeospatial/ogcapi-features/3.0.0-draft.1/docs/17-069.html#_feature_collection_metadata) * [ ] GET request at/collections/{collectionId} served * [ ] Response is metadata for the collection indicated using thesame schema as in 7.11.
7.13 [Feature collections](https://rawcdn.githack.com/opengeospatial/ogcapi-features/3.0.0-draft.1/docs/17-069.html#_feature_collections) * [ ] GET request at /collections/{collectionId}/items served* [ ] "limit" query parameter indicating max number of features to provide at once. * [ ] "limit"parameter includes "minimum" with value 1 * [ ] "limit" parameter includes (changeable) "default"* [ ] "limit" parameter includes (changeable) "maximum" * [ ] "bbox" query parameter. Onlyfeatures intersecting this rectangle are returned. * [ ] "datetime" query parameter. Only featuresintersecting this time stamp or interval are returned. * [ ] (recommended) For simple int/stringproperties of features include a querystring parameter with the property name to filter on. Forstrings, wildcard matches may be useful in addition to simple equality. * [ ] Response includes links:* [ ] rel "self" * [ ] rel "alternate", one for every other content type * [ ] (recommended) rel "next" foradditional features beyond limit. * [ ] "next" link uses same rules for "limit" * [ ] (optional) rel "prev"to mirror functionality of "next" * [ ] all links include "ref" & "type" * [ ] Response includesmetadata, if it not too complex to compute: * [ ] timeStamp as the time stamp of the response * [ ]numberMatched set to the number of features matching the query * [ ] numberReturned set to thenumber of features in this response (page)
7.14 [Feature](https://rawcdn.githack.com/opengeospatial/ogcapi-features/3.0.0-draft.1/docs/17-069.html#_feature_2) * [ ] GET request at /collections/{collectionId}/items/{featureId} served * [ ]Response payload contains the feature identified. * [ ] Response includes links: * [ ] rel "self" * [ ] rel"alternate" for other content types supported. * [ ] rel "collection" (validate against ATS)
45
Chapter 11. Media TypesJSON media types that would typically be used in a WFS that supports JSON are
• application/json for feature collection metadata, and
• application/geo+json for feature collections and features.
XML media types that would typically occur in a WFS that supports XML are
• application/xml for feature collection metadata,
• application/gml+xml;version=3.2 for any GML 3.2 feature collections and features,
• application/gml+xml;version=3.2;profile="http://www.opengis.net/def/profile/ogc/2.0/gml-sf0" for GML 3.2 feature collections and features conforming to the GML Simple Feature Level 0profile, and
• application/gml+xml;version=3.2;profile="http://www.opengis.net/def/profile/ogc/2.0/gml-sf2" for GML 3.2 feature collections and features conforming to the GML Simple Feature Level 2profile.
The typical HTML media type for all "web pages" in a WFS would be text/html.
The media type for an OpenAPI definition in JSON is application/vnd.oai.openapi+json;version=3.0.
NOTEThe media type for the OpenAPI definition has not yet been registered with IANA.See https://github.com/OAI/OpenAPI-Specification/issues/110. (done)
46
Annex A: Revision HistoryDate Release Editor Primary
clausesmodified
Description
2018-08-15 0.1 C. Heazel all initial version
(Done)
47
Annex B: Bibliography• W3C/OGC: Spatial Data on the Web Best Practices, W3C Working Group Note 28 September 2017,
https://www.w3.org/TR/sdw-bp/
• W3C: Data on the Web Best Practices, W3C Recommendation 31 January 2017,https://www.w3.org/TR/dwbp/
• IANA: Link Relation Types, https://www.iana.org/assignments/link-relations/link-relations.xml(Review and update as needed)
48