Open Geospatial Consortium

Submission Date: <yyyy-mm-dd>

Approval Date:   <yyyy-mm-dd>

Publication Date:   2021-10-06

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.

Table of Contents

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 (API-GeoData) Standard is to provide a means of organizing these collections and to define operations for the discovery and selection of 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.

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 the discovery and selection of 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. For the purpose of conformance, the applicable API modules are identified by Conformance Classes. It is anticipated that this standard will only be implemented through reference to these Conformance Classes by other standards.

This standard identifies four conformance classes. 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 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.

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 any API-Core Conformance Classes upon which it depends.

Proof of conformance with a Conformance Class includes demonstration of conformance with all dependencies of that Conformance Class. The abstract tests in Annex A have been organized to facilitate validation of these dependencies. These tests have been organized by requirements class. A referencing standard only has to require conformance with a Conformance Class and all of the requirements and relevant tests are identified.

In addition, each requirements class is organized as one or more trees. Starting at a root test, a test script can traverse the tree to address all of the required tests, each in the appropriate context.

NOTE

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.

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 geospatial resource that may be available as one or more sub-resource distributions that conform to one or more OGC API standards. (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.

  • Feature Collection
    a set of Features from a dataset

  • 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."

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

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-GeoData are described in Table 1. Additional relation types may be used if the implementation warrants it.

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.

An ABNF representation of the RFC 3339 format is provided in Annex F.

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 API-GeoData 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 API-GeoData 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 - Part 2: Geospatial Data Standard provides a starting point for the discovery and access of geospatial resources hosted on a Web API. While typically hosted on a landing page (see API - Common - Part 1), this is not required. The Requirements Classes defined in this standard are designed to be re-usable modules. To be deployed in accordance with the requirements of the API developer.

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 API-GeoData Standard is to provide a common connection between the API and the set of Geospatial data collections that are accessible through that API. 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.

While collection is a common term, its specific meaning is often based on the context in which it is used. Since we are addressing geospatial data, we need a definition that reflects the unique characteristics of geospatial data collections. Therefore, for purposes of this standard, a collection is defined as follows:

  • Collection: A geospatial resource that may be available as one or more sub-resource distributions that conform to one or more OGC API standards.

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

IETF RFC 7231, Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content

Requirement 1

/req/collections/rc-dependency-http

A

An implementation of the /Collections Requirements Class SHALL conform to HTTP 1.1.

B

If the API supports HTTPS, then the implementation SHALL also conform to HTTP over TLS.

Recommendation 1

/rec/collections/rec-dependency-core

A

An implementation of the /Collections Requirements Class SHOULD demonstrate conformance with the Core Conformance Class defined in OGC API - Common Part 1.

Recommendation 2

/rec/collections/rec-dependency-landing-page

A

An implementation of the /Collections Requirements Class SHOULD demonstrate conformance with the Landing Page Conformance Class defined in OGC API - Common Part 1.

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 and their operations are defined in this Requirements Class. They are summarized in Table 2.

Table 2. Collection Resources
Resource URI HTTP Method Description

Collections

/collections

GET

Information which describes the set of available Collections

Collection

/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 2

/req/collections/rc-md-op

A

The API SHALL support the HTTP GET operation at the path /collections.

8.1.2. Response

Requirement 3

/req/collections/rc-md-success

A

A successful execution of the operation SHALL be reported as a response with a HTTP status code 200.

B

The content of that response SHALL be based upon the JSON schema collections.yaml.

The collections response returned by this operation is based on the collections.yaml JSON schema. Examples of collections responses are provided in Collections Response Example.

collections.yaml
type: object
required:
  - links
  - collections
properties:
  links:
    type: array
    items:
      $ref: link.yaml
  timeStamp:
    type: string
    format: date-time
  numberMatched:
    type: integer
    minimum: 0
  numberReturned:
    type: integer
    minimum: 0
  collections:
    type: array
    items:
      $ref: collectionDesc.yaml

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.

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-descriptions

A

If external schemas or descriptions exist that provide additional information about the structure or semantics for the resource, a 200-response SHOULD include links to each of those resources in the links property of the response (relation: describedby).

B

The type link parameter SHOULD be provided for each link. This applies to resources that describe the whole dataset.

The timeStamp property of the Collections response indicates when the response was generated.

Requirement 5

/req/collections/rc-timeStamp

A

If a property timeStamp is included in the response, the value SHALL be set to the time stamp when the response was generated.

The collections property of the Collections response provides a description of each individual collection hosted by the API.

Requirement 6

/req/collections/rc-md-items

A

For each spatial resource collection accessible through this API, metadata describing that collection SHALL be provided in the collections property of the Collections response.

B

The content of that metadata SHALL comply with the http://www.opengis.net/spec/ogcapi-common-2/1.0/rm/collection Requirements Module desecribed in the Collection Resource Definition section of this Standard.

The array items included in the collection property are described in the Collection Resource section of this Requirements Class.

This Requirements Class does not define any parameters for use against a collections resource. Implementors who wish to support filtering of the collections to be included in a result set should implement the Simple Query Conformance Class for that purpose.

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 can be accessed directly using the /collections/{collectionId} path and as an entry in the collections property of the /Collections resource.

8.2.1. Operation

Requirement 7

/req/collections/src-md-op

A

The API SHALL support the HTTP GET operation at the path /collections/{collectionId}.

B

The parameter collectionId is each id property in the collections response (JSONPath: $.collections[*].id).

8.2.2. Response

Requirement 8

/req/collections/src-md-success

A

A successful execution of the operation SHALL be reported as a response with a HTTP status code 200.

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 Module 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 /collections response. That is, the values for id, title, description and extent SHALL be identical.

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 Resource

Requirement 9

/req/collections/collection-definition

A

The content of a Collection resource SHALL be based upon the JSON schema collectionDesc.yaml.
Collection Resource Schema
type: object
required:
  - id
  - links
properties:
  id:
    type: string
    example: address
  title:
    type: string
    example: address
  description:
    type: string
    example: An address
  attribution:
    type: string
    title: attribution for the collection
  links:
    type: array
    items:
      $ref: link.yaml
  extent:
    $ref: extent.yaml
  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

Most 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 4

/rec/collections/rc-md-item-type

A

If the members (items) that make up a collection can be individually accessed by a client, then the itemType key SHOULD be included in the Collection resource to indicate the type of the items (e.g. feature or record).
Links

To support hypermedia navigation, the links property must be populated with sufficient hyperlinks to navigate through the whole dataset.

Additional information may be available to assist in understanding and using this dataset. Links to those resources should be provided as well.

Recommendation 5

/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 200-response SHOULD include links to each of those resources in the links property of the response (relation: describedby).

B

The type link parameter SHOULD be provided for each link.
Extent

Requirements Module

http://www.opengis.net/spec/ogcapi-common-2/1.0/rm/extent

Target type

Web Resource

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 11

/req/collections/rc-md-extent

A

For each spatial collection resource, the extent property, if provided, SHALL define boundaries that encompass the spatial and temporal properties of all of the resources in this collection. The temporal extent may use null values to indicate an open time interval.

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 6

/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 7

/rec/collections/rc-md-extent-single

A

While the spatial and temporal extents support multiple bounding boxes (bbox array) and time intervals (interval array) for advanced use cases, implementations SHOULD provide only a single bounding box or time interval unless the use of multiple values is important for the use of the dataset and agents using the API are known to be support multiple bounding boxes or time intervals.

Permission 1

/per/collections/rc-md-extent-extensions

A

API-Common only specifies requirements for spatial and temporal extents. However, the extent object MAY be extended with additional members to represent other extents, such as thermal or pressure ranges.

B

API-Common only supports

  • Spatial extents in CRS84 or CRS84h and

  • Temporal extents in the Gregorian calendar

These are the only enum values in extent.json).

