OGC API - Features - Part 2: Coordinate Reference Systems by Reference corrigendum (original) (raw)

This document is an OGC Member approved international standard. This document is available on a royalty free, non-discriminatory basis. 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.

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. Scope
• 2. Conformance
• 3. References
• 4. Terms and Definitions
• 5. Conventions and background
• 6. Requirements Class Coordinate Reference Systems by Reference
  • 6.1. Overview
  • 6.2. Discovery
    * 6.2.1. CRS identifier list
    * 6.2.2. Storage CRS
    * 6.2.3. Global list of CRS identifiers
  • 6.3. Query
    * 6.3.1. Parameter bbox-crs
    * 6.3.2. Parameter crs
    * 6.3.3. Output format considerations
    * 6.3.4. Coordinate reference system information independent of the feature encoding
• Annex A: Abstract Test Suite (Normative)
  • A.1. Discovery
  • A.2. Query
    * A.2.1. Parameter crs
    * A.2.2. Parameter bbox-crs
• Annex B: Revision History
• Annex C: Bibliography

i. Abstract

OGC API standards define modular API building blocks to spatially enable Web APIs in a consistent way. The OpenAPI specification is used to define the API building blocks.

OGC API Features provides API building blocks to create, modify and query features on the Web. OGC API Features is comprised of multiple parts, each of them is a separate standard.

This part extends the core capabilities specified in Part 1: Core with the ability to use coordinate reference system identifiers other than the defaults defined in the core.

ii. Keywords

The following are keywords to be used by search engines and document catalogues.

OGC API, coordinate reference system identifier, CRS, feature, spatial data, openapi, crs84, wgs84, longitude, latitude

iii. Preface

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

• CubeWerx Inc.
• interactive instruments GmbH
• US Army Geospatial Center (AGC)

v. Submitters

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

6. Requirements Class Coordinate Reference Systems by Reference

6.1. Overview

The OGC API - Features - Part 1: Core standard defines support for only two coordinate reference systems:

• WGS 84 longitude, latitude
• WGS 84 longitude, latitude, ellipsoidal height

This extension defines the behavior of a server that supports additional coordinate reference systems.

Note that while the EPSG register itself is versioned, the registered items are not versioned and the "version" is always "0" in URIs of the authority "EPSG".

6.2. Discovery

6.2.1. CRS identifier list

The list has to include the default CRS — that is the CRS used unless something else is explicitly requested — is defined in OGC API - Features - Part 1: Core as:

• http://www.opengis.net/def/crs/OGC/1.3/CRS84 (for coordinates without height)
• http://www.opengis.net/def/crs/OGC/0/CRS84h (for coordinates with ellipsoidal height)

6.2.2. Storage CRS

The storage CRS for a spatial feature collection is the CRS identifier that may be used to retrieve features from that collection without the need to apply a CRS transformation.

Note that coordinates referenced to a dynamic coordinate reference system are ambiguous, if the coordinate epoch is unknown. It is therefore recommended to also provide the coordinate epoch when the storage CRS is dynamic, such as an ITRF realization or WGS 84. For more information on dynamic coordinate reference systems and coordinate epoch, please see OGC Abstract Specification Topic 2: Referencing by coordinates.

This document does not provide a mechanism to associate different coordinate epochs with feature geometries in a collection. If data with different coordinate epochs is merged in a collection, one option is to perform point motion operations (PMO) to convert all geometries to the same coordinate epoch. See OGC Abstract Specification Topic 2 for more information.

The following schema fragment extends the collection object to add the storageCrs and storageCrsCoordinateEpoch properties.

type: object
required:
  - id
  - links
properties:
  id:
    description: identifier of the collection used, for example, in URIs
    type: string
    example: address
  title:
    description: human readable title of the collection
    type: string
    example: address
  description:
    description: a description of the features in the collection
    type: string
    example: An address.
  links:
    type: array
    items:
      $ref: link.yaml
    example:
      - href: http://data.example.com/buildings
        rel: item
      - href: http://example.com/concepts/buildings.html
        rel: describedby
        type: text/html
  extent:
    $ref: extent.yaml
  itemType:
    description: indicator about the type of the items in the collection (the default value is 'feature').
    type: string
    default: feature
  crs:
    description: the list of CRS identifiers supported by the service
    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
  storageCrs:
     description: the CRS identifier, from the list of supported CRS identifiers, that may be used to retrieve features from a collection without the need to apply a CRS transformation
     type: string
     format: uri
  storageCrsCoordinateEpoch:
     description: point in time at which coordinates in the spatial feature collection are referenced to the dynamic coordinate reference system in `storageCrs`, that may be used to retrieve features from a collection without the need to apply a change of coordinate epoch. It is expressed as a decimal year in the Gregorian calendar
     type: number
     example: '2017-03-25 in the Gregorian calendar is epoch 2017.23'

