OGC Testbed-15: Maps and Tiles API Engineering Report

  openapi: 3.0.2
  info:
    title: OGC API Common
    description: |-
      Common components used in the OGC API family of standards. Deeply inspired in Clemens Portele work.

      This document is also available in [GitHub](https://github.com/opengeospatial/oapi_common/tree/master/OAPI-Common/openapi).

      This document copies or is inspired in
      [GitHub](https://github.com/opengeospatial/WFS_FES/blob/master/core/openapi/bbox/ogcapi-features-1.yaml)   from Clemens Portele

    version: '1.0.0'
    contact:
      name: Joan Maso
      email: joan.maso@uab.cat
    license:
      name: OGC License
      url: 'https://raw.githubusercontent.com/opengeospatial/oapi_common/master/LICENSE'

  components:
    parameters:
      bbox:
        name: bbox
        in: query
        description: |-
          Only elements that have a geometry that intersects the bounding box are selected.
          The bounding box is provided as four or six numbers, depending on whether the
          coordinate reference system includes a vertical axis (elevation or depth):

          * Lower left corner, coordinate axis 1
          * Lower left corner, coordinate axis 2
          * Lower left corner, coordinate axis 3 (optional)
          * Upper right corner, coordinate axis 1
          * Upper right corner, coordinate axis 2
          * Upper right corner, 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 by another parameter in the API (e.g 'bbox-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 an element 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.
        required: false
        schema:
          type: array
          minItems: 4
          maxItems: 6
          items:
            type: number
            format: double
        style: form
        explode: false
      collectionId:
        name: collectionId
        in: path
        description: local identifier of a collection
        required: true
        schema:
          type: string
      datetime:
        name: datetime
        in: query
        description: |-
          Either a date-time or an interval, open or closed. Date and time expressions
          adhere to RFC 3339. Open intervals are expressed using double-dots.

          Examples:

          * A date-time: "2018-02-12T23:20:50Z"
          * A closed interval: "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z"
          * Open intervals: "2018-02-12T00:00:00Z/.." or "../2018-03-18T12:31:12Z"

          Only elemenets that have a temporal property that intersects the value of
          `datetime` are selected.

          If a element has multiple temporal properties, it is the decision of the
          server whether only a single temporal property is used to determine
          the extent or all relevant temporal properties.
        required: false
        schema:
          type: string
        style: form
        explode: false
      limit:
        name: limit
        in: query
        description: |-
          The optional limit parameter limits the number of items that are presented in the response document.

          Only items are counted that are on the first level of the collection in the response document.
          Nested objects contained within the explicitly requested items shall not be counted.

          Minimum = 1. Maximum = 10000. Default = 10.
        required: false
        schema:
          type: number
          format: integer
          minimum: 0
          maximum: 10000
          default: 10
        style: form
        explode: false
      offset:
        name: offset
        in: query
        description: |-
          The optional offset parameter indicates the index within the result set from which the server shall begin presenting results in the response document. The first element has an index of 0.
          If offset is greater or equal to the number of items in the collection, the server should return an empty list.

          Minimum = 0. Default = 0.
        required: false
        style: form
        explode: false
        schema:
          type: number
          format: integer
          minimum: 0
          default: 0
        example: 0
      resultType:
        name: resultType
        in: query
        description: |-
          This service will respond to a query in one of two ways (excluding an
          exception response). It may either generate a complete response document
          containing resources that satisfy the operation or it may simply
          generate an empty response container that indicates the count of the
          total number of resources that the operation would return. Which of
          these two responses is generated is determined by the value of the
          optional resultType parameter.

          The allowed values for this parameter are "results" and "hits".

          If the value of the resultType parameter is set to "results", the server
          will generate a complete response document containing resources that
          satisfy the operation.

          If the value of the resultType attribute is set to "hits", the server
          will generate an empty response document containing no resource
          instances.

          The default value is "results".
        required: false
        style: form
        explode: false
        schema:
          type: string
          default: results
          enum:
            - hits
            - results
        example: results
      f-json-html:
        name: f
        in: query
        description: |-
          The format of the response. If no value is provided, the standard http
          rules apply, i.e., the accept header is used to determine the format.

          Pre-defined values are "json" and "html". The response to other
          values is determined by the server.
        required: false
        style: form
        explode: false
        schema:
          type: string
          enum:
            - application/json
            - text/html
        example: application/json
      f-json:
        name: f
        in: query
        description: |-
          The format of the response. If no value is provided, the standard http
          rules apply, i.e., the accept header is used to determine the format.

          The only pre-defined value is "json". The response to other values is
          determined by the server.
        required: false
        style: form
        explode: false
        schema:
          type: string
          enum:
            - application/json
        example: application/json
    schemas:
      collection:
        # This object does not include the links element that should be added as and additional element  using a personlizaed version of collection-link with allOf
        type: object
        required:
          - id
        properties:
          id:
            description: identifier of the collection used, for example, in URIs
            type: string
            example: buildings
          title:
            description: human readable title of the collection
            type: string
            example: Buildings in the city of Bonn
          description:
            description: a description of the collection
            type: string
            example: This collection contains buildings
          keywords:
            description: keywords about the elements in the collection
            type: array
            items:
              $ref: '#/components/schemas/keyword'
          attribution:
            description: |-
              The provider of the source data for the collection. Map viewers normally show this information at the bottom of the map
            type: string
            example: OpenStreetMap
          extent:
            $ref: '#/components/schemas/extent'

          #itemType:
          #Deprecated. The links are indicating the availability of a collection as features, covreages etc
          #  description: indicator about the type of the  items in the collection (the default value is 'feature'; alternative values are 'coverage', 'image', etc).
          #  type: string
          #  default: feature
          #  example: feature
          crs:
            description: The list of coordinate reference systems supported by the service. 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'
          # crsLibray:
          #this is just an idea for preventing long lists of CRSs. We have to see if there is consensus adopting it.
          #  type: string
          #  description: |-
          #    Reference to a CRS library giving support to a comprehensive list of CRSs that are not advertised but supported anyway.
          #  example: PROJ4G
          crsSpatialExtents:
            type: array
            description: |-
              Minimum spatial extent surrounding the spatial resource for each CRS available
            items:
              $ref: '#/components/schemas/spatialExtent'
            example:
              - bbox:
                  - -180
                  - -90
                  - 180
                  - 90
                crs: 'http://www.opengis.net/def/crs/OGC/1.3/CRS84'
              - bbox:
                  - -20037508.3427892
                  - -20037508.3427892
                  - 20037508.3427892
                  - 20037508.3427892
                crs: 'http://www.opengis.net/def/crs/EPSG/0/3395'
      collection-link:
        # This element is only used by `/collections` and is not directly by other APIs in '/collection/{collectionId}`  because they probably will need to add other links to other resource types in the examples. Instead, it would be copied and enriched with the right examples.
        type: object
        required:
          - links
        properties:
          links:
            type: array
            items:
              $ref: '#/components/schemas/link'
            example:
              - $ref: '#/components/examples/link-collection-from-collections'
              - $ref: '#/components/examples/link-collection-describedBy'
              - $ref: '#/components/examples/link-collection-license-html'
              - $ref: '#/components/examples/link-collection-license-rdf'
      collections:
        type: object
        required:
          - links
          - collections
        properties:
          links:
            type: array
            nullable: true
            items:
              $ref: '#/components/schemas/link'
            example:
              - href: 'http://data.example.org/collections?f=json'
                rel: self
                type: application/json
                title: this document
              - href: 'http://data.example.org/collections?f=html'
                rel: alternate
                type: text/html
                title: this document as HTML
              - href: 'http://schemas.example.org/1.0/dataset.xsd'
                rel: describedBy
                type: application/xml
                title: GML application schema for Acme Corporation dataset data
              - href: 'http://download.example.org/dataset.gpkg'
                rel: enclosure
                type: application/geopackage+sqlite3
                title: Bulk download (GeoPackage)
                length: 472546
          collections:
            type: array
            items:
              allOf:
                - $ref: '#/components/schemas/collection'
                - $ref: '#/components/schemas/collection-link'
      confClasses:
        type: object
        required:
          - conformsTo
        properties:
          conformsTo:
            type: array
            items:
              type: string
              format: uri
            example:
              - 'http://www.opengis.net/spec/ogcapi-common-1/1.0/req/core'
      exception:
        type: object
        required:
          - code
        properties:
          code:
            type: string
          description:
            type: string
        example:
          code: '500'
          description: 'An internal server error occured. Incident ID: 1234567. Please contact admin@example.org.'
      extent:
        description: |-
          The extent of 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.
          It is recommended that the statial extent is expected in CRS84 except if this is not possible.
        type: object
        properties:
          spatial:
            $ref: '#/components/schemas/spatialExtent'
          temporal:
            $ref: '#/components/schemas/temporalExtent'
      spatialExtent:
        description: |-
          The spatial extent of the element in the collection.
        type: object
        required: bbox
        properties:
          bbox:
            $ref: '#/components/schemas/bbox'
          crs:
            $ref: '#/components/schemas/crs'
      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: |-
            West, south, east, north edges of the bounding box. The coordinates
            are in the coordinate reference system specified in `crs`. By default
            this is WGS 84 longitude/latitude.
          type: array
          minItems: 4
          maxItems: 6
          items:
            type: number
          example:
            - - 7.01
              - 50.63
              - 7.22
              - 50.78
      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'
      temporalExtent:
        description: |-
          The temporal extent of the element in the collection.
        type: object
        nullable: true
        properties:
          interval:
            $ref: '#/components/schemas/temporalInterval'
          trs:
            $ref: '#/components/schemas/trs'
      temporalInterval:
        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
        nullable: true
        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:
            - '2010-02-15T12:34:56Z'
            - 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'
      landingPage:
        # This object does not include the links element that should be added as an additional element using a personlizaed version of landingPage-link with allOf
        type: object
        properties:
          title:
            type: string
            example: Buildings in Bonn
          description:
            type: string
            example: Access to data about buildings in the city of Bonn via a Web API that conforms to the OGC API Features specification.
      landingPage-link:
        # This element is not directly by other APIs in '/landingPage`because they probably will need to add other links to other resource types in the examples. Instead, it would be copied and enriched with the right examples.
        type: object
        required:
          - links
        properties:
          links:
            type: array
            items:
              $ref: '#/components/schemas/link'
            example:
              - $ref: '#/components/examples/link-landingPage-this'
              - $ref: '#/components/examples/link-landingPage-alternate'
              - $ref: '#/components/examples/link-landingPage-service-json'
              - $ref: '#/components/examples/link-landingPage-service-html'
              - $ref: '#/components/examples/link-landingPage-conformance'
              - $ref: '#/components/examples/link-landingPage-collections-json'
              - $ref: '#/components/examples/link-landingPage-collections-html'
      id-link:
        type: object
        description: |-
          Reusable object that contains an id to a resource and links where the object is described or a representation retrieved. Typically it is useful for paths like `/resources` and `resources/{resourceId}`.   `/resources` will respond an array of id-link listing the `resourceId` and the links to get it. `/collections` and `/collections/{collectionId}` is an exception to this pattern.
          The fact that `links` is an array can be used to advertise the same object representation in different formats.
        required:
          - id
          - links
        properties:
          id:
            type: string
          title:
            type: string
          links:
            type: array
            minItems: 1
            items:
              $ref: '#/components/schemas/link'
        example:
          id: night
          title: Topographic night style
          links:
            - href: 'https://example.com/api/1.0/styles/night?f=mapbox'
              rel: stylesheet
              type: 'application/vnd.mapbox.style+json'
            - href: 'https://example.com/api/1.0/styles/night?f=sld10'
              rel: stylesheet
              type: 'application/vnd.ogc.sld+xml;version=1.0'
      link:
        type: object
        required:
          - href
        properties:
          href:
            type: string
            example: 'http://data.example.com/buildings/123'
          rel:
            type: string
            example: alternate
          type:
            type: string
            pattern: '^(?=[-a-z]{1,127}/[-\.a-z0-9]{1,127}$)[a-z]+(-[a-z]+)*/[a-z0-9]+([-\.][a-z0-9]+)*$'
            example: application/geo+json
          hreflang:
            type: string
            example: en
          title:
            type: string
            example: 'Trierer Strasse 70, 53115 Bonn'
          length:
            type: integer
            minimum: 0
      keyword:
        required:
          - keyword
        type: object
        nullable: true
        properties:
          keyword:
            type: string
            example: land cover
          code:
            type: string
            example: '4612'
          codeSpace:
            type: string
            example: https://www.eionet.europa.eu/gemet/en/concept/
      numberMatched:
        description: The number of elements that match the selection parameters like `bbox`.
        type: integer
        minimum: 0
        example: 127
      numberReturned:
        description: |-
          The number of elements in the collection.

          A server may omit this information in a response, if the information
          about the number of elements is not known or difficult to compute.

          If the value is provided, the value shall be identical to the number
          of items in the returned array.
        type: integer
        minimum: 0
        example: 10
      timeStamp:
        description: This property indicates the time and date when the response was generated.
        type: string
        format: date-time
        example: '2017-08-17T08:05:32Z'
    responses:
      LandingPage:
        description: |-
          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`).
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/landingPage'
            example:
              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 specification.
              links:
                - $ref: '#/components/examples/link-landingPage-this'
                - $ref: '#/components/examples/link-landingPage-alternate'
                - $ref: '#/components/examples/link-landingPage-service-json'
                - $ref: '#/components/examples/link-landingPage-service-html'
                - $ref: '#/components/examples/link-landingPage-conformance'
                - $ref: '#/components/examples/link-landingPage-collections-json'
                - $ref: '#/components/examples/link-landingPage-collections-html'
          text/html:
            schema:
              type: string
      ConformanceDeclaration:
        description: |-
          The URIs of all conformance classes supported by the server.

          This is just an example that To support "generic" clients that want to access multiple OGC API implementations - and not "just" a specific API / server, the server declares the conformance classes it implements and conforms to.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/confClasses'
            example:
              conformsTo:
                - 'http://www.opengis.net/spec/ogcapi-common-1/1.0/conf/core'
          text/html:
            schema:
              type: string
      Collections:
        description: |-
          The collections shared by this API.

          This response can be references directly for every service that wants only essential information at the collections level. /collections/collectionId might return more information.

          The dataset is organized as one or more collections. This resource
          provides information about and access to the collections.

          The response contains the list of collections. For each collection, a link
          to other resources is present (e.g. the items in the collection; 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 (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 elements in the collection (the default value, if the indicator is not provided, is 'feature').

        content:
          application/json:
            schema:
              $ref: '#/components/schemas/collections'
          text/html:
            schema:
              type: string
      Collection:
        description: |-
          Information about the collection with id `collectionId`.
          This is an examples for commons only. A service should combine the schemas from common with others specific to its services.

          The response might also contain a linkto the elements in the collection
          (e.g. 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 (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').

        content:
          application/json:
            schema:
              allOf:
                - $ref: '#/components/schemas/collection'
                - $ref: '#/components/schemas/collection-link'
          text/html:
            schema:
              type: string
      NoContent:
        # Response associated to 204
        description: |-
          No content (useful for OPTIONS)
        headers:
          Allow:
            $ref: '#/components/headers/Allow'
      Created:
        # Response associated to 201
        description: |-
          Resource created
        headers:
          Location:
            $ref: '#/components/headers/Location'
      Updated:
        # Response associated to 204
        description: |-
          The resource has been updated or created
      Deleted:
        # Response associated to 204
        description: The resource has been deleted
      NotModified:
        # Response associated to 304
        description: The resource has not been modified
      Invalid:
        # Response associated to 400
        description: The resource is an invalid input
      InvalidParam:
        # Response associated to 400
        description: Invalid or unknown query parameters
      UnauthorizedAccess:
        # Response associated to 401
        description: Access not unauthorized
      NotFound:
        # Response associated to 404
        description: The requested URI was not found
      UnsupportedFormat:
        # Response associated to 406
        description: The media types accepted by the client are not supported for this resource
      AlreadyExist:
        # Response associated to 409
        description: Resource with that id already exists
      ServerError:
        # Response associated to 500
        description: A server error occurred
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/exception'
          text/html:
            schema:
              type: string
    headers:
      Location:
        schema:
          type: string
          format: uri
        description: |-
          URI of the new resource
      Allow:
        schema:
          type: string
        description: |-
          Comma separated list of verbs supported by the resource
      Link:
        description: |-
          link header according to RFC 8288
        schema:
          type: string
        example: 'Link: <http://data.example.org/collections/buildings/items.json>; rel=\"self\"; type=\"application/geo+json\"'
    examples:
      link-collection-from-collections:
        href: 'http://example.com/collections/buildings?f=json'
        rel: item
        type: 'application/json'
        title: CollectionId path description in the OpenAPI
      link-collection-this:
        href: 'http://example.com/collections/buildings?f=json'
        rel: self
        type: 'application/json'
        title: This document
      link-collection-describedBy:
        href: 'http://example.com/concepts/buildings.html'
        rel: describedBy
        type: text/html
      link-collection-license-html:
        href: 'https://creativecommons.org/publicdomain/zero/1.0/'
        rel: license
        type: text/html
        title: CC0-1.0
      link-collection-license-rdf:
        href: 'https://creativecommons.org/publicdomain/zero/1.0/rdf'
        rel: license
        type: application/rdf+xml
        title: CC0-1.0
      link-landingPage-this:
        href: 'http://data.example.org/?f=json'
        rel: self
        type: application/json
        title: this document
      link-landingPage-alternate:
        href: 'http://data.example.org/?f=html'
        rel: alternate
        type: text/html
        title: this document in HTML
      link-landingPage-service-json:
        href: 'http://data.example.org/api?f=json'
        rel: service-desc
        type: application/vnd.oai.openapi+json;version=3.0
        title: the API definition in OpenAPI 3.0 JSON
      link-landingPage-service-html:
        href: 'http://data.example.org/api?f=html'
        rel: service-desc
        type: text/html
        title: the API definition in HTML
      link-landingPage-conformance:
        href: 'http://data.example.org/conformance?f=json'
        rel: conformance
        type: application/json
        title: the list of conformance classes implemented by this API
      link-landingPage-collections-json:
        href: 'http://data.example.org/collections?f=json'
        rel: data
        type: application/json
        title: The collections in the dataset in JSON
      link-landingPage-collections-html:
        href: 'http://data.example.org/collections?f=html'
        rel: data
        type: text/html
        title: The collections in the dataset in HTML