C

Extensions MAY add additional reference systems to the extent object.

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

Collections Requirements Class

Dependency

RFC 3339 (Date and Time on the Internet: Timestamps)

This Requirements Class describes query parameters that can be used to discover and select resource collections exposed through an OGC Web API.

Implementors of this Requirements Class must also implement the /Collections Requirements Class.

Requirement 12

/req/simple-query/rc-dependency-collections

A

An implementation of the Simple-Query Requirements Class SHALL demonstrate conformance with the /collections Conformance Class.

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

http://www.opengis.net/spec/ogcapi-common-2/1.0/rm/bbox

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 13

/req/collections/rc-bbox-definition

A

The bbox parameter SHALL possess the following characteristics (using an OpenAPI Specification 3.0 fragment):

name: bbox
in: query
required: false
schema:
  type: array
  oneOf:
  - minItems: 4
    maxItems: 4
  - minItems: 6
    maxItems: 6
  items:
    type: number
style: form
explode: false

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):

  • Lower left corner, coordinate axis 1

  • Lower left corner, coordinate axis 2

  • Minimum value, coordinate axis 3 (optional)

  • Upper right corner, coordinate axis 1

  • Upper right corner, coordinate axis 2

  • Maximum value, coordinate axis 3 (optional)

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 bbox-crs.

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 bbox-crs.

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 14

