5.1.  Identifiers

The normative provisions in this standard are denoted by the URI http://www.opengis.net/spec/ogcapi-features-1/1.0.

All requirements and conformance tests that appear in this document are denoted by partial URIs which are relative to this base.

5.2.  Link relations

To express relationships between resources, RFC 8288 (Web Linking) is used.

The following registered link relation types are used in this document.

• alternate: Refers to a substitute for this context.

• collection: The target IRI points to a resource which represents the collection resource for the context IRI.

• describedBy: Refers to a resource providing information about the link’s context.

• item: The target IRI points to a resource that is a member of the collection represented by the context IRI.

• next: Indicates that the link’s context is a part of a series, and that the next in the series is the link target.

• license: Refers to a license associated with this context.

• prev: Indicates that the link’s context is a part of a series, and that the previous in the series is the link target.

  • This relation is only used in examples.

• self: Conveys an identifier for the link’s context.

• service-desc: Identifies service description for the context that is primarily intended for consumption by machines.

  • API definitions are considered service descriptions.

• service-doc: Identifies service documentation for the context that is primarily intended for human consumption.

In addition the following link relation types are used for which no applicable registered link relation type could be identified.

• items: Refers to a resource that is comprised of members of the collection represented by the link’s context.

• conformance: Refers to a resource that identifies the specifications that the link’s context conforms to.

• data: Indicates that the link’s context is a distribution of a dataset that is an API and refers to the root resource of the dataset in the API.

Each resource representation includes an array of links. Implementations are free to add additional links for all resources provided by the API. For example, an enclosure link could reference a bulk download of a collection. Or a related link on a feature could reference a related feature.

5.3.  Use of HTTPS

For simplicity, this document in general only refers to the HTTP protocol. This is not meant to exclude the use of HTTPS and simply is a shorthand notation for “HTTP or HTTPS.” In fact, most servers are expected to use HTTPS, not HTTP.

5.4.  HTTP URIs

This document does not restrict the lexical space of URIs used in the API beyond the requirements of the HTTP and URI Syntax IETF RFCs. If URIs include reserved characters that are delimiters in the URI subcomponent, these have to be percent-encoded. See Clause 2 of RFC 3986 for details.

5.5.  API definition

servers:
  - url: https://dev.example.org/
    description: Development server
  - url: https://data.example.org/
    description: Production server

6.1.  Design considerations

While this is the first version of the OGC API Features series, the fine-grained access to features over the Web has been supported by the OGC Web Feature Service (WFS) standard (in ISO: ISO 19142) and many implementations of that standard for many years. WFS uses a Remote-Procedure-Call-over-HTTP architectural style using XML for any payloads. When the WFS standard was originally designed in the late 1990s and early 2000s this was the state-of-the-art.

OGC API Features supports similar capabilities, but using a modernized approach that follows the current Web architecture and in particular the W3C/OGC best practices for sharing Spatial Data on the Web as well as the W3C best practices for sharing Data on the Web.

Beside the general alignment with the architecture of the Web (e.g., consistency with HTTP/HTTPS, hypermedia controls), another goal for OGC API Features is modularization. This goal has several facets, as described below.

• Clear separation between core requirements and more advanced capabilities. This document specifies the core requirements that are relevant for almost everyone who wants to share or use feature data on a fine-grained level. Additional capabilities that several communities are using today will be specified as extensions in additional parts of the OGC API Features series.

• Technologies that change more frequently are decoupled and specified in separate modules (“requirements classes” in OGC terminology). This enables, for example, the use/re-use of new encodings for spatial data or API descriptions.

• Modularization is not just about features are resources, but about providing building blocks for fine-grained access to spatial data that can be used in Web APIs in general. In other words, a server supporting OGC API Features is not intended to implement just a standalone Features API. A corollary of this is that the same Web API may also implement other standards of the OGC API family that support additional resource types; for example, tile resources could provide access to the same features, but organized in a spatial partitioning system; or map resources could process the features and render them as as map images.

Implementations of OGC API Features are intended to support two different approaches how clients can use the API.

