openapi.yaml

openapi: 3.0.1
info:
  title: A sample API conforming to the OGC Web Feature Service standard
  version: 0.0.1
  description: >-
    This is a sample OpenAPI definition that conforms to the OGC Web Feature
    Service specification (conformance classes: "Core", "GeoJSON", "HTML" and
    "OpenAPI 3.0").
  contact:
    name: Acme Corporation
    email: info@example.org
    url: 'http://example.org/'
  license:
    name: CC-BY 4.0 license
    url: 'https://creativecommons.org/licenses/by/4.0/'
servers:
  - url: 'https://dev.example.org/'
    description: Development server
  - url: 'https://data.example.org/'
    description: Production server
paths:
  '/':
    get:
      summary: landing page of this API
      description: >-
        The landing page provides links to the API definition, the Conformance
        statements and the metadata about the feature data in this dataset.
      operationId: getLandingPage
      tags:
        - Capabilities
      responses:
        '200':
          description: links to the API capabilities
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/root'
            text/html:
              schema:
                type: string
  '/conformance':
    get:
      summary: information about standards that this API conforms to
      description: >-
        list all requirements classes specified in a standard (e.g., WFS 3.0
        Part 1: Core) that the server conforms to
      operationId: getRequirementsClasses
      tags:
        - Capabilities
      responses:
        '200':
          description: the URIs of all requirements classes supported by the server
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/req-classes'
        default:
          description: An error occured.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/exception'
  '/collections':
    get:
      summary: describe the feature collections in the dataset
      operationId: describeCollections
      tags:
        - Capabilities
      responses:
        '200':
          description: Metdata about the feature collections shared by this API.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/content'
            text/html:
              schema:
                type: string
        default:
          description: An error occured.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/exception'
            text/html:
              schema:
                type: string
  '/collections/{collectionId}':
    get:
      summary: 'describe the {collectionId} feature collection'
      operationId: describeCollection
      tags:
        - Capabilities
      parameters:
      - $ref: '#/components/parameters/collectionId'
      responses:
        '200':
          description: 'Metadata about the {collectionId} collection shared by this API.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/collectionInfo'
            text/html:
              schema:
                type: string
        default:
          description: An error occured.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/exception'
            text/html:
              schema:
                type: string
  '/collections/{collectionId}/items':
    get:
      summary: 'retrieve features of feature collection {collectionId}'
      description: >-
        Every feature in a dataset belongs to a collection. A dataset may
        consist of multiple feature collections. A feature collection is often a
        collection of features of a similar type, based on a common schema.\

        Use content negotiation to request HTML or GeoJSON.
      operationId: getFeatures
      tags:
        - Features
      parameters:
      - $ref: '#/components/parameters/collectionId'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/bbox'
      - $ref: '#/components/parameters/time'
      responses:
        '200':
          description: >-
            Information about the feature collection plus the first features
            matching the selection parameters.
          content:
            application/geo+json:
              schema:
                $ref: '#/components/schemas/featureCollectionGeoJSON'
            text/html:
              schema:
                type: string
        default:
          description: An error occured.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/exception'
            text/html:
              schema:
                type: string
  '/collections/{collectionId}/items/{featureId}':
    get:
      summary: retrieve a feature; use content negotiation to request HTML or GeoJSON
      operationId: getFeature
      tags:
        - Features
      parameters:
      - $ref: '#/components/parameters/collectionId'
      - $ref: '#/components/parameters/featureId'
      responses:
        '200':
          description: A feature.
          content:
            application/geo+json:
              schema:
                $ref: '#/components/schemas/featureGeoJSON'
            text/html:
              schema:
                type: string
        default:
          description: An error occured.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/exception'
            text/html:
              schema:
                type: string