/req/collections/rc-bbox-response

A

If the bbox parameter is provided by the client and supported by the server, then only resources that have a spatial geometry that intersects the bounding box SHALL be part of the result set.

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 bbox parameter SHALL also match all resources in the collection that are not associated with a spatial geometry.

"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).

Example 1. The bounding box of the New Zealand Exclusive Economic Zone

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

http://www.opengis.net/spec/ogcapi-common-2/1.0/rm/datetime

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 15

/req/collections/rc-datetime-definition

A

The datetime parameter SHALL have the following characteristics (using an OpenAPI Specification 3.0 fragment):

name: datetime
in: query
required: false
schema:
  type: string
style: form
explode: false

B

Temporal geometries are either a date-time value or a time interval. The parameter value SHALL conform to the following syntax (using ABNF):

interval-closed     = date-time "/" date-time
interval-open-start = [".."] "/" date-time
interval-open-end   = date-time "/" [".."]
interval            = interval-closed / interval-open-start / interval-open-end
datetime            = date-time / interval

C

The syntax of date-time is specified by RFC 3339, 5.6.

D

Open ranges in time intervals at the start or end are supported using a double-dot (..) or an empty string for the start/end..

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 16

/req/collections/rc-datetime-response

A

If the datetime parameter is provided by the client and supported by the server, then only resources that have a temporal geometry that intersects the temporal information in the datetime parameter SHALL be part of the result set.

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 datetime parameter SHALL match all resources in the collection that are not associated with a temporal geometry.

"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.
Example 2. A date-time

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.

Example 3. Intervals

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

http://www.opengis.net/spec/ogcapi-common-2/1.0/rm/limit

Target type

Web API Query Parameter

The limit parameter limits the number of resources that can be returned in a single response.

Requirement 17

/req/collections/rc-limit-definition

A

The limit parameter SHALL possess the following characteristics (using an OpenAPI Specification 3.0 fragment):

name: limit
in: query
required: false
schema:
  type: integer
  minimum: 1
  maximum: 10000
  default: 10
style: form
explode: false

Note:

The values for minimum, maximum and default are only examples and MAY be changed.

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 18

/req/collections/rc-limit-response

A

If the limit parameter is provided by the client and supported by the server, then the response SHALL not contain more resources than specified by the limit parameter.

B

If the API definition specifies a maximum value for the limit parameter, the response SHALL not contain more resources than this maximum value.

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 8

/rec/collections/rc-next-1

A

A 200-response SHOULD include a link to the next "page" (relation: next), if more resources have been selected than returned in the response.

Recommendation 9

/rec/collections/rc-next-2

A

Dereferencing a next link SHOULD return additional resources from the set of selected resources that have not yet been returned.

Recommendation 10

/rec/collections/rc-next-3

A

The number of resources in a response to a next link SHOULD follow the same rules as for the response to the original query and again include a next link, if there are more resources in the selection that have not yet been returned.

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 next link MAY include a prev link to the resource that included the next link.

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 Description 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 19

/req/collections/rc-bbox-collection-response

A

The API server SHALL process the bbox parameter against the Collection resources (/collections/{collectionId}) accessible through that API.