In the first approach, clients are implemented with knowledge about this standard and its resource types. The clients navigate the resources based on this knowledge and based on the responses provided by the API. The API definition may be used to determine details, e.g., on filter parameters, but this may not be necessary depending on the needs of the client. These are clients that are in general able to use multiple APIs as long as they implement OGC API Features.

The other approach targets developers that are not familiar with the OGC API standards, but want to interact with spatial data provided by an API that happens to implement OGC API Features. In this case the developer will study and use the API definition — typically an OpenAPI document — to understand the API and implement the code to interact with the API. This assumes familiarity with the API definition language and the related tooling, but it should not be necessary to study the OGC API standards.

6.2.  Encodings

This standard does not mandate any encoding or format for representing features or feature collections. In addition to HTML as the standard encoding for Web content, rules for commonly used encodings for spatial data on the web are provided (GeoJSON, GML).

None of these encodings is mandatory and an implementation of the Core requirements class may implement none of them but implement another encoding instead.

Support for HTML is recommended as HTML is the core language of the World Wide Web. A server that supports HTML will support browsing the data with a web browser and will enable search engines to crawl and index the dataset.

GeoJSON is a commonly used format that is simple to understand and well supported by tools and software libraries. Since most Web developers are comfortable with using a JSON-based format, this version of OGC API Features recommends supporting GeoJSON for encoding feature data, if the feature data can be represented in GeoJSON for the intended use.

Some examples for cases that are out-of-scope of GeoJSON are:

• When solids are used for geometries (e.g., in a 3D city model),

• Geometries that include non-linear curve interpolations that cannot be simplified (e.g., use of arcs in authoritative geometries),

• Geometries that have to be represented in a coordinate reference system that is not based on WGS 84 longitude/latitude (e.g., an authoritative national reference system), or

• Features that have more than one geometric property.

In addition to HTML and GeoJSON, a significant volume of feature data is available in XML-based formats, notably GML. GML supports more complex requirements than GeoJSON and does not have any of the limitations mentioned in the above bullets, but as a result GML is more complex to handle for both servers and clients. Conformance classes for GML are, therefore, included in this standard. It is expected that these conformance classes will typically be supported by servers where users are known to expect feature data in XML/GML.

The recommendations for using HTML and GeoJSON reflect the importance of HTML and the current popularity of JSON-based data formats. As the practices in the Web community evolve, the recommendations will likely be updated in future versions of this standard to provide guidance on using other encodings.

This part of the OGC API Features standards does not provide any guidance on other encodings. The supported encodings, or more precisely the media types of the supported encodings, can be determined from the API definition. The desired encoding is selected using HTTP content negotiation.

For example, if the server supports GeoJSON Text Sequences, an encoding that is based on JSON text sequences and GeoJSON to support streaming by making the data incrementally parseable, the media type application/geo+json-seq would be used.

In addition, HTTP supports compression and therefore the standard HTTP mechanisms can be used to reduce the size of the messages between the server and the client.

6.3.  Examples

This document uses a simple example throughout the document: The dataset contains buildings and the server provides access to them through a single feature collection (“buildings”) and two encodings, GeoJSON and HTML.

The buildings have a few (optional) properties: the polygon geometry of the building footprint, a name, the function of the building (residential, commercial or public use), the floor count and the timestamp of the last update of the building feature in the dataset.

In addition to the examples included in the document, additional and more comprehensive examples are available at http://schemas.opengis.net/ogcapi/features/part1/1.0/examples.

7.1.  Overview

A server that implements this conformance class provides access to the features in a dataset. In other words, the API is a distribution of that dataset. A file download, for example, would be another distribution.

The entry point is a Landing page (path /).

The Landing page provides links to:

• the API definition (link relations service-desc and service-doc),

• the Conformance declaration (path /conformance, link relation conformance), and

• the Collections (path /collections, link relation data).

The API definition describes the capabilities of the server that can be used by clients to connect to the server or by development tools to support the implementation of servers and clients. Accessing the API definition using HTTP GET returns a description of the API. The API definition can be hosted on the API server(s) or a separate server.

The Conformance declaration states the conformance classes from standards or community specifications, identified by a URI, that the API conforms to. Clients can but are not required to use this information. Accessing the Conformance declaration using HTTP GET returns the list of URIs of conformance classes implemented by the server.

