+ |
Open Geospatial Consortium |
+
Submission Date: <yyyy-mm-dd> |
+
Approval Date: <yyyy-mm-dd> |
+
Publication Date: 2021-08-27 |
+
External identifier of this OGC® document: http://www.opengis.net/doc/IS/ogcapi-common-2/1.0 |
+
Internal reference number of this OGC® document: 20-024 |
+
Version: 0.0.9 |
+
Category: OGC® Implementation Standard |
+
Editor: Charles Heazel |
+
OGC API - Common - Part 2: Geospatial Data |
+
Copyright notice |
+
Copyright © 2021 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. This document 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 relevant patent rights of which they are aware and to provide supporting documentation.
+Document type: OGC® Implementation Standard |
+
Document stage: Draft |
+
Document language: English |
+
License Agreement
+Permission is hereby granted by the Open Geospatial Consortium, ("Licensor"), free of charge and subject to the terms set forth below, to any person obtaining a copy of this Intellectual Property and any associated documentation, to deal in the Intellectual Property without restriction (except as set forth below), including without limitation the rights to implement, use, copy, modify, merge, publish, distribute, and/or sublicense copies of the Intellectual Property, and to permit persons to whom the Intellectual Property is furnished to do so, provided that all copyright notices on the intellectual property are retained intact and that each person to whom the Intellectual Property 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 to the above copyright notice, a notice that the Intellectual Property includes modifications that have not been approved or adopted by LICENSOR.
+THIS LICENSE IS A COPYRIGHT LICENSE ONLY, AND DOES NOT CONVEY ANY RIGHTS UNDER ANY PATENTS THAT MAY 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 PARTICULAR PURPOSE, AND NONINFRINGEMENT OF THIRD PARTY RIGHTS. THE COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE DO NOT WARRANT THAT THE FUNCTIONS CONTAINED IN THE INTELLECTUAL PROPERTY WILL MEET YOUR REQUIREMENTS OR THAT THE OPERATION OF THE INTELLECTUAL PROPERTY WILL BE UNINTERRUPTED OR ERROR FREE. ANY USE OF THE INTELLECTUAL PROPERTY SHALL BE MADE ENTIRELY AT THE USER’S OWN RISK. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR ANY CONTRIBUTOR OF INTELLECTUAL PROPERTY 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 ALLEGED INFRINGEMENT OR ANY LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR 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 Property together with all copies in any form. The license will also terminate if you fail to comply with any term or condition of this Agreement. Except as provided in the following sentence, no such termination of this license shall require the termination of any third party end-user sublicense to the Intellectual Property which is in force as of the date of notice 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 a third party, you agree that LICENSOR, in its sole discretion, may terminate this license without any compensation or liability to you, your licensees or any other party. You agree upon termination of any kind to destroy or cause to be destroyed 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 the Intellectual Property shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Intellectual Property without prior written authorization of LICENSOR or such copyright holder. LICENSOR is and shall at all times be the sole entity that may authorize you or any third party to use certification marks, trademarks or other special designations to indicate compliance with any LICENSOR standards or specifications. This Agreement is governed by the laws of the Commonwealth of Massachusetts. The application to this Agreement of the United Nations Convention on Contracts for the International Sale of Goods is hereby expressly excluded. In the event any provision of this Agreement shall be deemed unenforceable, void or invalid, such provision shall be modified so as to make it valid and enforceable, and as so modified the entire Agreement shall remain in full force and effect. No decision, action or inaction by LICENSOR shall be construed to be a waiver of any rights or remedies available to it.
+-
+
- 1. Introduction +
- 2. Scope +
- 3. Conformance +
- 4. References +
- 5. Terms, Definitions and Abbreviated Terms + + +
- 6. Conventions + + +
- 7. Overview + + +
- 8. Requirements Class "Collections" + + +
- 9. Requirements Class "Simple Query" + + +
- 10. Requirements Class "Uniform Multi-Dimension Collection" + + +
- 11. Encoding Requirements Classes + + +
- 12. Media Types +
- 13. Security Considerations +
- Annex A: Abstract Test Suite (Normative) + + +
- Annex B: Examples (Informative) + + +
- Annex C: Revision History +
- Annex D: Glossary +
- Annex E: Bibliography +
- Annex F: Backus-Naur Forms + + +
- Annex G: HTTP Status Codes +
- Annex H: OGC Web API Guidelines +
1. Introduction
+i. Abstract
+The OGC has extended their suite of standards to include Resource Oriented Architectures and Web APIs. In the course of developing these standards, some practices proved to be common across multiple OGC Web API standards. These common practices are documented in the OGC API - Common Multi-Part Standard. OGC API - Common standards serve as reusable building-blocks. Standards developers will use these building-blocks in the construction of OGC Web API Standards. The result is a modular suite of coherent API standards which can be adapted by an system designer for the unique requirements of their system.
+Spatial data is rarely considered as a single entity. Feature Collections, Coverages, Data Sets, they are all aggregations of Spatial or Temporal Things. It stands to reason that an OGC Web API would also expose its' holdings as aggregates of spatial resources.
+The purpose of the OGC API - Common - Part 2: Geospatial Data Standard (API-GeoData) is to provide a common connection between the API landing page and resource-specific details. That connection includes metadata which describes the hosted geospatial resources, common parameters for selecting subsets of those resources, and URI templates for identifying the above.
+This common connection is sufficient to start the client down the path to resource discovery. Developers of OGC Web API standards extend these first steps with details specific to the resources they intend to expose.
+ii. Keywords
+The following are keywords to be used by search engines and document catalogues.
+ogcdoc, OGC document, geographic information, spatial data, spatial things, dataset, distribution, API, json, html, OpenAPI, REST, Common
+iii. Preface
+OGC Declaration
+Attention is drawn to the possibility that some of the elements of this document may be the subject of patent rights. The Open Geospatial Consortium Inc. shall not be held responsible for identifying any or all such patent rights.
+Recipients of this document are requested to submit, with their comments, notification of any relevant patent claims or other intellectual property rights of which they may be aware that might be infringed by any implementation of the standard set forth in this document, and to provide supporting documentation.
+iv. Submitting organizations
+The following organizations submitted this Document to the Open Geospatial Consortium (OGC):
+-
+
-
+
Heazeltech LLC
+
+ -
+
CubeWerx Inc.
+
+
v. Submitters
+All questions regarding this submission should be directed to the editors or the submitters:
+Name |
+Affiliation |
+
Chuck Heazel (editor) |
+Heazeltech |
+
Panagiotis (Peter) A. Vretanos |
+CubeWerx Inc. |
+
others |
+TBD |
+
2. Scope
+The OGC API - Common Standard is a multi-part standard which defines a standard set of modules which can be used to build resource and mission-specific Web API standards. The OGC API - Common - Part 2: Geospatial Data Standard (API-GeoData) is one of those modules.
+Geospatial resources are typically packaged into sets or collections of related resources. A single API may host a large number of collections. This API-Geodata standard provides a means of organizing these collections and defines operations for discovering and selecting individual collections.
+API-GeoData does not specify the nature of the geospatial data that make up a collection. Rather, it provides a basic capability which should be applicable to any geospatial resource type. Additional OGC Web API standards extend this foundation to define resource-specific capabilities.
+3. Conformance
+Conformance with this standard shall be checked using the tests specified in Annex A (normative) of this document. The framework, concepts, and methodology for testing, and the criteria to claim conformance are specified in the OGC Compliance Testing Policies and Procedures and the OGC Compliance Testing web site.
+The one Standardization Target for this standard is Web APIs.
+API-GeoData defines API modules intended for re-use by other OGC Web API standards. It is anticipated that this standard will only be implemented through inclusion in other standards. Therefore, all the relevant abstract tests in Annex A shall be included or referenced in the Abstract Test Suite for each separate standard that normatively references this standard.
+API-GeoData builds on API modules defined in the OGC API - Common - Part 1: Core
(API-Core) Standard. Each Requirements Class in the API-GeoData Standard identifies the API-Core Conformance Classes upon which it depends.
Proof of conformance with a Requirements Class includes demonstration of conformance with all dependencies of that Requirements Class. Unless otherwise specified, conformance only has to be demonstrated for those operations, parameters, and resources which are defined in that Requirements Class.
+This standard identifies five conformance classes. The conformance classes implemented by an OGC API are advertised through the /conformance
path on the landing page. Each conformance class is defined by one requirements class. The tests in Annex A are organized by Requirements Class. So an implementation of the Collections conformance class must pass all tests specified in Annex A for the Collections requirements class.
The requirements classes for API-GeoData are:
+-
+
- + + +
- + + +
- + + +
- + + +
- + + +
The Collections Requirements Class defines a common means to describe and access collections of spatial resources.
+The Simple Query Requirements Class defines basic query parameters for the selection of individual collections of spatial resources.
+The Uniform Multi-Dimension Collection Requirements Class extends the Simple Query Requirements Class to support selection of individual collections of spatial resources in an arbitrary uniform multi-dimension space.
+The Collections Requirements Class does not mandate a specific encoding or format for representing resources. The HTML and JSON requirements classes specify representations for these resources in commonly used encodings for spatial data on the web.
+The structure and organization of a collection of spatial resources is very much dependent on the nature of that resource and the expected access patterns. This is information which cannot be specified in a common manner. This Standard specifies the requirements necessary to discover and understand a generic collection and its' contents. Requirements governing a specific type of resource are specified in resource-specific OGC API standards.
+4. References
+The following normative documents contain provisions that, through reference in this text, constitute provisions of this document. For dated references, subsequent amendments to, or revisions of, any of these publications do not apply. For undated references, the latest edition of the normative document referred to applies.
+-
+
-
+
Klyne, G., Newman, C.: IETF RFC 3339, Date and Time on the Internet: Timestamps, http://tools.ietf.org/rfc/rfc3339.txt
+
+ -
+
Fielding, R., Reschke, JSchaub: IETF RFC 7231, Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content, https://tools.ietf.org/rfc/rfc7231.txt
+
+ -
+
Bray, T.: IETF RFC 8259, The JavaScript Object Notation (JSON) Data Interchange Format, http://tools.ietf.org/rfc/rfc8259.txt* Nottingham, M.: IETF RFC 8288, Web Linking, http://tools.ietf.org/rfc/rfc8288.txt
+
+ -
+
Nottingham, M.: IETF RFC 8288, Web Linking, http://tools.ietf.org/rfc/rfc8288.txt
+
+ -
+
ISO 8601-1:2019, Date and time - Representations for information interchange - Part 1: Basic rules
+
+ -
+
ISO 19111:2019, Geographic information ⎯ Spatial referencing by coordinates
+
+ -
+
json-schema-org: JSON Schema, September 2019, https://json-schema.org/specification.html
+
+ -
+
Open API Initiative: OpenAPI Specification 3.0.3, https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md
+
+ -
+
Herring, J.: OGC 06-104r4,OpenGIS® Implementation Standard for Geographic information - Simple feature access - Part 2: SQL option, http://portal.opengeospatial.org/files/?artifact_id=25354
+
+ -
+
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
+
+ -
+
Heazel, C.: OGC 19-072, OGC API - Common - Part 1: Core, http://docs.opengeospatial.org/DRAFTS/19-072.html
+
+ -
+
W3C: HTML5, W3C Recommendation, http://www.w3.org/TR/html5/
+
+ -
+
Schema.org: http://schema.org/docs/schemas.html
+
+
5. Terms, Definitions and Abbreviated Terms
+5.1. Terms and Definitions
+This document uses the terms defined in Sub-clause 5 of OGC API - Common - Part 1: Core (OGC 19-072), which is based on the ISO/IEC Directives, Part 2, Rules for the structure and drafting of International Standards. In particular, the word "shall" (not "must") is the verb form used to indicate a requirement to be strictly followed to conform to this standard.
+For the purposes of this document, the following additional terms and definitions apply.
+-
+
-
+
Collection
+
+A body of resources that belong or are used together. An aggregate, set, or group of related resources. (OGC 20-024)
+
-
+
-
+
Coverage
+
+feature that acts as a function to return values from its range for any direct position within its spatiotemporal domain, as defined in OGC Abstract Topic 6 (OGC 09-146r6)
+
-
+
-
+
Dataset
+
+A collection of data, published or curated by a single agent, and available for access or download in one or more representations. (DCAT)
+
-
+
-
+
Distribution
+
+A specific representation of a dataset. A dataset might be available in multiple serializations that may differ in various ways, including natural language, media-type or format, schematic organization, temporal and spatial resolution, level of detail or profiles (which might specify any or all of the above). (DCAT)
+
+EXAMPLE: a downloadable file, an RSS feed or an API.
+
-
+
-
+
Extent
+
+The area covered by something. Within this document, we always imply spatial extent; e.g. size or shape that may be expresses using coordinates. (W3C/OGC Spatial Data on the Web Best Practice)
+
-
+
-
+
Feature
+
+abstraction of real world phenomena (ISO 19101-1:2014)+
++ + ++ + + + + +NOTE:
+More details about the term
feature
may be found in the W3C/OGC Spatial Data on the Web Best Practice in the section Spatial Things, Features and Geometry.
+
-
+
-
+
Feature Collection
+
+a set of Features from a dataset
+
-
+
-
+
Geometry
+
+An ordered set of n-dimensional points in a given coordinate reference system. (W3C/OGC Spatial Data on the Web Best Practice)
+
-
+
-
+
OGC Web API
+
+A Web API that implements one or more Conformance Classes from an OGC API Standard.
+
-
+
-
+
Resource
+
+entity that might be identified (Dublin Core Metadata Initiative - DCMI Metadata Terms)+
++ + ++ + + + + +NOTE:
+The term "resource", when used in the context of an OGC Web API standard, should be understood to mean a Web Resource unless otherwise indicated.
+
-
+
-
+
Resource Type
+
+the definition of a type of resource. Resource types are re-usable components which are independent of where the resource resides in the API.+
++ + ++ + + + + +NOTE:
+Resource types are re-usable components that are independent of where the resource resides in the API."
+
-
+
-
+
Spatial Resource
+
+the resources which we usually think of as Geospatial Data. A Spatial Thing. (OGC 19-072)
+
-
+
-
+
Spatial Thing
+
+anything with spatial extent, (i.e. size, shape, or position) and is a combination of the real-world phenomenon and its abstraction. (W3C/OGC Spatial Data on the Web Best Practice)
+
-
+
-
+
Temporal Coordinate System
+
+temporal reference system based on an interval scale on which distance is measured as a multiple of a single unit of time. (ISO 19108)
+
-
+
-
+
Temporal Position
+
+location relative to a temporal reference system (ISO 19108)
+
-
+
-
+
Temporal Reference System
+
+reference system against which time is measured (ISO 19108)
+
-
+
-
+
Temporal Resource
+
+the resources which we usually think of as time and date focused data. A Temporal Thing. (OGC 19-072)
+
-
+
-
+
Temporal Thing
+
+Anything with temporal extent, i.e. duration. e.g. the taking of a photograph, a scheduled meeting, a GPS time-stamped track-point. (W3C Basic Geo)
+
-
+
-
+
Web API
+
+API using an architectural style that is founded on the technologies of the Web. (W3C Data on the Web Best Practices)
+
-
+
-
+
Web Resource
+
+a resource that is identified by an URI.
+
5.2. Abbreviated terms
+-
+
- API +
-
+
Application Programming Interface
+
+ - CORS +
-
+
Cross-Origin Resource Sharing
+
+ - CRS +
-
+
Coordinate Reference System
+
+ - HTTP +
-
+
Hypertext Transfer Protocol
+
+ - HTTPS +
-
+
Hypertext Transfer Protocol Secure
+
+ - IANA +
-
+
Internet Assigned Numbers Authority
+
+ - OGC +
-
+
Open Geospatial Consortium
+
+ - TRS +
-
+
Temporal Coordinate Reference System
+
+ - URI +
-
+
Uniform Resource Identifier
+
+ - YAML +
-
+
YAML Ain’t Markup Language
+
+
6. Conventions
+All conventions described in the OGC API - Common Part 1: Core Standard are also applicable to this API-Common Part 2: Geospatial Data Standard except where modified in the following section.
+6.1. Identifiers
+The normative provisions in this standard are denoted by the URI http://www.opengis.net/spec/ogcapi-common-2/1.0
.
All Requirements, Requirements Modules and Conformance Modules that appear in this document are denoted by partial URIs that are relative to this base.
+Additional information about the use of Identifiers in API-Common is provided in the OGC API - Common Users Guide.
+6.2. Link relations
+RFC 8288 (Web Linking) is used by this standard to express relationships between resources. Link relation types from the IANA Link Relations Registry are used wherever possible. Additional link relation types are registered with the OGC Naming Authority.
+The link relationships used in API-Common GeoData are described in Table 1. Additional relation types may be used if the implementation warrants it.
+Link Relation | +Purpose | +
---|---|
|
+Refers to a substitute for this context [IANA]. |
+
+ | Identifies general metadata for the context (dataset or collection) that is primarily intended for consumption by machines. |
+
|
+The target IRI points to a resource which represents the collection resource for the context IRI. [IANA] |
+
+ | Refers to a resource that identifies the specifications that the link’s context conforms to. [OGC] |
+
+ | Indicates that the link’s context is a distribution of a dataset that is an API and refers to the root resource of the dataset in an API. [OGC] |
+
|
+Refers to a resource providing information about the link’s context.[IANA] |
+
|
+The target IRI points to a resource that is a member of the collection represented by the context IRI. [IANA] |
+
+ | Refers to a resource that is comprised of members of the collection represented by the link’s context. [OGC] |
+
|
+Refers to a license associated with this context. [IANA] |
+
|
+Conveys an identifier for the link’s context. [IANA] |
+
|
+Identifies service description for the context that is primarily intended for consumption by machines. [IANA] |
+
|
+Identifies service documentation for the context that is primarily intended for human consumption. [IANA] |
+
|
+Identifies general metadata for the context that is primarily intended for consumption by machines. [IANA] |
+
Additional information on the use of link relationships is provided in the OGC API - Common Users Guide.
+6.3. Geometry
+6.3.1. Geospatial Geometry
+Standardized concepts for geospatial characteristics are needed in order to share geographic information between applications. Concepts for shape (geometry) are key. These concepts are standardized in ISO 19107.
+The geospatial geometry used in the OGC API - Common Standards is documented in the GML Simple Features Profile Standard. This Profile defines a subset of the ISO 19107 geometry which is aligned with the OGC Simple Features for SQL Standard. That geometry includes: Point, Curve (LineString), Surface (Polygon), MultiPoint, MultiCurve, and MultiSurface.
+6.3.2. Temporal Geometry
+Standardized concepts for temporal characteristics are also needed in order to share date and time information between applications. OGC API Common adopts the Gregorian calendar and a 24 hour time keeping system for its temporal geometry. All representations of that geometry which are discussed in this document conform to RFC 3339.
+6.4. Coordinate Reference Systems
+As discussed in Chapter 9 of the W3C/OGC Spatial Data on the Web Best Practices document, the ability to express and share location in a consistent way is one of the most fundamental aspects of publishing geographic data. To do so, it is important to be clear about the coordinate reference system (CRS) within which the coordinates are expressed.
+This OGC API - Common Geospatial Data standard does not mandate the use of a specific coordinate reference system. However, if no CRS is specified, the following default coordinate reference systems apply for spatial geometries.
+-
+
-
+
CRS84 - WGS 84 longitude and latitude without height
+
+ -
+
CRS84h - WGS 84 longitude and latitude with ellipsoidal height
+
+
Temporal geometry is measured relative to an underlying temporal coordinate reference system (TRS). This OGC API - Common - Part 2: Geospatial Data Standard does not mandate a specific temporal coordinate reference system. However, all dates or timestamps discussed in this document are in the Gregorian calendar and conform to RFC 3339. In data, other temporal coordinate reference systems may be used where appropriate.
+ISO 19111 provides the conceptual model for Coordinate Reference Systems.
+6.5. API definition
+6.5.1. General remarks
+This OGC standard specifies requirements and recommendations for the development of APIs that share spatial resources using a standard way of doing so. In general, APIs will go beyond the requirements and recommendations stated in this standard. They will support additional operations, parameters, and so on that are specific to the API or the software tool used to implement the API.
+So that developers can more easily learn how to use the API, good documentation is essential. In the best case, documentation would be available both in HTML for human consumption and in a machine readable format that can be processed by software for run-time binding. OpenAPI is one way to provide that machine readable documentation.
+6.5.2. Role of OpenAPI
+This OGC API Standard uses OpenAPI 3.0 fragments in examples and to formally state requirements. Using OpenAPI 3.0 is not required for implementing an OGC API. Other API definition languages may be used along with, or instead of, OpenAPI. However, any API definition language used should have an associated conformance class advertised through the /conformance
path.
This standard includes a conformance class for API definitions that follow the OpenAPI specification 3.0. Alternative API definition languages are also allowed. Conformance classes for additional API definition languages will be added as the OGC API landscape continues to evolve.
+6.5.3. References to OpenAPI components in normative statements
+Some normative statements (requirements, recommendations and permissions) use a phrase that a component in the API definition of the server must be "based upon" a schema or parameter component 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 OpenAPI schema components.
+ -
+
The range of values of a parameter or property may be extended (additional values) or constrained (only a subset of all possible values is allowed). An example for a constrained range of values is to explicitly specify the supported values of a string parameter or property using an enum.
+
+ -
+
Additional properties may be added to the schema definition of a Response Object.
+
+ -
+
Informative text, such as comments or description properties, may be changed or added.
+
+
For OGC API definitions that do not conform to the OpenAPI Specification 3.0, the normative statement should be interpreted in the context of the API definition language used.
+6.5.4. Reusable OpenAPI components
+Reusable components for OpenAPI definitions for an OGC API are referenced from this document. They are available from the OGC Schemas Registry at http://schemas.opengis.net/ogcapi/common/part1/1.0 and http://schemas.opengis.net/ogcapi/common/part2/1.0
+Additional information on the use of OpenAPI as an API definition is provided in the OGC API - Common Users Guide.
+7. Overview
+This API-Common Geospatial Data Standard provides a common connection between the API landing page and resource-specific specifications or standards.
+7.1. Collections
+Spatial data is rarely considered as a single entity. Feature Collections, Coverages, Data Sets, they are all aggregations of Spatial or Temporal Things. It stands to reason that an OGC Web API would also expose its holdings as aggregates of spatial/temporal resources.
+The purpose of the OGC API - Common - Part 2: Geospatial Data Standard is to provide a common connection between the API landing page and resource-specific details. That connection includes metadata which describes the hosted resources, common parameters for selecting subsets of the hosted resources, and URI templates for identifing the above.
+A contentous issue is the term used to describe an aggregation of resources. The term should be consistent with its coloquial use, should indicate that the members of the aggregation are somehow associated, and it should be independent of any resource type.
+Merriam Websters Dictionary provides a few relevant definitions :
+-
+
-
+
Collection: "An accumulation of objects gathered for study, comparison, or exhibition or as a hobby."
+
+ -
+
Aggregate: (a synonym to collection) "A mass or body of units or parts somewhat loosely associated with one another."
+
+ -
+
Set: "A number of things of the same kind that belong or are used together."
+
+
Based on these definitions, the term collection
will be used in this standard to indicate an aggregation of resources. For purposes of this standard, a collection is defined as follows:
-
+
-
+
Collection: A body of resources that belong or are used together. An aggregate, set, or group of related resources.
+
+
OGC Web API standards should extend this definition to address the specific properties of the resources they describe.
+7.2. Views
+A collection of geospatial data may be represented in more than one way. For example, a point cloud may be represented as a collection of Features, or as a Coverage, or as a color-coded map. Each is a representation of the same data. But the access methods and returned data structures are very different. OGC Web API standards refer to these representations as views
.
Views
should not be confused with encodings. HTTP content negotiation allows a client to negotiate the encoding (XML, JSON, etc.) to be used for the returned data. Regardless of the encoding, the underlying data model is the same. A view
, on the other hand, is both a data model and a set of access mechanisms. It is an addressible resource in its own right and must be treated as such.
The API-Common Geodata Standard does not define any views
. These are defined in separate OGC Web API standards. What is important to understand is how these view-specific standards extend the API-Common Geodata Standard.
The URI for a view of a collection folows the URI template:
+/collections/{collectionId}/{viewId}+
Where:
+-
+
-
+
collectionId = an identifier for the collection
+
+ -
+
viewId = an identifier for the type of view.
+
+
So the URIs for the point cloud described above could be:
+For Features: /collections/mycollection/items
For coverages: /collections/mycollection/coverage
For Maps: /collections/mycollection/maps
The view identifiers are maintained as a controlled vocabulary by the OGC.
+Additional information on Views is provided in the OGC API - Common Users Guide.
+8. Requirements Class "Collections"
+Requirements Class |
+|
http://www.opengis.net/spec/ogcapi-common-2/1.0/req/collections |
+|
Target type |
+Web API |
+
Dependency |
++ |
Dependency |
++ |
Dependency |
++ |
Dependency |
++ |
Dependency |
++ |
Dependency |
++ |
Dependency |
++ |
Dependency |
++ |
+ Note
+ |
++This Requirements Class is dependent on API-Common Part 1 section 8.1. Content from Part 1 Section 8.2 has been included in Annex F for reference. + | +
This Requirements Class describes the resources and operations used to describe and access resource collections exposed through an OGC Web API. It does not include any requirements about how resources are aggregated into collections nor about the aggregated resources themselves. That detail is reserved for resource-specific OGC Web API standards (see Views Section)..
+The two resources defined in this Requirements Class are summarized in Table 2.
+Resource | +URI | +HTTP Method | +Description | +
---|---|---|---|
+ | /collections |
+GET |
+Information which describes the set of available Collections |
+
+ | /collections/{collectionId} |
+GET |
+Information about a specific collection of geospatial data with links to distribution |
+
8.1. Collections
+OGC APIs typically organize their Spatial Resources into collections. Information about those collections is accessed through the /collections
path and the http://www.opengis.net/def/rel/ogc/1.0/data link relation.
8.1.1. Operation
+Requirement 1 |
+
+ /req/collections/rc-md-op + |
+
A |
+
+ The API SHALL support the HTTP GET operation at the path |
+
8.1.2. Response
+Requirement 2 |
+
+ /req/collections/rc-md-success + |
+
A |
+
+ A successful execution of the operation SHALL be reported as a response with a HTTP status code |
+
B |
+
+ The content of that response SHALL be based upon the JSON schema collections.json. + |
+
The collections response returned by this operation is based on the collections.json JSON schema. Examples of collections responses are provided in Collections Response Example.
+{
+ "$schema": "http://json-schema.org/draft-07/schema#",
+ "title": "Collections Schema",
+ "description": "This schema defines the resource returned from /collections path.",
+ "type": "object",
+ "required": [
+ "links",
+ "collections"
+ ],
+ "properties": {
+ "links": {
+ "type": "array",
+ "items": {"$href": "link.json"}
+ },
+ "timeStamp": {
+ "type": "string",
+ "format": "date-time"
+ },
+ "numberMatched": {
+ "type": "integer",
+ "min": "0"
+ },
+ "numberReturned": {
+ "type": "integer",
+ "min": "0"
+ },
+ "collections": {
+ "type": "array",
+ "items": {"$href": "collectionDesc.json"}
+ }
+ }
+ }
+This schema is further constrained by the following requirements and recommendations.
+To support hypermedia navigation, the links
property must be populated with sufficient hyperlinks to navigate through the whole dataset.
Requirement 3 |
+
+ /req/collections/rc-md-links + |
+
A |
+
+
+A
+
|
+
B |
+
+ All links SHALL include the |
+
Additional information may be available to assist in understanding and using this dataset. Links to those resources should be provided as well.
+Recommendation 1 |
+
+ /rec/collections/rc-md-descriptions + |
+
A |
+
+ If external schemas or descriptions exist that provide additional information about the structure or semantics for the resource, a |
+
B |
+
+ The |
+
The timeStamp
property of the Collections response indicates when the response was generated.
Requirement 4 |
+
+ /req/collections/rc-timeStamp + |
+
A |
+
+ If a property |
+
The collections
property of the Collections response provides a description of each individual collection hosted by the API. These descriptions are based on the Resource Collection Schema. This schema is described in detail in the Resource Collection section of this Standard.
Requirement 5 |
+
+ /req/collections/rc-md-items + |
+
A |
+
+ For each spatial resource collection accessible through this API, metadata describing that collection SHALL be provided in the |
+
B |
+
+ The content of that response SHALL comply with the requirements in the http://www.opengis.net/spec/ogcapi-common-2/1.0/rm/collection Requirements Class desecribed in section Collection Resource Definition of this Standard. + |
+
A client may wish to select a subset of the hosted collections using HTTP query parameters. The Simple Query Conformance Class defines the bbox
and the datetime
parameter for that purpose. It also defines how a server should process those parameters. These parameters are evaluated against the extent
element of each Collection item in the Collections response.
The requirements governing the processing of these parameters are provided by the Simple Query Requirements Class.
+Requirement 6 |
+
+ /req/collections/rc-bbox-unsupported + |
+
A |
+
+ If the |
+
Requirement 7 |
+
+ /req/collections/rc-datetime-unsupported + |
+
A |
+
+ If the |
+
The Simple Query Conformance Class also defines a parameter to limit the number of collections returned in a response. This limit
parameter indicates the maximum number of collections which should be included in a single response.
Requirement 8 |
+
+ /req/collections/rc-limit-unsupported + |
+
A |
+
+ If the |
+
+ Note
+ |
++This requirement does not preclude server imposed limits on the size of a response. + | +
8.1.3. Error situations
+See HTTP Status Codes for general guidance.
+8.2. Resource Collection
+Each resource collection is described by a set of metadata. That metadata is accessed directly using the /collections/{collectionId}
path or as an entry in the collections
property of the Collections resource.
8.2.1. Operation
+Requirement 9 |
+
+ /req/collections/src-md-op + |
+
A |
+
+ The API SHALL support the HTTP GET operation at the path |
+
B |
+
+ The parameter |
+
8.2.2. Response
+Requirement 10 |
+
+ /req/collections/src-md-success + |
+
A |
+
+ A successful execution of the operation SHALL be reported as a response with a HTTP status code |
+
B |
+
+ The content of that response SHALL comply with the requirements in the http://www.opengis.net/spec/ogcapi-common-2/1.0/rm/collection Requirements Class secribed in section Collection Resource Definition of this Standard. + |
+
C |
+
+ The content of that response SHALL be consistent with the content for this collection in the |
+
8.2.3. Error Situations
+See HTTP Status Codes for general guidance.
+If the parameter collectionId
does not exist on the server, the status code of the response will be 404
(see Table 5).
8.2.4. Collection Resource Definition
+Requirements Module |
+|
http://www.opengis.net/spec/ogcapi-common-2/1.0/rm/collection |
+|
Target type |
+Web API |
+
Description |
+The Collection resource provides clients with a basic understanding of a single collection. It also serves as a starting point for further navigation through the collection. |
+
Requirements |
+/req/collections/collection-definition |
+
Recommendations and Permissions |
+/rec/collections/rc-md-item-type |
+
Examples of Collection resources are provided in Collection Object Examples.
+Requirement 11 |
+
+ /req/collections/collection-definition + |
+
A |
+
+ The content of a |
+
{
+ "$schema": "http://json-schema.org/draft-07/schema#",
+ "title": "Collection Resource Schema",
+ "description": "This schema defines the resource returned from /collections/{collectionId}.",
+ "type": "object",
+ "required": [
+ "id",
+ "links"
+ ],
+ "properties": {
+ "id": {
+ "description": "identifier of the collection used, for example, in URIs",
+ "type": "string"
+ },
+ "title": {
+ "description": "human readable title of the collection",
+ "type": "string"
+ },
+ "description": {
+ "description": "a description of the members of the collection",
+ "type": "string"
+ },
+ "attribution" : {
+ "type" : "string",
+ "title" : "attribution for the collection",
+ "description" : "The `attribution` should be short and intended for presentation to a user, for example, in a corner of a map. Parts of the text can be links to other resources if additional information is needed. The string can include HTML markup."
+ },
+ "links": {
+ "type": "array",
+ "items": {"$href": "link.json"}
+ },
+ "extent": {"$href": "extent.json"},
+ "itemType": {
+ "description": "An indicator about the type of the items in the collection.",
+ "type": "string"
+ },
+ "crs": {
+ "description": "the list of coordinate reference systems supported by the API; the first item is the default coordinate reference system",
+ "type": "array",
+ "items": {
+ "type": "string"
+ },
+ "default": [
+ "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
+ ],
+ "example": [
+ "http://www.opengis.net/def/crs/OGC/1.3/CRS84",
+ "http://www.opengis.net/def/crs/EPSG/0/4326"
+ ]
+ }
+ }
+ }
+Many of the properties of the Collection resource are self-explanitory. However, a few call for additional explanation.
+Attribution
+The attribution element is a special type of string property. Specifically, it can contain markup text. Markup allows a text string to import images and format text. The capabilities are only limited by the markup language used. See the example collection response for an example of the use of markup in the attribution element.
+Item Type
+In some Geospatial collections, the members (items
) that make up that collection can be individually accessed by a client. In this case, the itemType
property in the Collection resource identifies the type of the items
accessible from that collection.
Recommendation 2 |
+
+ /rec/collections/rc-md-item-type + |
+
A |
+
+ If the members ( |
+
Links
+To support hypermedia navigation, the links
property must be populated with sufficient hyperlinks to navigate through the whole dataset.
Requirement 12 |
+
+ /req/collections/rc-md-items-links + |
+
A |
+
+
+
+
|
+
B |
+
+ All links SHALL include the |
+
Additional information may be available to assist in understanding and using this dataset. Links to those resources should be provided as well.
+Recommendation 3 |
+
+ /rec/collections/rc-md-items-descriptions + |
+
A |
+
+ If external schemas or descriptions exist that provide additional information about the structure or semantics of the collection, a |
+
B |
+
+ The |
+
Extent
+The extent property defines a spatial-temporal surface which encompasses the geospatial data in the collection. Since not all collections are nicely clustered around a single place in space and time, the extent property provides flexibility in how that surface can be defined.
+-
+
-
+
Spatial Bounding Box (Bbox) provides a set of rectangular bounding boxes which use geographic coordinates to envelope portions of the collection. Typically only the first element would be populated. Additional boxes may be useful, for example, when the collection is clustered in multiple, widely-separated locations.
+
+ -
+
Temporal Interval provides a set of temporal periods. Typically only the first temporal period would be populated. However, like bbox, additional periods can be added if the collection does not form a single temporal cluster.
+
+
Requirement 13 |
+
+ /req/collections/rc-md-extent + |
+
A |
+
+ For each spatial collection resource, the |
+
B |
+
+ If a spatial resource has multiple properties with spatial or temporal information, it is the decision of the API implementation whether only a single spatial or temporal geometry property is used to determine the extent or all relevant geometries. + |
+
Recommendation 4 |
+
+ /rec/collections/rc-md-extent + |
+
A |
+
+ If an extent contains multiple spatial boundaries (multiple bbox, etc.), then the extent SHOULD include in the first bbox a boundary which represents the union of all of the other boundaries. + |
+
B |
+
+ If an extent contains multiple temporal intervals, then the extent SHOULD include as the first interval an interval which represents the union of all of the other intervals. + |
+
Recommendation 5 |
+
+ /rec/collections/rc-md-extent-single + |
+
A |
+
+ While the spatial and temporal extents support multiple bounding boxes ( |
+
Permission 1 |
+
+ /per/collections/rc-md-extent-extensions + |
+
A |
+
+ API-Common only specifies requirements for spatial and temporal extents. However, the |
+
B |
+
+
+API-Common only supports +
+
+
+ These are the only enum values in extent.json). + |
+
C |
+
+ Extensions MAY add additional reference systems to the |
+
9. Requirements Class "Simple Query"
+Requirements Class |
+|
http://www.opengis.net/spec/ogcapi-common-2/1.0/req/simple-query |
+|
Target type |
+Web API |
+
Dependency |
++ |
Dependency |
++ |
Dependency |
++ |
Dependency |
++ |
Dependency |
++ |
Dependency |
++ |
Dependency |
++ |
+ Note
+ |
++This Requirements Class is dependent on API-Common Part 1 Sections 8.1, 8.3, and 8.8. + | +
This Requirements Class describes query parameters that can be used to discover and select resource collections exposed through an OGC Web API.
+9.1. Parameter Requirements
+Query parameters are used in URIs to limit the resources which are returned on a GET request. The OGC API - Common - Part 2: Geospatial Data Standard identifies three query parameters for use in OGC API standards:
+The behavior generated by these parameters is specific to the operation and resource upon which they are applied. Those behaviors are described for each resource type and operation in the Target Resource Requirements section.
+Use of these query parameters with any specific operation is optional. Developers of API-GeoData servers should document their supported parameters in the API definition as describe in API-Core.
+9.1.1. Parameter bbox
+Requirements Module |
+|
+ | |
Target type |
+Web API Query Parameter |
+
The bbox
parameter is used to select resources based on the geospatial footprint or extent.
The bbox
parameter is defined as follows:
Requirement 14 |
+
+ /req/collections/rc-bbox-definition + |
+
A |
+
+
+The
+
+
+
+ |
+
B |
+
+
+The bounding box SHALL be provided as four or six numbers, depending on whether the coordinate reference system includes a vertical axis (height or depth): +
+
|
+
C |
+
+ If the bounding box consists of four numbers, the coordinate reference system of the values SHALL be interpreted as WGS 84 longitude/latitude (http://www.opengis.net/def/crs/OGC/1.3/CRS84) unless a different coordinate reference system is specified in a parameter |
+
D |
+
+ If the bounding box consists of six numbers, the coordinate reference system of the values SHALL be interpreted as WGS 84 longitude/latitude/ellipsoidal height (http://www.opengis.net/def/crs/OGC/0/CRS84h) unless a different coordinate reference system is specified in a parameter |
+
While the processing of the bbox
parameter is specific to the resource and operation for which it is applied, there is a general set of requirements which all implementations must address.
Requirement 15 |
+
+ /req/collections/rc-bbox-response + |
+
A |
+
+ If the |
+
B |
+
+ If a resource has multiple spatial geometry properties, it is the decision of the server whether only a single spatial geometry property is used to determine the extent or all relevant geometries. + |
+
C |
+
+ The |
+
D |
+
+ The coordinate values provided with the |
+
"Intersects" means that a coordinate that is part of the spatial geometry of the resource falls within the area specified in the parameter bbox
. This includes the boundaries of the geometries. For curves the boundary includes the start and end position. For surfaces the boundary includes the outer and inner rings.
In case of a degenerate bounding box, the resulting geometry is used. For example, if the lower left corner is the same as the upper right corner, all resources match where the geometry intersects with this point.
+This standard does not specify requirements for the parameter bbox-crs
. Those requirements will be specified in a later version of this standard.
The bounding box for WGS 84 longitude/latitude is, in most cases, the sequence of minimum longitude, minimum latitude, maximum longitude and maximum latitude. However, in cases where the box spans the anti-meridian (180th meridian) the first value (west-most box edge) is larger than the third value (east-most box edge).
+The bounding box of the New Zealand Exclusive Economic Zone in WGS84 (from 160.6°E to 170°W and from 55.95°S to 25.89°S) would be represented in JSON as [ 160.6, -55.95, -170, -25.89 ]
and in a query as bbox=160.6,-55.95,-170,-25.89
.
Note that the server will return an error if a latitude value of 160.0
is used.
If the vertical axis is included, the third and the sixth number are the bottom and the top of the 3-dimensional bounding box.
+A template for the definition of the parameter in YAML according to OpenAPI 3.0 is available at bbox.yaml.
+9.1.2. Parameter datetime
+Requirements Module |
+|
+ | |
Target type |
+Web API Query Parameter |
+
The datetime
parameter selects resources based on their temporal extent. The definition of temporal extent is specific to the resource type being filtered.
The datetime
parameter is defined as follows:
Requirement 16 |
+
+ /req/collections/rc-datetime-definition + |
+
A |
+
+
+The
+
+
+
+ |
+
B |
+
+
+Temporal geometries are either a date-time value or a time interval. The parameter value SHALL conform to the following syntax (using ABNF): +
+
+
+
+ |
+
C |
+
+ The syntax of |
+
D |
+
+ Open ranges in time intervals at the start or end are supported using a double-dot ( |
+
While the processing of the datetime
parameter is specific to the resource and operation for which it is applied, there is a general set of requirements which all implementations must address.
Requirement 17 |
+
+ /req/collections/rc-datetime-response + |
+
A |
+
+ If the |
+
B |
+
+ If a resource has multiple temporal properties, the decision of the server whether only a single temporal property is used to determine the extent or all relevant temporal properties. + |
+
C |
+
+ The |
+
"Intersects" means that the time (instant or period) specified in the parameter datetime
includes a timestamp that is part of the temporal geometry of the resource (again, a time instant or period). For time periods this includes the start and end time.
Note |
+
+ ISO 8601-2 distinguishes open start/end timestamps (double-dot) and unknown start/end timestamps (empty string). For queries, an unknown start/end has the same effect as an open start/end. + |
+
February 12, 2018, 23:20:52 GMT:
+time=2018-02-12T23%3A20%3A52Z
For resources with a temporal property that is a timestamp (like lastUpdate
), a date-time value would match all resources where the temporal property is identical.
For resources with a temporal property that is a date or a time interval, a date-time value would match all resources where the timestamp is on that day or within the time interval.
+February 12, 2018, 00:00:00 GMT to March 18, 2018, 12:31:12 GMT:
+datetime=2018-02-12T00%3A00%3A00Z%2F2018-03-18T12%3A31%3A12Z
February 12, 2018, 00:00:00 UTC or later:
+datetime=2018-02-12T00%3A00%3A00Z%2F..
March 18, 2018, 12:31:12 UTC or earlier:
+datetime=..%2F2018-03-18T12%3A31%3A12Z
A template for the definition of the parameter in YAML according to OpenAPI 3.0 is available at datetime.yaml.
+9.1.3. Parameter limit
+Requirements Module |
+|
+ | |
Target type |
+Web API Query Parameter |
+
The limit
parameter limits the number of resources that can be returned in a single response.
Requirement 18 |
+
+ /req/collections/rc-limit-definition + |
+
A |
+
+
+The
+
+
+
+ |
+
Note: |
+
+ The values for |
+
While the processing of the limit
parameter is specific to the resource and operation for which it is applied, there is a general set of requirements which all implementations must address.
Requirement 19 |
+
+ /req/collections/rc-limit-response + |
+
A |
+
+ If the |
+
B |
+
+ If the API definition specifies a maximum value for the |
+
C |
+
+ Only items are counted that are on the first level of the collection. Any nested objects contained within the explicitly requested items SHALL not be counted. + |
+
The number of resources returned depends on the server and the value of the limit
parameter.
-
+
-
+
The client can request a limit to the number of resources returned.
+
+ -
+
The server may have a default value for the limit, and a maximum limit.
+
+ -
+
If the server has any more results available than it returns (the number it returns is less than or equal to the requested/default/maximum limit) then the server will include a link to the next set of results.
+
+
Permission 2 |
+
+ /per/collections/rc-server-limit + |
+
A |
+
+ If a server is configured with a maximum response size, then the server MAY page responses which exceed that threshold. + |
+
Since many servers will place a limit on the size of their responses, clients should be prepared to handle a paged response even if they have not specified a limit
parameter in their query.
The effect of the limit parameter is to divide the response into a number of pages. Each page (except for the last) contains the specified number of entities. The response contains the first page. Additional pages can be accessed through hyperlink navigation.
+Recommendation 6 |
+
+ /rec/collections/rc-next-1 + |
+
A |
+
+ A |
+
Recommendation 7 |
+
+ /rec/collections/rc-next-2 + |
+
A |
+
+ Dereferencing a |
+
Recommendation 8 |
+
+ /rec/collections/rc-next-3 + |
+
A |
+
+ The number of resources in a response to a |
+
Providing prev
links supports navigating back and forth between pages, but depending on the implementation approach it may be too complex to implement.
Permission 3 |
+
+ /per/collections/rc-prev + |
+
A |
+
+ A response to a |
+
9.2. Target Resource Requirements
+The target of the parameters defined in this conformance class is the Collection resource described in the Collections Requirements Class. The purpose of these parameters is to select a subset of Collection resources to be included in the response to a /collections request.
+Three parameters are defined for use with the Collections resource. These parameters subset the set of Collection entries returned based on spatial, temporal, and volumetric filters. These parameters are documented in the Parameter Requirements section.
+The collections
property of the Collections response provides a description of each individual collection hosted by the API. These descriptions are based on the Resource Collection Schema. This schema is described in detail in the Resource Collection section of this Standard.
9.2.1. Spatial and Temporal Filtering
+A client may select a subset of the hosted collections using the bbox
and the datetime
parameter. These parameters are evaluated against the extent
element of each Collection item in the Collections response.
The requirements governing the processing of these parameters are:
+Requirement 20 |
+
+ /req/collections/rc-bbox-collection-response + |
+
A |
+
+ The API server SHALL process the |
+
B |
+
+ The |
+
Requirement 21 |
+
+ /req/collections/rc-datetime-collection-response + |
+
A |
+
+ The API server SHALL process the |
+
B |
+
+ The |
+
9.2.2. Volumetric Filtering
+The client may limit the number of collections returned in a response by using the limit
parameter. When applied against the /collections
resource, the limit
parameter indicates the maximum number of collections which should be included in a single response.
Requirement 22 |
+
+ /req/collections/rc-limit-collection-response + |
+
A |
+
+ If the |
+
B |
+
+ If the API definition specifies a maximum value for the |
+
The server also has the option of limiting the size of the Collections response.
+Permission 4 |
+
+ /per/collections/rc-md-items + |
+
A |
+
+ To support servers with many collections, servers MAY limit the number of items included in the |
+
9.2.3. Paged Response
+If the collections response does not contain all of the collection resources available from this server, then the client should be informed of that fact.
+Recommendation 9 |
+
+ /rec/collections/rc-paged-response + |
+
A |
+
+ If the number of items in the |
+
The numberMatched
property of the Collections response indicates the number of Collection items included in the Collections response. This may be a subset of the total set of collections hosted by the API. Selection of which collections to include in a subset is controled through the bbox
, datetime
and other selection parameters provided by the client.
Requirement 23 |
+
+ /req/collections/rc-numberMatched + |
+
A |
+
+ If a property |
+
B |
+
+ A server MAY omit this information in a response, if the information about the number of matching resources is not known or difficult to compute. + |
+
The number of collection items included in a Collections response may be a subset of the number matched. In that case, the numberReturned
property of the Collections response indicates the number of collection items returned in this "page" of the Collections response.
Requirement 24 |
+
+ /req/collections/rc-numberReturned + |
+
A |
+
+ If a property |
+
B |
+
+ A server MAY omit this information in a response, if the information about the number of resources in the response is not known or difficult to compute. + |
+
If the Collections response contains a subset of the selected collection items (numberReturned is less than numberMatched) then the Collections response should contain links for navigating to the rest of the collection items as described in the limit parameter section.
+10. Requirements Class "Uniform Multi-Dimension Collection"
+Requirements Class |
+|
http://www.opengis.net/spec/ogcapi-common-2/1.0/req/umd-collection |
+|
Target type |
+Web API |
+
Dependency |
++ |
The Collections Requirements Class defines a Collection resource which supports both geospatial and temporal geometries. However, some resources cannot be fully described with just these two geometries. The Uniform Multi-Dimension Collection Requirements Class extends the Collection resource to support geometries with an unlimited number of uniform, domain-specific axis. This Requirements Class also defines how that geometry can be evaluated through HTTP query parameters.
+10.1. Uniform Multi-Dimension Collection Definition
+The Uniform Multi-Dimension Collection is an extension of the Collection resource. So all of the requirements defined in Collections Requirements Class are required.
+Support for domain-specific Collections is supplied by the Extent with Uniform Additional Dimensions
requirements module.
Requirements Module |
+|
http://www.opengis.net/spec/ogcapi-common-2/1.0/rm/extent-uad |
+|
Target type |
+Web API Resource |
+
Dependencies |
+Collections Requirements Class |
+
The Extent with Uniform Additional Dimensions
(Extent-uad) element extends the Extent element defined in the http://www.opengis.net/spec/ogcapi-common-2/1.0/req/collections Requirements Class to support domain-specific geometries.
The Extent-uad
parameter is defined as follows:
Requirement 25 |
+
+ /req/common/extent-uad-definition + |
+
A |
+
+ The content of an |
+
Extent-uad
extends the Extent
element with a new uniform-md
property.
Since the Extent-uad
element extends the Extent
element, all operations applied against the Extent
element will have identical behavior when applied against Extend-uad
.
uniform-md:
+ description: "extends the Extent object to support domain-specific geometries defined by axis names and the occupied interval alone each access."
+ type: object
+ properties:
+ orderedAxes:
+ description: axis labels of all dimensions listed in CRS order. Spatial dimensions should be listed separately here.
+ type: array
+ minItems: 1
+ items:
+ type: string
+ intervals:
+ description: One interval for each axis. An interval describes the extent of the dataset along that axis.
+ type: array
+ minItems: 1
+ items:
+ description: Lower and upper bound values of the interval.
+ type: array
+ minItems: 2
+ maxItems: 2
+ items:
+ type: string
+ nullable: 'true'
+10.2. Multi-Dimension Collection Selection
+Selection and access of a Uniform Multi-Dimension Collection is similar to that of a Collection resource. All of the requirements defined in the Simple Query Requirements Class also apply to this Requirements Class. So all of the requirements defined in Collections Requirements Class are required.
+However, the parameters defined in Simple Query only operate against the spatial
and temporal
properties of the Extent. An additional parameter is needed to operate against the uniform-md
property. The Subset
parameter fills that role. This parameter is defined in the Subset
requirements module.
Requirements Module |
+|
+ | |
Target type |
+Web API Query Parameter |
+
The subset
parameter is used to select a subset of a geospatial resource.
The subset
parameter is defined as follows:
Requirement 26 |
+
+ /req/collections/rc-subset-definition + |
+
A |
+
+
+The
+
+
+
+ |
+
B |
+
+ The axis name SHALL correspond to one of the axis of the Coordinate Reference System (CRS) of the target resource or else return a 400 status code. + |
+
C |
+
+ If the intervalOrPoint values fall entirely outside the range of valid values defined for the identified axis, a 204 status code SHALL be returned + |
+
D |
+
+ For a CRS where an axis can wrap around, such as subsetting across the dateline (anti-meridian) in a geographic CRS, a |
+
+ Note
+ |
++When the intervalOrPoint values fall partially outside of the range of valid values defined by the CRS for the identified axis, the service is expected to return the non-empty portion of the resource resulting from the subset. + | +
While the processing of the subset
parameter is specific to the resource and operation for which it is applied, there is a general set of requirements which all implementations must address.
Requirement 27 |
+
+ /req/collection/subset-response + |
+
A |
+
+ Only that part of the resource that falls within the bounds of the subset expression SHALL be returned. + |
+
B |
+
+ If an lower limit of the subset expression is populated with an asterix "*" THEN the mainumum extent of the resource along that axis SHALL be selected. + |
+
C |
+
+ If an upper limit of the subset expression is populated with an asterix "*" THEN the maximum extent of the resource along that axis SHALL be selected. + |
+
11. Encoding Requirements Classes
+11.1. Overview
+This clause specifies two requirements classes for encodings to be used with the Collections and Collection resources. These encodings are commonly used encodings for spatial data on the web:
+None of these encodings are mandatory. An implementation of the Collections requirements class may implement either, both, or none of them.
+11.2. Requirement Class "HTML"
+Geographic information that is only accessible in formats like GeoJSON or GML has two issues:
+-
+
-
+
The data is not discoverable using the most common mechanism for discovering information, that is the search engines of the Web,
+
+ -
+
The data can not be viewed directly in a browser - additional tools are required to view the data.
+
+
Therefore, sharing data on the Web should include publication in HTML. To be consistent with the Web, it should be done in a way that enables users and search engines to access all data.
+This is discussed in detail in W3C Best Practice. This standard therefore recommends supporting HTML as an encoding.
+Requirements Class |
+|
+ | |
Target type |
+Web API |
+
Dependency |
++ |
Dependency |
++ |
Dependency |
++ |
Requirement 28 |
+
+ /req/html/definition + |
+
A |
+
+
|
+
Requirement 29 |
+
+ /req/html/content + |
+
A |
+
+
+Every
+
|
+
Recommendation 10 |
+
+ /rec/html/schema-org + |
+
A |
+
+ A |
+
11.3. Requirement Class "JSON"
+JSON is a text syntax that facilitates structured data interchange between programming languages. It commonly used for Web-based software-to-software interchanges. Most Web developers are comfortable with using a JSON-based format, so supporting JSON is recommended for machine-to-machine interactions.
+Requirements Class |
+|
+ | |
Target type |
+Web API |
+
Dependency |
++ |
Dependency |
+IETF RFC 8259: The JavaScript Object Notation (JSON) Data Interchange Format |
+
Dependency |
++ |
Requirement 30 |
+
+ /req/json/definition + |
+
A |
+
+
|
+
Requirement 31 |
+
+ /req/json/content + |
+
A |
+
+ Every |
+
B |
+
+ The schema of all responses with the media type |
+
JSON Schema for the Collections and Collection responses are available at collections.yaml and collectionDesc.yaml.
+These are generic schemas that do not include any application schema information about specific resource types or their properties.
+12. Media Types
+JSON media types that would typically be supported by a server that supports JSON are:
+-
+
-
+
+application/geo+json
for feature collections and features, and
+ -
+
+application/json
for all other resources.
+
XML media types that would typically be supported by a server that supports XML are:
+-
+
-
+
+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 0 profile,
+ -
+
+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 2 profile, and
+ -
+
+application/xml
for all other resources.
+
The typical HTML media type for all "web pages" in a server would be text/html
.
13. Security Considerations
+See OGC API - Common - Part 1: Core, Clause 11.
+add additional text as needed
+Annex A: Abstract Test Suite (Normative)
+A.1. Introduction
+OGC Web APIs are not a Web Services in the traditional sense. Rather, they define the behavior and content of a set of Resources exposed through a Web Application Programing Interface (Web API). Therefore, an API may expose resources in addition to those defined by the standard. A test engine must be able to traverse the API, identify and validate test points, and ignore resource paths which are not to be tested.
+A.2. Conformance Class Collections
+Conformance Class |
+|
http://www.opengis.net/spec/ogcapi-common-2/1.0/conf/collections |
+|
Target type |
+Web API |
+
Requirements Class |
+http://www.opengis.net/spec/ogcapi_common-2/1.0/req/collections |
+
Dependency |
++ |
Conformance with the Collections Conformance Class is demonstrated by execution, in order, of the following tests:
+-
+
- + + +
- + + +
IF the Simple Query Conformance Class has not been implemented, then also execute test ats/collections/rc-md-simple-query-unsupported
+A.2.1. Collections {root}/collections Tests
+Abstract Test 1 |
+
+ /ats/collections/rc-md-op + |
+
Test Purpose |
+
+ Validate that information about the Collections can be retrieved from the expected location. + |
+
Requirement |
++ |
Test Method |
+
+
|
+
Abstract Test 2 |
+
+ /ats/collections_rc-md-success + |
+
Test Purpose |
+
+ Validate that the Collections content complies with the required structure and contents. + |
+
Requirement |
++ |
Test Method |
+
+
|
+
The Collections content may be retrieved in a number of different formats. The following table identifies the applicable schema document for each format and the test to be used to validate against that schema. All supported formats should be exercised.
+Format | +Schema Document | +Test ID | +
---|---|---|
HTML |
++ | + |
JSON |
++ | + |
Abstract Test 3 |
+
+ /ats/collections/rc-md-links + |
+
Test Purpose |
+
+ Validate that the required links are included in the Collections document. + |
+
Requirement |
++ |
Test Method |
+
+
+Verify that the response document includes: +
+
+
+ Verify that all links include the |
+
Abstract Test 4 |
+
+ /ats/collections/rc-timestamp + |
+
Test Purpose |
+
+ If a |
+
Requirement |
++ |
Test Method |
+
+
+IF the Collections document contains a
+
|
+
Note: |
+
+ The two minute threshold was chosen to allow for test script processing time and clock synchronization issues. + |
+
Abstract Test 5 |
+
+ /ats/collections/rc-md-items + |
+
Test Purpose |
+
+ Validate that each collection accessible through the API is described in the Collections document. + |
+
Requirement |
++ |
Test Method |
+
+
|
+
A.2.2. Collection {root}/collections/{collectionId} Tests
+Abstract Test 6 |
+
+ /ats/collections/src-md-op + |
+
Test Purpose |
+
+ Validate that the Collection content can be retrieved from the expected location. + |
+
Requirement |
++ |
Test Method |
+
+
+For every Collection described in the Collections content, issue an HTTP GET request to the URL
+
|
+
Abstract Test 7 |
+
+ /ats/collections/src-md-success + |
+
Test Purpose |
+
+ Validate that the Collection content complies with the required structure and contents. + |
+
Requirement |
++ |
Test Method |
+
+
|
+
Abstract Test 8 |
+
+ /ats/collections/rc-md-collection-content + |
+
Test Purpose |
+
+ Validate that a Collection document complies with the required structure and values. + |
+
Requirement |
++ |
Test Method |
+
+
+FOR a each Collection document, validate: +
+
|
+
The Collection content may be retrieved in a number of different formats. The following table identifies the applicable schema document for each format and the test to be used to validate against that schema. All supported formats should be exercised.
+Format | +Schema Document | +Test ID | +
---|---|---|
HTML |
++ | + |
JSON |
++ | + |
Abstract Test 9 |
+
+ /ats/collections/rc-md-items-links + |
+
Test Purpose |
+
+ Validate that a Collection document includes all required links. + |
+
Requirement |
++ |
Test Method |
+
+
|
+
Abstract Test 10 |
+
+ /ats/collections/rc-md-extent + |
+
Test Purpose |
+
+ Validate the |
+
Requirement |
++ |
Test Method |
+
+
+IF the
+
|
+
Note: |
+
+ A temporal extent of |
+
A.2.3. Simple Query Tests
+Abstract Test 11 |
+
+ /ats/collections/rc-md-simple-query-unsupported + |
+
Test Purpose |
+
+ Validate proper handling of the Simple Query parameters if the Simple Query Conformance Class has not been implemented. + |
+
Requirement |
++ |
Test Method |
+
+
+IF the Simple Query Conformance Class is not supported by this API implementation, THEN: +
+
|
+
A.3. Conformance Class Simple query
+Conformance Class |
+|
http://www.opengis.net/spec/ogcapi-common-2/1.0/conf/simple-query |
+|
Target type |
+Web API |
+
Requirements Class |
+http://www.opengis.net/spec/ogcapi_common-2/1.0/req/simple-query |
+
Dependency |
++ |
Conformance with the Simple Query Conformance Class is demonstrated by execution of the following tests:
+A.3.1. Bounding Box Tests
+Abstract Test 12 |
+
+ /ats/collections/rc-op-bbox + |
+
Test Purpose |
+
+ Validate that resources can be identified and extracted from an API server using the bbox query parameter. + |
+
Requirement |
++ |
Test Method |
+
+
|
+
Abstract Test 13 |
+
+ /ats/collections/rc-bbox-definition + |
+
Test Purpose |
+
+ Validate that the bounding box query parameter is constructed correctly. + |
+
Requirement |
++ |
Test Method |
+
+
+Verify that the
+
+
+
+
+
+
+Use a bounding box with four numbers in all requests where the collection has spatial geometries in 2D: +
+
+
+
+Use a bounding box with six numbers in all requests where the collection has spatial geometries in 3D: +
+
|
+
Abstract Test 14 |
+
+ /ats/collections/rc-bbox-response + |
+
Test Purpose |
+
+ Validate that the |
+
Requirement |
++ |
Test Method |
+
+
+DO FOR each
+
|
+
A.3.2. Date-Time Tests
+Abstract Test 15 |
+
+ /ats/collections/rc-op-datetime + |
+
Test Purpose |
+
+ Validate that resources can be identified and extracted from an API server using the datetime query parameter. + |
+
Requirement |
++ |
Test Method |
+
+
|
+
Abstract Test 16 |
+
+ /ats/collections/rc-datetime-definition + |
+
Test Purpose |
+
+ Validate that the dateTime query parameter is constructed correctly. + |
+
Requirement |
++ |
Test Method |
+
+
+Verify that the
+
+
+
+ |
+
Abstract Test 17 |
+
+ /ats/collections/rc-datetime-response + |
+
Test Purpose |
+
+ Validate that the |
+
Requirement |
++ |
Test Method |
+
+
+DO FOR each
+
|
+
A.3.3. Limit Tests
+Abstract Test 18 |
+
+ /ats/collections/rc-op-limit + |
+
Test Purpose |
+
+ Validate that the client can place a limit on the number of resources returned. + |
+
Requirement |
++ |
Test Method |
+
+
|
+
Abstract Test 19 |
+
+ /ats/collections/rc-limit-definition + |
+
Test Purpose |
+
+ Validate that the limit query parameter is constructed correctly. + |
+
Requirement |
++ |
Test Method |
+
+
+Verify that the
+
+
+
+ |
+
Abstract Test 20 |
+
+ /ats/collections/rc-limit-response + |
+
Test Purpose |
+
+ Validate that the limit query parameters are processed correctly. + |
+
Requirement |
++ |
Test Method |
+
+
|
+
Abstract Test 21 |
+
+ /ats/collections/rc-paged-response + |
+
Test Purpose |
+
+ Validate that the |
+
Requirement |
++ |
Test Method |
+
+
|
+
A.4. Conformance Class JSON
+Conformance Class |
+|
+ | |
Target type |
+Web API |
+
Requirements Class |
++ |
Dependency |
++ |
A.4.1. GeoJSON Definition
+Abstract Test 22 |
+
+ /ats/json/definition + |
+
Test Purpose |
+
+ Verify support for JSON + |
+
Requirement |
++ |
Test Method |
+
+
|
+
A.4.2. GeoJSON Content
+Abstract Test 23 |
+
+ /ats/json/content + |
+
Test Purpose |
+
+ Verify the content of a JSON document given an input document and schema. + |
+
Requirement |
++ |
Test Method |
+
+
|
+
A.5. Conformance Class HTML
+Conformance Class |
+|
+ | |
Target type |
+Web API |
+
Requirements Class |
++ |
Dependency |
++ |
A.5.1. HTML Definition
+Abstract Test 24 |
+
+ /ats/html/definition + |
+
Test Purpose |
+
+ Verify support for HTML + |
+
Requirement |
++ |
Test Method |
+
+ Verify that every |
+
A.5.2. HTML Content
+Abstract Test 25 |
+
+ /ats/html/content + |
+
Test Purpose |
+
+ Verify the content of an HTML document given an input document and schema. + |
+
Requirement |
++ |
Test Method |
+
+
|
+
Annex B: Examples (Informative)
+B.1. Collections Response Example
+This collections example response in JSON is for a dataset with a single "buildings" feature collection.
+There is a link to the collections response itself (link relation type: "self").
+Representations of this resource in other formats are referenced (link relation type: "alternate").
+An additional link is to a GML application schema for the collection (link relation type: "describedby").
+{ + "links": [ + { "href": "http://data.example.org/collections.json", + "rel": "self", "type": "application/json", "title": "this document" }, + { "href": "http://data.example.org/collections.html", + "rel": "alternate", "type": "text/html", "title": "this document as HTML" }, + { "href": "http://schemas.example.org/1.0/foobar.xsd", + "rel": "describedby", "type": "application/xml", "title": "XML schema for Acme Corporation data" } + ], + "collections": [ + { + "id": "buildings", + "title": "Buildings", + "description": "Buildings in the city of Bonn.", + "extent": { + "spatial": [ 7.01, 50.63, 7.22, 50.78 ], + "temporal": [ "2010-02-15T12:34:56Z", "2018-03-18T12:11:00Z" ] + }, + "links": [ + { "href": "http://example.org/concepts/building.html", + "rel": "describedby", "type": "text/html", + "title": "Feature catalogue for buildings" } + ] + } + ] +}+
B.2. Collection Object Examples
+B.2.1. Building Collection
+This Collection Description example response in JSON is for a single "buildings" collection.
+The basic descriptive information includes:
+-
+
-
+
"id": an identifier for this collection
+
+ -
+
"title": the title of this collection
+
+ -
+
"description": self evident
+
+ -
+
"attribution": markup providing attribution (owner, producer, logo, etc.) of this collection
+
+
The response includes links to:
+-
+
-
+
There is a link to the response itself (link relation type: "self").
+
+ -
+
Representations of this response in other formats are referenced using link relation type "alternate".
+
+ -
+
An additional link is to a GML application schema for the collection - using:https://www.iana.org/assignments/link-relations/link-relations.xhtml[link relation type] "describedby".
+
+
Finally, this response includes both spatial and temporal extents.
+Reference system information is not provided as the service provides geometries only in the default system (spatial: WGS 84 longitude/latitude; temporal: Gregorian calendar).
+{ + "id": "1234567890", + "title": "Example Collection Description Response", + "description": "This is an example of a Collection Description in JSON format", + "attribution": "<a href='www.ign.es' rel=' '>IGN</a> <a href='www.govdata.de/dl-de/by-2-0'>(c)</a>", + "links": [ + { "href": "http://data.example.org/collections.json", + "rel": "self", "type": "application/json", "title": "this document" }, + { "href": "http://data.example.org/collections.html", + "rel": "alternate", "type": "text/html", "title": "this document as HTML" }, + { "href": "http://schemas.example.org/1.0/foobar.xsd", + "rel": "describedby", "type": "application/xml", "title": "XML schema for Acme Corporation data" } + ], + "extent": { + "spatial": [ 7.01, 50.63, 7.22, 50.78 ], + "temporal": [ "2010-02-15T12:34:56Z", "2018-03-18T12:11:00Z" ] + } +}+
Annex C: Revision History
+Date | +Release | +Editor | +Primary clauses modified | +Description | +
---|---|---|---|---|
2019-11-25 |
+1.0.0-SNAPSHOT |
+Panagiotis (Peter) Vretanos, Clemens Portele |
+all |
+initial version |
+
2020-04-21 |
+1.0.1-SNAPSHOT |
+Chuck Heazel |
+all |
+Initial API-Common version |
+
Annex D: Glossary
+-
+
-
+
Conformance Test Module
+
+set of related tests, all within a single conformance test class (OGC 08-131r3)
+
NOTE: |
+When no ambiguity is possible, the word |
+
-
+
-
+
Conformance Test Class; Conformance Test Level
+
+set of conformance test modules that must be applied to receive a single certificate of conformance. (OGC 08-131r3)
+
NOTE: |
+When no ambiguity is possible, the word |
+
-
+
-
+
Executable Test Suite (ETS)
+
+A set of code (e.g. Java and CTL) that provides runtime tests for the assertions defined by the ATS. Test data required to do the tests are part of the ETS (OGC 08-134)
+
-
+
-
+
Recommendation
+
+expression in the content of a document conveying that among several possibilities one is recommended as particularly suitable, without mentioning or excluding others, or that a certain course of action is preferred but not necessarily required, or that (in the negative form) a certain possibility or course of action is deprecated but not prohibited (OGC 08-131r3)
+
NOTE: |
+"Although using normative language, a recommendation is not a requirement. The usual form replaces the |
+
-
+
-
+
Requirement
+
+expression in the content of a document conveying criteria to be fulfilled if compliance with the document is to be claimed and from which no deviation is permitted (OGC 08-131r3)
+
-
+
-
+
Requirements Class
+
+aggregate of all requirement modules that must all be satisfied to satisfy a conformance test class (OGC 08-131r3)
+
-
+
-
+
Requirements Module
+
+aggregate of requirements and recommendations of a specification against a single standardization target type (OGC 08-131r3)
+
-
+
-
+
Standardization Target
+
+entity to which some requirements of a standard apply (OGC 08-131r3)
+
NOTE: |
+The standardization target is the entity which may receive a certificate of conformance for a requirements class. |
+
Annex E: Bibliography
+-
+
-
+
Fielding, Roy Thomas. Architectural Styles and the Design of Network-based Software Architectures. Doctoral dissertation, University of California, Irvine, 2000.
+
+ -
+
YAML Ain’t Markup Language [online, viewed 2020-03-16]. Edited by O. Ben-Kiki, C. Evans, Ingy döt Net. Available at https://yaml.org.
+
+ -
+
Internet Assigned Numbers Authority (IANA). Link Relation Types [online, viewed 2020-03-16], Available at https://www.iana.org/assignments/link-relations/link-relations.xml.
+
+ -
+
Crocker, D., Overell, P.: IETF RFC 5234, Augmented BNF for Syntax Specifications: ABNF, https://tools.ietf.org/html/rfc5234
+
+ -
+
Open Geospatial Consortium: The Specification Model — A Standard for Modular specifications, OGC 08-131
+
+ -
+
Open Geospatial Consortium (OGC) / World Wide Web Consortium (W3C): Spatial Data on the Web Best Practices [online]. Edited by J. Tandy, L. van den Brink, P. Barnaghi. 2017 [viewed 2020-03-16]. Available at https://www.w3.org/TR/sdw-bp/.
+
+ -
+
World Wide Web Consortium (W3C): Data on the Web Best Practices [online]. Edited by B.F. Lóscio, C. Burle, N. Calegari. 2017 [viewed 2020-03-16]. Available at https://www.w3.org/TR/dwbp/.
+
+ -
+
World Wide Web Consortium (W3C): Data Catalog Vocabulary (DCAT) - Version 3 [online]. Edited by R. Albertoni, D. Browning, S. Cox, A.G. Beltran, A. Perego, P. Winstanley. W3C Editors Draft 15 June 2021. Available at https://w3c.github.io/dxwg/dcat/.
+
+ -
+
Open Geospatial Consortium (OGC): Welcome To The OGC APIs [online, viewed 2020-03-16]. Available at http://www.ogcapi.org/.
+
+ -
+
Open Geospatial Consortium (OGC): OGC Link Relations Registry, [online, viewed 2020-04-17]. Available at https://github.com/opengeospatial/NamingAuthority/blob/master/incubation/linkRelationTypes/linkrelations.csv.
+
+ -
+
Open Geospatial Consortium (OGC): Compliance Testing Program Policies & Procedures [online, viewed 2020-04-18]. Available at https://portal.ogc.org/files/?artifact_id=28982.
+
+
Annex F: Backus-Naur Forms
+F.1. BNF for URI
+The following Augmented Backus-Naur Form (ABNF) is from Appendix A of IETF RFC 3986.
+URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]+
hier-part = "//" authority path-abempty + / path-absolute + / path-rootless + / path-empty+
URI-reference = URI / relative-ref+
absolute-URI = scheme ":" hier-part [ "?" query ]+
relative-ref = relative-part [ "?" query ] [ "#" fragment ]+
relative-part = "//" authority path-abempty + / path-absolute + / path-noscheme + / path-empty+
scheme = ALPHA *( ALPHA / DIGIT / "+" / "-" / "." )+
authority = [ userinfo "@" ] host [ ":" port ] +userinfo = *( unreserved / pct-encoded / sub-delims / ":" ) +host = IP-literal / IPv4address / reg-name +port = *DIGIT+
IP-literal = "[" ( IPv6address / IPvFuture ) "]"+
IPvFuture = "v" 1*HEXDIG "." 1*( unreserved / sub-delims / ":" )+
IPv6address = 6( h16 ":" ) ls32 + / "::" 5( h16 ":" ) ls32 + / [ h16 ] "::" 4( h16 ":" ) ls32 + / [ *1( h16 ":" ) h16 ] "::" 3( h16 ":" ) ls32 + / [ *2( h16 ":" ) h16 ] "::" 2( h16 ":" ) ls32 + / [ *3( h16 ":" ) h16 ] "::" h16 ":" ls32 + / [ *4( h16 ":" ) h16 ] "::" ls32 + / [ *5( h16 ":" ) h16 ] "::" h16 + / [ *6( h16 ":" ) h16 ] "::"+
h16 = 1*4HEXDIG +ls32 = ( h16 ":" h16 ) / IPv4address +IPv4address = dec-octet "." dec-octet "." dec-octet "."+
dec-octet = DIGIT ; 0-9 + / %x31-39 DIGIT ; 10-99 + / "1" 2DIGIT ; 100-199 + / "2" %x30-34 DIGIT ; 200-249 + / "25" %x30-35 ; 250-255+
reg-name = *( unreserved / pct-encoded / sub-delims )+
path = path-abempty ; begins with "/" or is empty + / path-absolute ; begins with "/" but not "//" + / path-noscheme ; begins with a non-colon segment + / path-rootless ; begins with a segment + / path-empty ; zero characters+
path-abempty = *( "/" segment ) +path-absolute = "/" [ segment-nz *( "/" segment ) ] +path-noscheme = segment-nz-nc *( "/" segment ) +path-rootless = segment-nz *( "/" segment ) +path-empty = 0<pchar>+
segment = *pchar +segment-nz = 1*pchar +segment-nz-nc = 1*( unreserved / pct-encoded / sub-delims / "@" ) + ; non-zero-length segment without any colon ":"+
pchar = unreserved / pct-encoded / sub-delims / ":" / "@"+
query = *( pchar / "/" / "?" )+
fragment = *( pchar / "/" / "?" )+
pct-encoded = "%" HEXDIG HEXDIG+
unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~" +reserved = gen-delims / sub-delims +gen-delims = ":" / "/" / "?" / "#" / "[" / "]" / "@" +sub-delims = "!" / "$" / "&" / "'" / "(" / ")" + / "*" / "+" / "," / ";" / "="+
F.2. BNF for Date-Time
+The following Augmented Backus-Naur Form (ABNF) is from IETF RFC 3339.
+date-fullyear = 4DIGIT +date-month = 2DIGIT ; 01-12 +date-mday = 2DIGIT ; 01-28, 01-29, 01-30, 01-31 based on month/year +time-hour = 2DIGIT ; 00-23 +time-minute = 2DIGIT ; 00-59 +time-second = 2DIGIT ; 00-58, 00-59, 00-60 based on leap second rules +time-secfrac = "." 1*DIGIT +time-numoffset = ("+" / "-") time-hour ":" time-minute +time-offset = "Z" / time-numoffset +partial-time = time-hour ":" time-minute ":" time-second [time-secfrac] +full-date = date-fullyear "-" date-month "-" date-mday +full-time = partial-time time-offset +date-time = full-date "T" full-time+
Note that unlike ISO 8601, the local time zone offset is required by RFC 3339.
+Annex G: HTTP Status Codes
+Table 5 lists the main HTTP status codes that clients should be prepared to receive. This includes support for specific security schemes or URI redirection. In addition, other error situations may occur in the transport layer outside of the server.
+Status code | +Description | +
---|---|
|
+A successful request. |
+
|
+The target resource was found but resides temporarily under a different URI. A 302 response is not evidence that the operation has been successfully completed. |
+
|
+The server is redirecting the user agent to a different resource. A 303 response is not evidence that the operation has been successfully completed. |
+
|
+An entity tag was provided in the request and the resource has not changed since the previous request. |
+
|
+The target resource resides temporarily under a different URI and the user agent MUST NOT change the request method if it performs an automatic redirection to that URI. |
+
|
+Indicates that the target resource has been assigned a new permanent URI and any future references to this resource ought to use one of the enclosed URIs. |
+
|
+The server cannot or will not process the request due to an apparent client error. For example, a query parameter had an incorrect value. |
+
|
+The request requires user authentication. The response includes a |
+
|
+The server understood the request, but is refusing to fulfill it. While status code |
+
|
+The requested resource does not exist on the server. For example, a path parameter had an incorrect value. |
+
|
+The request method is not supported. For example, a POST request was submitted, but the resource only supports GET requests. |
+
|
+Content negotiation failed. For example, the |
+
|
+An internal error occurred in the server. |
+
The status codes described in Table 5 do not cover all possible conditions. See IETF RFC 7231 for a complete list of HTTP status codes.
+Annex H: OGC Web API Guidelines
+The following table discusses how this standard addresses the design principles documented in the OGC Web API Guidelines.
+# |
+Principle |
+Discussion |
+
1 |
+Don’t reinvent |
+Great care was taken in the development of this standard to only address capabilities that were not already standardized and to define how the needed capabilites integrate into a single API. |
+
2 |
+Keep it simple and intuitive |
+OGC Web APIs are developed using a building block approach. Conformance Classes are defined that encompase requirements sufficient to create a usable software module and no more. Complex APIs are constructed by assembling the applicable Conformance Classes. |
+
3 |
+Use well-known resource types |
+Except where unique to a specific Conformance Class, all resources types are IANA or OGC registered types. |
+
4 |
+Construct consistent URIs |
+OGC Web APIs are built from standardized modules using standardized patterns. This modular approach assures that the URIs are consistent across OGC Web APIs. |
+
5 |
+Use HTTP methods consistent with RFC 7231 |
+OGC web APIs are restricted to the HTTP methods defined in IETF RFC 7231. |
+
6 |
+Put selection criteria behind the ‘?’ |
+Section 6.1 of this Standard defines the conventions to be used when creating URIs for OGC Web API standards. This includes the use of the "?" to deliminate query parameters from the rest of the URI. |
+
7 |
+Error handling and use of HTTP status codes |
+This standard identifies the applicable HTTP status codes and under what conditions they should be returned. Status codes and supporting information are returned in the HTTP response using a reporting structure based on RFC 7807. |
+
8 |
+Use explicit list of HTTP status codes |
+HTTP Status Codes provides a list of the HTTP status codes that implementers of this standard should be prepared to generate and accept. This list is not exhaustive (see guideline #1). |
+
9 |
+Use of HTTP header |
+OGC API Common does not preclude use of HTTP headers where it is appropriate to do so. |
+
10 |
+Allow flexible content negotiation |
+IETF RFC 7231 content negotiation is avalable on all transactions. |
+
11 |
+Pagination |
+Of the resources defined in API-Common Core only the conformance resource is "listable". We do not anticipate the conformance resource to grow to any size, so support for pagenation would add complexity will little to no value (violating #2) |
+
12 |
+Processing resources |
+Processing resources are not addressed by this Standard. |
+
13 |
+Support metadata |
+Support for metadata is provided through metadata resource links. Examples include links with the relation type |
+
14 |
+Consider your security needs |
+While not mandated, use of HTTPS vs. HTTP is encouraged throughout this standard. |
+
15 |
+API description |
+The API definition is avaliable using the |
+
16 |
+Use well-known identifiers |
+IANA identifiers are used where they are available. Where no IANA identifiers are appropriate, OGC registered identifiers are used. |
+
17 |
+Use explicit relations |
+All relations in this standard are typed using relation types registered in the IANA or the OGC relation type registers. |
+
18 |
+Support W3C cross-origin resource sharing |
+This guideline is addressed in [cross-origin-section]. |
+
19 |
+Resource encodings |
+Conformance classes for both HTML and JSON have been defined. Implementation of both the HTML and JSON Conformance Classes is recommended. |
+
20 |
+Good APIs are testable from the beginning |
+The Abstract Test Suite (ATS) for this standard is provided in Annex A. |
+
21 |
+Specify whether operations are safe and/or idempotent |
+According to IETF RFC 7231 "the GET, HEAD, OPTIONS, and TRACE methods are defined to be safe." and the "PUT, DELETE, and safe request methods are idempotent". All request methods in this standard (GET) are both safe and idempotent. |
+
22 |
+Make resources discoverable |
+All resouces defined in this standard can be navigated to through resource links and optional standard paths. All resource links are typed using registered relation types. These links are encoded using a standard link structure that includes the media type, language, and title of the resource. |
+
23 |
+Make default behavior explicit |
+This Standard defines the proper and allowed responses for any valid or invalid request. |
+