6.2.3. Global list of CRS identifiers

To prevent unnecessary duplication of lists of supported CRS identifiers in the collection object, a global list of supported CRS identifiers may be provided as part of the collections object.

This global list of CRS identifiers is not automatically inherited by each collection offered by the service. Rather the global list of CRS identifiers must be explicitly referenced in the crs property of the collection object using a JSON Pointer (RFC 6901).

Note that only a local JSON Pointer within the same document is supported.

The following schema fragment extends the collections object to add the crs property which contains the global list of CRS identifiers.

allOf:
- $ref: 'http://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/schemas/collections.yaml'
- type: object
  properties:
    crs:
      description: a global list of CRS identifiers that are supported by spatial feature collections offered by the service
      type: array
      items:
        type: string
        format: uri

The following example illustrates the used of a global list of CRS identifiers.

Example 1. Collections object containing a global list of CRS identifiers

{
  "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/buildings.xsd",
      "rel": "describedby", "type": "application/xml", "title": "GML application schema for Acme Corporation building data" },
    { "href": "http://download.example.org/buildings.gpkg",
      "rel": "enclosure", "type": "application/geopackage+sqlite3", "title": "Bulk download (GeoPackage)", "length": 472546 }
  ],
  "crs": [
     "http://www.opengis.net/def/crs/OGC/1.3/CRS84",
     "http://www.opengis.net/def/crs/EPSG/0/4326",
     "http://www.opengis.net/def/crs/EPSG/0/3857",
     "http://www.opengis.net/def/crs/EPSG/0/3395"
  ],
  "collections": [
     {
       "id": "bonn_buildings",
       "title": "Bonn Buildings",
       "description": "Buildings in the city of Bonn.",
       "extent": {
         "spatial": {
           "bbox": [ [ 7.01, 50.63, 7.22, 50.78 ] ]
         },
         "temporal": {
           "interval": [ [ "2010-02-15T12:34:56Z", null ] ]
         }
       },
       "links": [
         { "href": "http://data.example.org/collections/bonn_buildings/items",
           "rel": "items", "type": "application/geo+json",
           "title": "Bonn Buildings" },
         { "href": "https://creativecommons.org/publicdomain/zero/1.0/",
           "rel": "license", "type": "text/html",
           "title": "CC0-1.0" },
         { "href": "https://creativecommons.org/publicdomain/zero/1.0/rdf",
           "rel": "license", "type": "application/rdf+xml",
           "title": "CC0-1.0" }
       ],
       "crs": [
          "#/crs",
          "http://www.opengis.net/def/crs/EPSG/0/4258",
          "http://www.opengis.net/def/crs/EPSG/0/25831",
          "http://www.opengis.net/def/crs/EPSG/0/25832"
       ]
     },
     {
       "id": "tor_buildings",
       "title": "Toronto Buildings",
       "description": "Buildings in the city of Toronto.",
       "extent": {
         "spatial": {
           "bbox": [ [ -79.62, 43.58, -79.12, 43.87 ] ]
         },
         "temporal": {
           "interval": [ [ "2010-02-15T12:34:56Z", null ] ]
         }
       },
       "links": [
         { "href": "http://data.example.org/collections/tor_buildings/items",
           "rel": "items", "type": "application/geo+json",
           "title": "Toronto Buildings" },
         { "href": "https://creativecommons.org/publicdomain/zero/1.0/",
           "rel": "license", "type": "text/html",
           "title": "CC0-1.0" },
         { "href": "https://creativecommons.org/publicdomain/zero/1.0/rdf",
           "rel": "license", "type": "application/rdf+xml",
           "title": "CC0-1.0" }
       ],
       "crs": [
          "#/crs"
       ]
     },
     {
       "id": "dc_buildings",
       "title": "Washington DC Buildings",
       "description": "Buildings in the city of Washington DC.",
       "extent": {
         "spatial": {
           "bbox": [ [ -77.12, 38.80, -76.89, 39.01 ] ]
         },
         "temporal": {
           "interval": [ [ "2010-02-15T12:34:56Z", null ] ]
         }
       },
       "links": [
         { "href": "http://data.example.org/collections/dc_buildings/items",
           "rel": "items", "type": "application/geo+json",
           "title": "DC Buildings" },
         { "href": "https://creativecommons.org/publicdomain/zero/1.0/",
           "rel": "license", "type": "text/html",
           "title": "CC0-1.0" },
         { "href": "https://creativecommons.org/publicdomain/zero/1.0/rdf",
           "rel": "license", "type": "application/rdf+xml",
           "title": "CC0-1.0" }
         ],
         "crs": [
           "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
       ]
     }
  ]
}

In the above example, the bonn_buildings collection is offered in all the CRSs specified in the global list plus three other CRSs.