The data is organized into one or more collections. Collections provides information about and access to the collections.

This document specifies requirements only for collections consisting of features. That is, each collection considered by this document is a feature collection. Other OGC API standards may add requirements for other types of collections.

This standard does not include any requirements about how the features in the dataset have to be aggregated into collections. A typical approach is to aggregate by feature type but any other approach that fits the dataset or the applications using this distribution may also be used.

Accessing Collections using HTTP GET returns a response that contains at least the list of collections. For each Collection, a link to the items in the collection (Features, path /collections/{collectionId}/items, link relation items) as well as key information about the collection. This information includes:

• A local identifier for the collection that is unique for the dataset;

• A list of coordinate reference systems (CRS) in which geometries may be returned by the server: the first CRS is the default coordinate reference system (in the Core, the default is always WGS 84 with axis order longitude/latitude);

• An optional title and description for the collection;

• An optional extent that can be used to provide an indication of the spatial and temporal extent of the collection — typically derived from the data;

• An optional indicator about the type of the items in the collection (the default value, if the indicator is not provided, is ‘feature’).

The Collection resource is available at path /collections/{collectionId}, too, often with more details than included in the Collections response.

Each Collection that is a feature collection consists of features. This document only discusses the behavior of feature collections.

Each feature in a dataset is part of exactly one collection.

Accessing the Features using HTTP GET returns a document consisting of features in the collection. The features included in the response are determined by the server based on the query parameters of the request. To support access to larger collections without overloading the client, the API supports paged access with links to the next page, if more features are selected than the page size.

A bbox or datetime parameter may be used to select only a subset of the features in the collection (the features that are in the bounding box or time interval). The bbox parameter matches all features in the collection that are not associated with a location, too. The datetime parameter matches all features in the collection that are not associated with a time stamp or interval, too.

The limit parameter may be used to control the subset of the selected features that should be returned in the response, the page size.

Each page may include information about the number of selected and returned features (numberMatched and numberReturned) as well as links to support paging (link relation next).

Each Feature (path /collections/{collectionId}/items/{featureId}) is also a separate resource and may be requested individually using HTTP GET.

In addition to the simple path structures described above, where all features are organized in a one-level collection hierarchy, additional parts of the OGC API Feature series are expected to provide alternate access to the features served by the API via additional, deeper collection hierarchies.

7.2.  API landing page

type: object
required:
  - links
properties:
  title:
    type: string
  description:
    type: string
  links:
    type: array
    items:
      $ref: http://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/schemas/link.yaml

{
  "title": "Buildings in Bonn",
  "description": "Access to data about buildings in the city of Bonn via a Web API that conforms to the OGC API Features specification.",
  "links": [
    { "href": "http://data.example.org/",
      "rel": "self", "type": "application/json", "title": "this document" },
    { "href": "http://data.example.org/api",
      "rel": "service-desc", "type": "application/vnd.oai.openapi+json;version=3.0", "title": "the API definition" },
    { "href": "http://data.example.org/api.html",
      "rel": "service-doc", "type": "text/html", "title": "the API documentation" },
    { "href": "http://data.example.org/conformance",
      "rel": "conformance", "type": "application/json", "title": "OGC API conformance classes implemented by this server" },
    { "href": "http://data.example.org/collections",
      "rel": "data", "type": "application/json", "title": "Information about the feature collections" }
  ]
}

7.3.  API definition

7.4.  Declaration of conformance classes

type: object
required:
  - conformsTo
properties:
  conformsTo:
    type: array
    items:
      type: string

{
  "conformsTo": [
    "http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/core",
    "http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/oas30",
    "http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/html",
    "http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/geojson"
  ]
}

7.5.  HTTP 1.1

This includes the correct use of status codes, headers, etc.

Supporting the method HEAD in addition to GET can be useful for clients and is simple to implement.

Servers implementing CORS will implement the method OPTIONS, too.

7.6.  Unknown or invalid query parameters

If a server wants to support vendor specific parameters, these have to be explicitly declared in the API definition.

If OpenAPI is used to represent the API definition, a capability exists to allow additional parameters without explicitly declaring them. That is, parameters that have not been explicitly specified in the API definition for the operation will be ignored.