components:
  parameters:
    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: integer
        minimum: 1
        maximum: 10000
        default: 10
      style: form
      explode: false
    bbox:
      name: bbox
      in: query
      description: >
        Only features 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 WGS84 longitude/latitude
        (http://www.opengis.net/def/crs/OGC/1.3/CRS84) unless a different coordinate
        reference system is specified in the parameter `bbox-crs`.

        For WGS84 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 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.
      required: false
      schema:
        type: array
        minItems: 4
        maxItems: 6
        items:
          type: number
      style: form
      explode: false
    time:
      name: time
      in: query
      description: >-
        Either a date-time or a period string that adheres to RFC 3339. Examples:

        * A date-time: "2018-02-12T23:20:50Z"
        * A period: "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z" or "2018-02-12T00:00:00Z/P1M6DT12H31M12S"

        Only features that have a temporal property that intersects the value of
        `time` are selected.

        If a feature 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
    collectionId:
      name: collectionId
      in: path
      required: true
      description: Identifier (name) of a specific collection
      schema:
        type: string
    featureId:
      name: featureId
      in: path
      description: Local identifier of a specific feature
      required: true
      schema:
        type: string
  schemas:
    exception:
      type: object
      required:
        - code
      properties:
        code:
          type: string
        description:
          type: string
    root:
      type: object
      required:
        - links
      properties:
        links:
          type: array
          items:
            $ref: '#/components/schemas/link'
          example:
            - href: 'http://data.example.org/'
              rel: self
              type: application/json
              title: this document
            - href: 'http://data.example.org/api'
              rel: service
              type: application/openapi+json;version=3.0
              title: the API definition
            - href: 'http://data.example.org/conformance'
              rel: conformance
              type: application/json
              title: WFS 3.0 conformance classes implemented by this server
            - href: 'http://data.example.org/collections'
              rel: data
              type: application/json
              title: Metadata about the feature collections
    req-classes:
      type: object
      required:
        - conformsTo
      properties:
        conformsTo:
          type: array
          items:
            type: string
          example:
            - 'http://www.opengis.net/spec/wfs-1/3.0/req/core'
            - 'http://www.opengis.net/spec/wfs-1/3.0/req/oas30'
            - 'http://www.opengis.net/spec/wfs-1/3.0/req/html'
            - 'http://www.opengis.net/spec/wfs-1/3.0/req/geojson'
    link:
      type: object
      required:
        - href
      properties:
        href:
          type: string
        rel:
          type: string
          example: prev
        type:
          type: string
          example: application/geo+json
        hreflang:
          type: string
          example: en
    content:
      type: object
      required:
        - links
        - collections
      properties:
        links:
          type: array
          items:
            $ref: '#/components/schemas/link'
          example:
            - href: 'http://data.example.org/collections.json'
              rel: self
              type: application/json
              title: this document
            - href: 'http://data.example.org/collections.html'
              rel: alternate
              type: text/html
              title: this document as HTML
            - href: 'http://schemas.example.org/1.0/foobar.xsd'
              rel: describedBy
              type: application/xml
              title: XML schema for Acme Corporation data
        collections:
          type: array
          items:
            $ref: '#/components/schemas/collectionInfo'
    collectionInfo:
      type: object
      required:
        - name
        - links
      properties:
        name:
          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
        description:
          description: 'a description of the features in the collection'
          type: string
          example: Buildings in the city of Bonn.
        links:
          type: array
          items:
            $ref: '#/components/schemas/link'
          example:
            - href: 'http://data.example.org/collections/buildings/items'
              rel: item
              type: application/geo+json
              title: Buildings
            - href: 'http://example.org/concepts/building.html'
              rel: describedBy
              type: text/html
              title: Feature catalogue for buildings
        extent:
          $ref: '#/components/schemas/extent'
        crs:
          description: >-
            The coordinate reference systems in which geometries
            may be retrieved. Coordinate reference systems are identified
            by a URI. The first coordinate reference system is the
            coordinate reference system that is used by default. This
            is always "http://www.opengis.net/def/crs/OGC/1.3/CRS84", i.e.
            WGS84 longitude/latitude.
          type: array
          items:
            type: string
          default:
            - 'http://www.opengis.net/def/crs/OGC/1.3/CRS84'
    extent:
      type: object
      properties:
        crs:
          description: >-
            Coordinate reference system of the coordinates in the spatial extent (property `spatial`).
            In the Core, only WGS84 longitude/latitude is supported. Extensions may support additional
            coordinate reference systems.
          type: string
          enum:
            - 'http://www.opengis.net/def/crs/OGC/1.3/CRS84'
          default: 'http://www.opengis.net/def/crs/OGC/1.3/CRS84'
        spatial:
          description: >-
            West, north, east, south edges of the spatial extent. The minimum and
            maximum values apply to the coordinate reference system WGS84 longitude/latitude
            that is supported in the Core. If, for example, a projected coordinate reference
            system is used, the minimum and maximum values need to be adjusted.
          type: array
          minItems: 4
          maxItems: 6
          items:
            type: number
          example:
            - -180
            - -90
            - 180
            - 90
        trs:
          description: >-
            Temporal reference system of the coordinates in the temporal extent (property `temporal`).
            In the Core, only the Gregorian calendar is supported. Extensions may support additional
            temporal reference systems.
          type: string
          enum:
            - 'http://www.opengis.net/def/uom/ISO-8601/0/Gregorian'
          default: 'http://www.opengis.net/def/uom/ISO-8601/0/Gregorian'
        temporal:
          description: Begin and end times of the temporal extent.
          type: array
          minItems: 2
          maxItems: 2
          items:
            type: string
            format: dateTime
          example:
            - '2011-11-11T12:22:11Z'
            - '2012-11-24T12:32:43Z'
    featureCollectionGeoJSON:
      type: object
      required:
        - type
        - features
      properties:
        type:
          type: string
          enum:
            - FeatureCollection
        features:
          type: array
          items:
            $ref: '#/components/schemas/featureGeoJSON'
        links:
          type: array
          items:
            $ref: '#/components/schemas/link'
        timeStamp:
          type: string
          format: dateTime
        numberMatched:
          type: integer
          minimum: 0
        numberReturned:
          type: integer
          minimum: 0
    featureGeoJSON:
      type: object
      required:
        - type
        - geometry
        - properties
      properties:
        type:
          type: string
          enum:
            - Feature
        geometry:
          $ref: '#/components/schemas/geometryGeoJSON'
        properties:
          type: object
          nullable: true
        id:
          oneOf:
            - type: string
            - type: integer
    geometryGeoJSON:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - Point
            - MultiPoint
            - LineString
            - MultiLineString
            - Polygon
            - MultiPolygon
            - GeometryCollection
tags:
  - name: Capabilities
    description: >-
      Essential characteristics of this API including information about the
      data.
  - name: Features
    description: >-
      Access to data (features).