B

The bbox parameter SHALL be evaluated against the geometry defined by the bbox element of the extent property of the Collection resource.

Requirement 20

/req/collections/rc-datetime-collection-response

A

The API server SHALL process the datetime parameter against the Collection resources (/collections/{collectionId}) accessible through that API.

B

The datetime parameter SHALL be evaluated against the temporal geometry defined by the interval element of the extent property of the Collection resource.

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 21

/req/collections/rc-limit-collection-response

A

If the limit parameter is provided by the client, then the collections element of the collections response SHALL not contain more items than specified by the limit parameter.

B

If the API definition specifies a maximum value for the limit parameter, the collections element of the collections response SHALL not contain more items than this maximum value.

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 collections property.

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 11

/rec/collections/rc-paged-response

A

If the number of items in the collections element is less than the number available through the API, then the numberMatched and numberReurned properties SHOULD be included in the Collections response.

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 22

/req/collections/rc-numberMatched

A

If a property numberMatched is included in the response, the value SHALL be identical to the number of hosted collections that meet the selection parameters provided by the client.

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 23

/req/collections/rc-numberReturned

A

If a property numberReturned is included in the response, the value SHALL be identical to the number of items in the collections array in the Collections document.

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. Encoding Requirements Classes

10.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:

Neither of these encodings are mandatory. An implementation of the Collections requirements class may implement either, both, or neither of them.

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

http://www.opengis.net/spec/ogcapi_common-2/1.0/req/html

Target type

Web API

Dependency

HTML5

Dependency

Schema.org

Requirement 24

/req/html/definition

A

200-responses of the server SHALL support the text/html media type for the Collections and Collection resources.

Requirement 25

/req/html/content

A

Every 200-response of the API with the media type "text/html" SHALL be a HTML 5 document that includes the following information in the HTML body:

  • All information identified in the schemas of the Response Object in the HTML <body/>, and

  • All links in HTML <a/> elements in the HTML <body/>.

Recommendation 12

/rec/html/schema-org

A

A 200-response with the media type text/html, SHOULD include Schema.org annotations.

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

http://www.opengis.net/spec/ogcapi_common-2/1.0/req/json

Target type

Web API

Dependency

IETF RFC 8259: The JavaScript Object Notation (JSON) Data Interchange Format

Dependency

JSON Schema

Requirement 26

/req/json/definition

A

200-responses of the server SHALL support the application/json media type for the Collections and Collection resources.

Requirement 27

/req/json/content

A

Every 200-response with the media type application/json SHALL include, or link to, a payload encoded according to the JSON Interchange Format.

B

The schema of all responses with the media type application/json SHALL conform with the JSON Schema specified for that resource.

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.

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

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

The Conformance Classes addressed by this Abstract Test Suite are the:

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

IETF RFC 7231, Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content

The Collections Conformance Class has a dependency on the HTTP and optionally HTTPS protocols.

Abstract Test 1

/conf/collections/http

Test Purpose

Validate that all resources accessible through the /Collections Requirements Class can be accessed using the HTTP 1.1 protocol and, where approprate, TLS.

Requirement

/req/collections/rc-dependency-http

Test Method

  1. All compliance tests shall be configured to use the HTTP 1.1 protocol exclusively.

  2. For APIs which support HTTPS, all compliance tests shall be configured to use HTTP over TLS (RFC 2818) with their HTTP 1.1 protocol.

Conformance with the Collections Conformance Class is demonstrated by execution, in order, of the following tests:

  1. /conf/collections/rc-md-op

  2. /conf/collections/src-md-op

A.2.1. Collections {root}/collections Tests

Abstract Test 2

/conf/collections/rc-md-op

Test Purpose

Validate that information about the Collections can be retrieved from the expected location.

Requirement

/req/collections/rc-md-op
/req/collections/rc-md-success

Test Method

  1. Issue an HTTP GET request without query parameters to the URL {root}/collections

  2. Validate that a document was returned with a status code 200

  3. Validate the contents of the returned document using test /conf/collections/rc-md-success.

Abstract Test 3

/conf/collections_rc-md-success

Test Purpose