in: query
name: vendorSpecificParameters
schema:
  type: object
  additionalProperties: true
style: form

OpenAPI schema for additional “free-form” query parameters

Note that the name of the parameter does not matter as the actual query parameters are the names of the object properties. For example, assume that the value of vendorSpecificParameters is this object:

{
  “my_first_parameter”: “some value”,
  “my_other_parameter”: 42
}

In the request URI this would be expressed as &my_first_parameter=some%20value&my_other_parameter=42.

This is a general rule that applies to all parameters, whether they are specified in this document or in additional parts. A value is invalid if it violates the API definition or any other constraint for that parameter stated in a requirement.

7.7.  Web caching

Entity tags are a mechanism for web cache validation and for supporting conditional requests to reduce network traffic. Entity tags are specified by HTTP/1.1 (RFC 2616).

7.8.  Support for cross-origin requests

Access to data from a HTML page is by default prohibited for security reasons, if the data is located on another host than the webpage (“same-origin policy”). A typical example is a web-application accessing feature data from multiple distributed datasets.

Two common mechanisms to support cross-origin requests are:

• Cross-origin resource sharing (CORS); and

• JSONP (JSON with padding).

7.9.  Encodings

While OGC API Features does not specify any mandatory encoding, support for the following encodings is recommended. See Clause 6 (Overview) for a discussion.

Requirement /req/core/http implies that the encoding of a server response is determined using content negotiation as specified by the HTTP RFC.

The section Media Types includes guidance on media types for encodings that are specified in this document.

Note that any server that supports multiple encodings will have to support a mechanism to mint encoding-specific URIs for resources in order to express links, for example, to alternate representations of the same resource. This document does not mandate any particular approach how this is supported by the server.

As clients simply need to dereference the URI of the link, the implementation details and the mechanism how the encoding is included in the URI of the link are not important. Developers interested in the approach of a particular implementation, for example, to manipulate (“hack”) URIs in the browser address bar, can study the API definition.

7.10.  String internationalization

If the server supports representing resources in multiple languages, the usual HTTP content negotiation mechanisms apply. The client states its language preferences in the Accept-Language header of a request and the server responds with responses that have linguistic text in the language that best matches the requested languages and the capabilities of the server.

For example, if JSON-LD is used as an encoding, the built-in capabilities to annotate a string with its language should be used.

The link object based on RFC 8288 (Web Linking) includes a hreflang attribute that can be used to state the language of the referenced resource. This can be used to include links to the same data in, for example, English or French. Just like with multiple encodings a server that wants to use language-specific links will have to support a mechanism to mint language-specific URIs for resources in order to express links to, for example, the same resource in another language. Again, this document does not mandate any particular approach how such a capability is supported by the server.

7.11.  Coordinate reference systems

As discussed in Chapter 9 of the W3C/OGC Spatial Data on the Web Best Practices document, how to express and share the location of features in a consistent way is one of the most fundamental aspects of publishing geographic data and it is important to be clear about the coordinate reference system that coordinates are in.

For the reasons discussed in the Best Practices, OGC API Features uses WGS 84 longitude and latitude as the default coordinate reference system.

Implementations compliant with the Core are not required to support publishing feature geometries in coordinate reference systems other than http://www.opengis.net/def/crs/OGC/1.3/CRS84 (for coordinates without height) or http://www.opengis.net/def/crs/OGC/0/CRS84h (for coordinates with height); i.e., the (optional) third coordinate number is always the height.

The Core also does not specify a capability to request feature geometries in a different coordinate reference system. Such a capability will be specified in another part of the OGC API Features series.

7.12.  Link headers

7.13.  Feature collections

type: object
required:
  — links
  — collections
properties:
  links:
    type: array
    items:
      $ref: http://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/schemas/link.yaml
  collections:
    type: array
    items:
      $ref: http://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/schemas/collection.yaml

type: object
required:
  — id
  — links