The tor_buildings collection is offered in the CRSs specified in the global list.

The dc_buildings collection is only offered in the default CRS (i.e., WGS 84 longitude, latitude).

6.3. Query

6.3.1. Parameter bbox-crs

The bbox-crs parameter may be used to assert the CRS used for the coordinate values of the bbox parameter.

As usual, it is good practice to include a message about the reason for the error in the response.

The following fragment illustrates the use of the bbox-crs parameter (reserved characters have to be encoded):

Example 2. Specifying a bounding box in one of the supported coordinate reference systems

   ...&bbox=32507317%2C5224265%2C33427450%2C5603836&bbox-crs=http%3A%2F%2Fwww.opengis.net%2Fdef%2Fcrs%2FEPSG%2F0%2F25832

6.3.2. Parameter crs

As usual, it is good practice to include a message about the reason for the error in the response.

For example, OGC KML only supports the default CRS (WGS84 longitude and latitude, optionally with ellipsoidal height).

The following fragment illustrates the use of the crs parameter:

Example 3. Retrieving features from a collection in one of the supported CRSs

.../collections/buildings/items?crs=http%3A%2F%2Fwww.opengis.net%2Fdef%2Fcrs%2FEPSG%2F0%2F26703&...

6.3.3. Output format considerations

OGC API - Features - Part 1: Core defines three conformance classes related to the output formats:

• GML/XML
• GeoJSON/JSON
• HTML

6.3.3.1. Collections and Collection resources

This document specifies extensions to the Collections resource (the global list of coordinate reference systems) and the Collection resource (the storage CRS including the associated coordinate epoch).

How these extensions are reflected in each encoding is not fully specified by this standard, except for JSON-based or YAML-based encodings where the extensions are fully specified by the OpenAPI schema components.

For XML, the content model of the of the complex types core:CollectionsType and core:CollectionType would have to be extended with additional information. This document does not specify the details for such extensions due to a lack of demand.

6.3.3.2. Features and Feature resources

GML has full CRS support and no further conventions are imposed by this standard.

HTML does not have any provisions for spatial geometries and coordinate reference systems. However, note that schema.org that is embedded in HTML only supports WGS 84 in the axis order latitude/longitude, so any coordinates in schema.org markup will have to be in that coordinate reference system, independent of the requested coordinate reference system.

GeoJSON normatively supports WGS 84 (without height: CRS84; with ellipsoidal height: CRS84h), but the "prior arrangement" provision allows other coordinate systems to be used.

An explicit request by a client with a query parameter crs establishes a prior arrangement. It is the responsibility of the client that submits the request to handle the coordinates in the response correctly. In particular, clients should not make the GeoJSON document available to others unless they are aware of the prior arrangement.

This standard does not specify any standardized approach to encoding coordinate reference system information in a GeoJSON document.

The first paragraph of section 4 in GeoJSON also states:

An OPTIONAL third-position element SHALL be the height in meters above or below the WGS 84 reference ellipsoid. In the absence of elevation values, applications sensitive to height or depth SHOULD interpret positions as being at local ground or sea level.

If the requested coordinate reference system includes the vertical axis, the third-position element has to be interpreted according to that coordinate reference system, not as if it would be relative to the WGS 84 reference ellipsoid.

6.3.4. Coordinate reference system information independent of the feature encoding

Because of the inconsistent provision of CRS metadata in geospatial encodings and the continued confusion caused by the axis order of coordinates, this standard defines a mechanism for a server to clearly and unambiguously assert the CRS being used in a response document independent of the requested output format.

The following example illustrates the Content-Crs header in a response.

Example 4. HTTP header declaring the CRS used in the body of the response

   $ curl -i "https://example.com/api/v1/collections/poi/items/1?crs=http%3A%2F%2Fwww.opengis.net%2Fdef%2Fcrs%2FEPSG%2F0%2F3395"

   HTTP/1.1 200 OK
   Date: Sun, 24 May 2020 15:30:56 GMT
   Content-Type: application/geo+json
   Content-Language: en
   Content-Crs: <http://www.opengis.net/def/crs/EPSG/0/3395>
   Link: <https://example.com/api/v1/collections/poi/items/1?crs=http%3A%2F%2Fwww.opengis.net%2Fdef%2Fcrs%2FEPSG%2F0%2F3395&f=json>; rel="self"; title="This document"; type="application/geo+json"
   Link: <https://example.com/api/v1/collections/poi/items/1?crs=http%3A%2F%2Fwww.opengis.net%2Fdef%2Fcrs%2FEPSG%2F0%2F3395&f=html>; rel="alternate"; title="This document as HTML"; type="text/html"
   Link: <https://example.com/api/v1/collections/poi>; rel="collection"; title="The collection the feature belongs to"
   Vary: Accept-Language,Accept-Encoding
   Content-Length: 1064

   ...