Validate that the Collections content complies with the required structure and contents.

Requirement

/req/collections/rc-md-success
/req/collections/rc-md-links
/req/collections/rc-timestamp
/req/collections/rc-md-items

Test Method

  1. Validate that the response document complies with /conf/collections/rc-md-links

  2. Validate that the response document complies with /conf/collections/rc-timestamp

  3. Validate that the response document complies with /conf/collections/rc-md-items

  4. Validate the Collections resource for all supported media types using the resources and tests identified in Table 3

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.

Table 3. Schema and Tests for Collections content
Format Schema Document Test ID

HTML

collections.json

/conf/html/content

JSON

collections.json

/conf/json/content

Abstract Test 5

/conf/collections/rc-timestamp

Test Purpose

If a timeStamp property is included in the Collections document, then validate that the value of that property equates to the time that the response was generated.

Requirement

/req/collections/rc-timestamp

Test Method

IF the Collections document contains a timeStamp property, THEN

  1. Get the current date and time

  2. Verify that the value of that property is within two minutes of the current date and time.

Note:

The two minute threshold was chosen to allow for test script processing time and clock synchronization issues.

Abstract Test 6

/conf/collections/rc-md-items

Test Purpose

Validate that each collection accessible through the API is described in the Collections document.

Requirement

/req/collections/rc-md-items

Test Method

  1. Verify that the Collections document includes a collections property.

  2. Verify that the collections property is an array.

  3. Verify that there is an entry in the collections property for each resource collection accessible through the API.

  4. Verify that each entry in the collections array is valid according to /conf/collections/rc-md-collection-content.

A.2.2. Collection {root}/collections/{collectionId} Tests

Abstract Test 7

/conf/collections/src-md-op

Test Purpose

Validate that the Collection content can be retrieved from the expected location.

Requirement

/req/collections/src-md-op
/conf/collections/req-md-success

Test Method

For every Collection described in the Collections content, issue an HTTP GET request to the URL /collections/{collectionId} where {collectionId} is the id property for the collection.

  1. Validate that a Collection was returned with a status code 200

  2. Validate the contents of the returned document using test /conf/collections/src-md-success.

Abstract Test 8

/conf/collections/src-md-success

Test Purpose

Validate that the Collection content complies with the required structure and contents.

Requirement

/req/collections/src-md-success

Test Method

  1. Validate the structure and content of the response document using /conf/collections/rc-md-items-collection-content

  2. Verify that the content of the response is consistent with the content for this Resource Collection in the /collections response. That is, the values for id, title, description and extent are identical.

Abstract Test 9

/conf/collections/rc-md-collection-content

Test Purpose

Validate that a Collection document complies with the required structure and values.

Requirement

/req/collections/collection-definition
/req/collections/rc-md-items-links
/req/collections/rc-md-extent

Test Method

FOR a each Collection document, validate:

  1. That the Collection document includes an id property.

  2. That the Collection document complies with /conf/collections/rc-md-items-links

  3. That any extent properties included in the Collection document comply with /conf/collections/rc-md-extent

  4. Validate the content of the Collection document for all supported media types using the resources and tests identified in Table 4

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.

Table 4. Schema and Tests for Collection content
Format Schema Document Test ID

HTML

collectionDesc.json

/conf/html/content

JSON

collectionDesc.json

/conf/json/content

Abstract Test 11

/conf/collections/rc-md-extent

Test Purpose

Validate the extent property if it is present

Requirement

/req/collections/rc-md-extent

Test Method

IF the extent property is present, THEN:

  1. Verify that the extent provides bounding boxes that include all spatial geometries in this resource.

  2. Verify that the extent provides time intervals that include all temporal geometries in this resource.

Note:

A temporal extent of null indicates an open time interval.

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

Collections Conformance Class

The Simple Query Conformance Class has a dependency on the Collections Conformance Class.

Abstract Test 12

/conf/simple-query/dependency-collections

Test Purpose

Validate that Collections Conformance Class has been implemented

Requirement

/req/simple-query/rc-dependency-collections

Test Method

Validate that the conformance test for the Collections Conformance Class has been pased.