properties:
  id:
    description: identifier of the collection used, for example, in URIs
    type: string
  title:
    description: human readable title of the collection
    type: string
  description:
    description: a description of the features in the collection
    type: string
  links:
    type: array
    items:
      $ref: http://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/schemas/link.yaml
  extent:
    description: >-
      The extent of the features in the collection. In the Core only spatial and temporal
      extents are specified. Extensions may add additional members to represent other
      extents, for example, thermal or pressure ranges.
    type: object
    properties:
      spatial:
        description: >-
          The spatial extent of the features in the collection.
        type: object
        properties:
          bbox:
            description: >-
              One or more bounding boxes that describe the spatial extent of the dataset.
              In the Core only a single bounding box is supported. Extensions may support
              additional areas. If multiple areas are provided, the union of the bounding
              boxes describes the spatial extent.
            type: array
            minItems: 1
            items:
              description: >-
                Each bounding box is 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)

                The coordinate reference system of the values is WGS 84 longitude/latitude
                (http://www.opengis.net/def/crs/OGC/1.3/CRS84) unless a different coordinate
                reference system is specified in `crs`.

                For WGS 84 longitude/latitude the values are in most cases the sequence of
                minimum longitude, minimum latitude, maximum longitude and maximum latitude.
                However, in cases where the box spans the antimeridian the first value
                (west-most box edge) is larger than the third value (east-most box edge).

                If the vertical axis is included, the third and the sixth number are
                the bottom and the top of the 3-dimensional bounding box.

                If a feature 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.
              type: array
              minItems: 4
              maxItems: 6
              items:
                type: number
              example:
                — -180
                — -90
                — 180
                — 90
          crs:
            description: >-
              Coordinate reference system of the coordinates in the spatial extent
              (property `bbox`). The default reference system is WGS 84 longitude/latitude.
              In the Core this is the only supported coordinate reference system.
              Extensions may support additional coordinate reference systems and add
              additional enum values.
            type: string
            enum:
              — ’http://www.opengis.net/def/crs/OGC/1.3/CRS84’
            default: ‘http://www.opengis.net/def/crs/OGC/1.3/CRS84’
      temporal:
        description: >-
          The temporal extent of the features in the collection.
        type: object
        properties:
          interval:
            description: >-
              One or more time intervals that describe the temporal extent of the dataset.
              The value `null` is supported and indicates an open time intervall.
              In the Core only a single time interval is supported. Extensions may support
              multiple intervals. If multiple intervals are provided, the union of the
              intervals describes the temporal extent.
            type: array
            minItems: 1
            items:
              description: >-
                Begin and end times of the time interval. The timestamps
                are in the coordinate reference system specified in `trs`. By default
                this is the Gregorian calendar.
              type: array
              minItems: 2
              maxItems: 2
              items:
                type: string
                format: date-time
                nullable: true
              example:
                — ’2011-11-11T12:22:11Z’
                — null
          trs:
            description: >-
              Coordinate reference system of the coordinates in the temporal extent
              (property `interval`). The default reference system is the Gregorian calendar.
              In the Core this is the only supported temporal reference system.
              Extensions may support additional temporal reference systems and add
              additional enum values.
            type: string
            enum:
              — ’http://www.opengis.net/def/uom/ISO-8601/0/Gregorian’
            default: ‘http://www.opengis.net/def/uom/ISO-8601/0/Gregorian’
  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 coordinate reference systems supported by the service
    type: array
    items:
      type: string
    default:
      — http://www.opengis.net/def/crs/OGC/1.3/CRS84

{
  "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 }
  ],
  "collections": [
    {
      "id": "buildings",
      "title": "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/buildings/items",
          "rel": "items", "type": "application/geo+json",
          "title": "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" }
      ]
    }
  ]
}

7.14.  Feature collection

7.15.  Features

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

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

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

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

in: query
required: false
style: form
explode: false

name: function
in: query
description: >-
  Only return buildings of a particular function.\

  Default = return all buildings.
required: false
schema:
  type: string
  enum:
    - residential
    - commercial
    - public use
style: form
explode: false
example: 'function=public+use'

name: name
in: query
description: >-
  Only return buildings with a particular name. Use '*' as a wildcard.\

  Default = return all buildings.
required: false
schema:
  type: string
style: form
explode: false
example: 'name=A*'

Link: <http://data.example.org/collections/buildings/items.json>; rel=”self”; type=”application/geo+json”
Link: <http://data.example.org/collections/buildings/items.html>; rel=”alternate”; type=”text/html”
Link: <http://data.example.org/collections/buildings/items.json?offset=10>; rel=”next”; type=”application/geo+json”