Conformance with the Simple Query Conformance Class is demonstrated by execution of the following tests:

  1. /conf/collections/rc-op-bbox

  2. /conf/collections/rc-op-datetime

  3. /conf/collections/rc-op-limit

A.3.1. Bounding Box Tests

Abstract Test 13

/conf/collections/rc-op-bbox

Test Purpose

Validate that resources can be identified and extracted from an API server using the bbox query parameter.

Requirement

/req/collections/rc-bbox-definition
/req/collections/rc-bbox-response

Test Method

  1. Select a valid bbox value which intersects a subset of the resource collections available through the API implementation.

  2. Construct a bbox query parameter using the selected value.

  3. Validate the bbox query parameter using /conf/collections/rc-bbox-definition

  4. Issue an HTTP GET request to the URL {root}/collections. Include the validated bbox query parameter.

  5. Validate that a document was returned with a status code 200

  6. Validate the contents of the returned document using:

    1. /conf/collections_rc-md-success and

    2. /conf/collections/rc-bbox-response and

    3. /conf/collections/rc-paged-response.

Abstract Test 14

/conf/collections/rc-bbox-definition

Test Purpose

Validate that the bounding box query parameter is constructed correctly.

Requirement

/req/collections/rc-bbox-definition

Test Method

Verify that the bbox query parameter complies with the following definition (using an OpenAPI Specification 3.0 fragment):

name: bbox
in: query
required: false
schema:
  type: array
  minItems: 4
  maxItems: 6
  items:
    type: number
style: form
explode: false

Use a bounding box with four numbers in all requests where the collection has spatial geometries in 2D:

  • Lower left corner, WGS 84 longitude

  • Lower left corner, WGS 84 latitude

  • Upper right corner, WGS 84 longitude

  • Upper right corner, WGS 84 latitude

Use a bounding box with six numbers in all requests where the collection has spatial geometries in 3D:

  • Lower left corner, WGS 84 longitude

  • Lower left corner, WGS 84 latitude

  • Minimum value, WGS 84 ellipsoidal height

  • Upper right corner, WGS 84 longitude

  • Upper right corner, WGS 84 latitude

  • Maximum value, WGS 84 ellipsoidal height

Abstract Test 15

/conf/collections/rc-bbox-response

Test Purpose

Validate that the bbox query parameter is processed correctly.

Requirement

/req/collections/rc-bbox-response
/req/collections/rc-bbox-collection-response

Test Method

DO FOR each Collection in the collections element of the response:

  1. Extract the spatial geometry from the bbox element of the extent property of the Collection resource.

  2. IF there is a spatial geometry, verify that the coordinate reference system of the spatial geometry is WGS 84 longitude/latitude (http://www.opengis.net/def/crs/OGC/1.3/CRS84 or http://www.opengis.net/def/crs/OGC/0/CRS84h.

  3. IF there is a spatial geometry, verify that the spatial geometry intersects the bounding box defined by the bbox parameter.

A.3.2. Date-Time Tests

Abstract Test 16

/conf/collections/rc-op-datetime

Test Purpose

Validate that resources can be identified and extracted from an API server using the datetime query parameter.

Requirement

/req/collections/rc-datetime-definition
/req/collections/rc-datetime-response

Test Method

  1. Select a valid datetime value which intersects a subset of the resource collections available through the API implementation.

  2. Construct a datetime query parameter using the selected value.

  3. Validate the datetime query parameter using /conf/collections/rc-datetime-definition

  4. Issue an HTTP GET request to the URL {root}/collections. Include the validated datetime query parameter.

  5. Validate that a document was returned with a status code 200

  6. Validate the contents of the returned document using:

    1. /conf/collections_rc-md-success and

    2. /conf/collections/rc-datetime-response and

    3. /conf/collections/rc-paged-response.

Abstract Test 17

/conf/collections/rc-datetime-definition

Test Purpose

Validate that the dateTime query parameter is constructed correctly.

Requirement

/req/collections/rc-datetime-definition

Test Method

Verify that the datetime query parameter complies with the following definition (using an OpenAPI Specification 3.0 fragment):

name: datetime
in: query
required: false
schema:
  type: string
style: form
explode: false

Abstract Test 18

/conf/collections/rc-datetime-response

Test Purpose

Validate that the datetime query parameter is processed correctly.

Requirement

/req/collections/rc-datetime-definition
/req/collections/rc-datetime-response
/req/collections/rc-datetime-collection-response

Test Method

DO FOR each Collection in the collections element of the response:

  1. Extract the temporal geometry from the interval element of the extent property of the Collection resource.

  2. IF there is a temporal geometry, verify that the temporal geometry intersects the temporal period defined by the datetime parameter.

  3. IF there is a temporal geometry, validate that the processing of the datetime parameter complies with the syntax described in /req/collections/rc-datetime-definition (B, C, and D).

A.3.3. Limit Tests

Abstract Test 19

/conf/collections/rc-op-limit

Test Purpose

Validate that the client can place a limit on the number of resources returned.

Requirement

/req/collections/rc-limit-definition
/req/collections/rc-limit-response

Test Method

  1. Select a valid limit value which is less than the number of resource collections available through the API implementation and less than any limits advertised for the server.

  2. Construct a limit query parameter using the selected value.

  3. Validate the limit query parameter using /conf/collections/rc-limit-definition

  4. Issue an HTTP GET request to the URL {root}/collections. Include the validated limit query parameter.

  5. Validate that a document was returned with a status code 200

  6. Validate the contents of the returned document using:

    1. /conf/collections_rc-md-success and

    2. /conf/collections/rc-limit-response and

    3. /conf/collections/rc-paged-response.

Abstract Test 20

/conf/collections/rc-limit-definition

Test Purpose

Validate that the limit query parameter is constructed correctly.

Requirement

/req/collections/rc-limit-definition

Test Method

Verify that the limit query parameter complies with the following definition (using an OpenAPI Specification 3.0 fragment):

name: datetime
in: query
required: false
schema:
  type: string
style: form
explode: false

Abstract Test 21

/conf/collections/rc-limit-response

Test Purpose

Validate that the limit query parameters are processed correctly.

Requirement

/req/collections/rc-limit-response
/req/collections/rc-limit-collection-response

Test Method

  1. Count the items in the collections element of the response:

  2. Verify that this count is not greater than the value specified for the limit parameter.

  3. If the API definition specifies a maximum value for limit parameter, verify that the count does not exceed this maximum value.

Abstract Test 22

/conf/collections/rc-paged-response

Test Purpose

Validate that the numberMatched and numberReturned parameters, if present, are populated correctly..

Requirement

/req/collections/rc-numberMatched
/req/collections/rc-numberReturned

Test Method

  1. IF the numerMatched property is included in the response, THEN verify that the value of the numberMatched parameter is identical to the number of hosted resources that meet the selection parameters provided by the client.

  2. IF the numberReturned property is included in the response, THEN verify that the value of the numberReturned parameter is identical to the number of resources returned in the response.

A.4. Conformance Class JSON

Conformance Class

http://www.opengis.net/spec/ogcapi-common-2/1.0/conf/json

Target type

Web API

Requirements Class

http://www.opengis.net/spec/ogcapi_common-2/1.0/req/json

Dependency

Conformance Class "OAPI Core"

A.4.1. GeoJSON Definition

Abstract Test 23

/conf/json/definition

Test Purpose

Verify support for JSON

Requirement

/req/json/definition

Test Method

  1. A resource is requested with response media type of application/json

  2. All 200-responses SHALL support the media type application/json.

A.4.2. GeoJSON Content

Abstract Test 24

/conf/json/content

Test Purpose

Verify the content of a JSON document given an input document and schema.

Requirement

/req/json/content

Test Method

  1. Validate that the document is a JSON document.

  2. Validate the document against the schema using a JSON Schema validator.

A.5. Conformance Class HTML

Conformance Class

http://www.opengis.net/spec/ogcapi-common-2/1.0/conf/html

Target type

Web API

Requirements Class

http://www.opengis.net/spec/ogcapi_common-2/1.0/req/html

Dependency

Conformance Class "OAPI Core"

A.5.1. HTML Definition

Abstract Test 25

/conf/html/definition

Test Purpose

Verify support for HTML

Requirement

/req/html/definition

Test Method

Verify that every 200-response of every operation of the API where HTML was requested is of media type text/html

A.5.2. HTML Content

Abstract Test 26

/conf/html/content

Test Purpose

Verify the content of an HTML document given an input document and schema.

Requirement

/req/html/content

Test Method

  1. Validate that the document is an HTML 5 document

  2. Manually inspect the document against the schema.

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

2021-10-06

0.0.9

Charles Heazel

all

SWG review draft.

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 test may be omitted. i.e. conformance test module is the same as conformance module. Conformance modules may be nested in a hierarchical way.
This term and those associated to it are included here for consistency with ISO 19105.

NOTE:

When no ambiguity is possible, the word test may be left out, so conformance test class may be called a conformance class.

  • 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 shall (imperative or command) of a requirement with a should (suggestive or conditional)." (ISO Directives Part 2)

  • 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)

  • 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

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.