Link: <http://data.example.org/collections/buildings/items.json?offset=10>; rel=”self”; type=”application/geo+json”
Link: <http://data.example.org/collections/buildings/items.html?offset=10>; rel=”alternate”; type=”text/html”
Link: <http://data.example.org/collections/buildings/items.json?offset=0>; rel=”prev”; type=”application/geo+json”
Link: <http://data.example.org/collections/buildings/items.json?offset=20>; rel=”next”; type=”application/geo+json”

Link: <http://data.example.org/collections/buildings/items.json?limit=50>; rel=”self”; type=”application/geo+json”
Link: <http://data.example.org/collections/buildings/items.html?limit=50>; rel=”alternate”; type=”text/html”
Link: <http://data.example.org/collections/buildings/items.json?limit=50&offset=50>; rel=”next”; type=”application/geo+json”

Link: <http://data.example.org/collections/buildings/items.json?limit=50&offset=50>; rel=”self”; type=”application/geo+json”
Link: <http://data.example.org/collections/buildings/items.html?limit=50&offset=50>; rel=”alternate”; type=”text/html”
Link: <http://data.example.org/collections/buildings/items.json?limit=50&offset=0>; rel=”prev”; type=”application/geo+json”
Link: <http://data.example.org/collections/buildings/items.json?limit=50&offset=100>; rel=”next”; type=”application/geo+json”

7.16.  Feature

Link: <http://data.example.org/collections/buildings/items/123.json>; rel="self"; type="application/geo+json"
Link: <http://data.example.org/collections/buildings/items/123.html>; rel="alternate"; type="text/html"
Link: <http://data.example.org/collections/buildings.json>; rel="collection"; type="application/json"
Link: <http://data.example.org/collections/buildings.html>; rel="collection"; type="text/html"

8.1.  Overview

This clause specifies four pre-defined requirements classes for encodings to be used by a OGC API Features implementation. These encodings are commonly used encodings for spatial data on the web:

• HTML

• GeoJSON

• Geography Markup Language (GML), Simple Features Profile, Level 0

• Geography Markup Language (GML), Simple Features Profile, Level 2

None of these encodings are mandatory and an implementation of the Core requirements class may also implement none of them but implement another encoding instead.

The Core requirements class includes recommendations to support HTML and GeoJSON as encodings, where practical. Clause 6 (Overview) includes a discussion about recommended encodings.

8.2.  Requirements 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 Best Practice 2: Make your spatial data indexable by search engines [SDWBP]. This standard therefore recommends supporting HTML as an encoding.

8.3.  Requirements Class “GeoJSON”

GeoJSON is a commonly used format that is simple to understand and well supported by tools and software libraries. Since most Web developers are comfortable with using a JSON-based format supporting GeoJSON is recommended, if the feature data can be represented in GeoJSON for the intended use.

Templates for the definition of the schemas for the GeoJSON responses in OpenAPI definitions are available at featureCollectionGeoJSON.yaml and featureGeoJSON.yaml. These are generic schemas that do not include any application schema information about specific feature types or their properties.

A GeoJSON FeatureCollection Object response

{
  "type" : "FeatureCollection",
  "links" : [ {
    "href" : "http://data.example.com/collections/buildings/items?f=json",
    "rel" : "self",
    "type" : "application/geo+json",
    "title" : "this document"
  }, {
    "href" : "http://data.example.com/collections/buildings/items?f=html",
    "rel" : "alternate",
    "type" : "text/html",
    "title" : "this document as HTML"
  }, {
    "href" : "http://data.example.com/collections/buildings/items?f=json&offset=10&limit=10",
    "rel" : "next",
    "type" : "application/geo+json",
    "title" : "next page"
  } ],
  "timeStamp" : "2018-04-03T14:52:23Z",
  "numberMatched" : 123,
  "numberReturned" : 10,
  "features" : [ {
    "type" : "Feature",
    "id" : "123",
    "geometry" : {
      "type" : "Polygon",
      "coordinates" : [ ... ]
    },
    "properties" : {
      "function" : "residential",
      "floors" : "2",
      "lastUpdate" : "2015-08-01T12:34:56Z"
    }
  }, { ...
  }, {
    "type" : "Feature",
    "id" : "132",
    "geometry" : {
      "type" : "Polygon",
      "coordinates" : [ ... ]
    },
    "properties" : {
      "function" : "public use",
      "floors" : "10",
      "lastUpdate" : "2013-12-03T10:15:37Z"
    }
  } ]
}