Table 5. Typical HTTP status codes
Status code Description

200

A successful request.

302

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.

303

The server is redirecting the user agent to a different resource. A 303 response is not evidence that the operation has been successfully completed.

304

An entity tag was provided in the request and the resource has not changed since the previous request.

307

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.

308

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.

400

The server cannot or will not process the request due to an apparent client error. For example, a query parameter had an incorrect value.

401

The request requires user authentication. The response includes a WWW-Authenticate header field containing a challenge applicable to the requested resource.

403

The server understood the request, but is refusing to fulfill it. While status code 401 indicates missing or bad authentication, status code 403 indicates that authentication is not the issue, but the client is not authorized to perform the requested operation on the resource.

404

The requested resource does not exist on the server. For example, a path parameter had an incorrect value.

405

The request method is not supported. For example, a POST request was submitted, but the resource only supports GET requests.

406

Content negotiation failed. For example, the Accept header submitted in the request did not support any of the media types supported by the server for the requested resource.

500

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

This standard doesn’t define any new concepts. It generalizes concepts defined in other standards so that they can serve as re-usable modules for almost any API standard.

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.
OGC Web API standards do not mandate an encoding. The encodings supported by an API are specified by the corresponding encoding Conformance Classes. All encodings used to-date are IANA registered media 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.
OGC Web API Common defines stylistic conventions for query parameters, query values, identifiers, and path elements used to create OGC Web API URIs.

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 ‘?’

The conventions described in OGC API - Common Part 1 are also applicable to OGC API - Common Part 2. 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

Annex G: 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.
Only standard HTTP headers are used.
Due to the common use of the HATEOAS pattern in OGC Web APIs, HTTP headers are not always accessible. The use of query parameter overrides is allowed.

10

Allow flexible content negotiation

IETF RFC 7231 content negotiation is avalable on all transactions.
Since the HTTP headers are not always accessible, content negotiation may be performed through a query parameter (see #9).

11

Pagination

Of the resources defined in API-Common Part 2, only the /collections resource has "listable" content. Paging of this content can be requested by the client if the Simple Query Requirements Class is implemented. Server implementations have the option to implement paging based on internal parameters.

12

Processing resources

Processing resources are not addressed by this Standard.

13

Support metadata

Support for metadata is provided through metadata resource links. Specifically the data-meta relationship.

14

Consider your security needs

While not mandated, use of HTTPS vs. HTTP is encouraged throughout this standard.
Authentication is not precluded by this standard, but in keeping with guideline #1, this standard does not presume to dictate what authentication methods can be used.
API-Common - Part 2 only defines GET requests. The security issues associated with CRUD are not applicable to this standard.

15

API description

The API definition is provided by API-Common Part 1. It is out of scope for this standard.
OpenAPI is the only API definition type currently supported.

16

Use well-known identifiers

IANA identifiers are used where they are available. Where no IANA identifiers are appropriate, OGC registered identifiers are used.
OGC identifiers are only used after they have been reviewed and approved by the OGC Naming Authority.

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 OGC API - Common Part 1.

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.
The ATS is defined to sufficient level of detail to validate that it is implementable and comprehensive

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.