A GeoJSON Feature Object response

{
  "type" : "Feature",
  "links" : [ {
    "href" : "http://data.example.com/collections/buildings/items/123?f=json",
    "rel" : "self",
    "type" : "application/geo+json",
    "title" : "this document"
  }, {
    "href" : "http://data.example.com/collections/buildings/items/123?f=html",
    "rel" : "alternate",
    "type" : "text/html",
    "title" : "this document as HTML"
  }, {
    "href" : "http://data.example.com/collections/buildings",
    "rel" : "collection",
    "type" : "application/json",
    "title" : "the collection document"
  } ],
  "id" : "123",
  "geometry" : {
    "type" : "Polygon",
    "coordinates" : [ ... ]
  },
  "properties" : {
    "function" : "residential",
    "floors" : "2",
    "lastUpdate" : "2015-08-01T12:34:56Z"
  }
}

8.4.  Requirements Class “Geography Markup Language (GML), Simple Features Profile, Level 0”

In addition to HTML and GeoJSON, a significant volume of feature data is available in XML-based formats, notably GML. Therefore, this standard specifies requirements classes for GML. The Simple Features Profile, Level 0, is the simplest profile of GML and is typically supported by tools.

The GML Simple Features Profile is restricted to data with 2D geometries with linear/planar interpolation (points, line strings, polygons). In addition, the Level 0 profile is limited to features that can be stored in a tabular data structure.

Table 3 — Media types and XML elements for each resource

The namespace prefixes used above and in the OGC API Features Core XML schemas are:

• core: http://www.opengis.net/ogcapi-features-1/1.0

• sf: http://www.opengis.net/ogcapi-features-1/1.0/sf

• gml: http://www.opengis.net/gml/3.2

• atom: http://www.w3.org/2005/Atom

• xlink: http://www.w3.org/1999/xlink

The mapping of the content from the responses specified in the Core requirements class to the XML is straightforward. All links have to be encoded as HTTP header Link.

See Clause 6.3 for links to example responses in XML.

8.5.  Requirements Class “Geography Markup Language (GML), Simple Features Profile, Level 2”

The difference between this requirements class and the Level 0 requirements class is that non-spatial feature properties are not restricted to atomic values (strings, numbers, etc.).

9.1.  Basic requirements

Servers conforming to this requirements class define their API by an OpenAPI Document.

The requirements /req/core/root-success and /req/core/api-definition-success in Core require that the API definition documents are referenced from the landing page.

OpenAPI definitions can be created using different approaches. A typical example is the representation of the feature collections. One approach is to use a path parameter collectionId, i.e., the API definition has only a single path entry for all feature collections. Another approach is to explicitly define each feature collection in a separate path and without a path parameter, which allows to specify filter parameters or explicit feature schemas per feature collection. Both approaches are valid.

9.2.  Complete definition

Note that servers that, for example, are access-controlled (see Security), support web cache validation, CORS or that use HTTP redirection will make use of additional HTTP status codes beyond regular codes such as 200 for successful GET requests and 400, 404 or 500 for error situations. See HTTP status codes.

Clients have to be prepared to receive responses not documented in the OpenAPI definition. For example, additional errors may occur in the transport layer outside of the server.

9.3.  Exceptions

An exception response object definition

description: An error occurred.
content:
  application/json:
    schema:
      $ref: http://schemas.opengis.net/ogcapi/features/part1/1.0/openapi/schemas/exception.yaml
  text/html:
    schema:
      type: string

9.4.  Security

The OpenAPI specification currently supports the following security schemes:

• HTTP authentication,

• an API key (either as a header or as a query parameter),

• OAuth2’s common flows (implicit, password, application and access code) as defined in RFC6749, and

• OpenID Connect Discovery.

9.5.  Features