commons.yaml

openapi: 3.0.3
info:
  title: The SpatioTemporal Asset Catalog API - Commons
  description: This is the OpenAPI version of the core STAC spec JSON Schemas.
  version: 1.0.0-beta.4
paths: {}
components:
  responses:
    Error:
      description: An error occurred.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/exception'
  schemas:
    exception:
      type: object
      description: |-
        Information about the exception: an error code plus an optional description.
      required:
        - code
      properties:
        code:
          type: string
        description:
          type: string
    conformanceClasses:
      type: object
      required:
        - conformsTo
      properties:
        conformsTo:
          description: >-
            A list of all conformance classes implemented by the server.
            In addition to the STAC-specific conformance classes, all OGC-related
            conformance classes listed at `GET /conformances` must be listed here.
            This entry should mirror what `GET /conformances` returns, if implemented.
          type: array
          items:
            type: string
    catalog:
      type: object
      required:
        - stac_version
        - type
        - id
        - description
        - links
      properties:
        stac_version:
          $ref: '#/components/schemas/stac_version'
        stac_extensions:
          $ref: '#/components/schemas/stac_extensions'
        type:
          type: string
        id:
          type: string
        title:
          type: string
        description:
          type: string
        links:
          $ref: '#/components/schemas/links'
    collection:
      type: object
      required:
        - stac_version
        - type
        - id
        - description
        - license
        - extent
        - links
      properties:
        stac_version:
          $ref: '#/components/schemas/stac_version'
        stac_extensions:
          $ref: '#/components/schemas/stac_extensions'
        type:
          type: string
        id:
          description: identifier of the collection used, for example, in URIs
          type: string
        title:
          description: human readable title of the collection
          type: string
        description:
          type: string
          description: >-
            Detailed multi-line description to fully explain the catalog or
            collection.

            [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for
            rich text representation.
        keywords:
          type: array
          description: List of keywords describing the collection.
          items:
            type: string
        license:
          $ref: '#/components/schemas/license'
        extent:
          $ref: '#/components/schemas/extent'
        providers:
          $ref: '#/components/schemas/providers'
        links:
          $ref: '#/components/schemas/links'
        summaries:
          description: |-
            Summaries are either a unique set of all available values *or*
            statistics. Statistics by default only specify the range (minimum
            and maximum values), but can optionally be accompanied by additional
            statistical values. The range can specify the potential range of
            values, but it is recommended to be as precise as possible. The set
            of values must contain at least one element and it is strongly
            recommended to list all values. It is recommended to list as many
            properties as reasonable so that consumers get a full overview of
            the Collection. Properties that are covered by the Collection
            specification (e.g. `providers` and `license`) may not be repeated
            in the summaries.
          type: object
          additionalProperties:
            oneOf:
              - type: array
                title: Set of values
                items:
                  description: A value of any type.
              - type: object
                title: Statistics
                description: |-
                  By default, only ranges with a minimum and a maximum value can
                  be specified. Ranges can be specified for ordinal values only,
                  which means they need to have a rank order. Therefore, ranges
                  can only be specified for numbers and some special types of
                  strings. Examples: grades (A to F), dates or times.
                  Implementors are free to add other derived statistical values
                  to the object, for example `mean` or `stddev`.
                required:
                  - min
                  - max
                properties:
                  min:
                    anyOf:
                      - type: string
                      - type: number
                  max:
                    anyOf:
                      - type: string
                      - type: number
      example:
        stac_version: 1.0.0
        stac_extensions: []
        type: Collection
        id: Sentinel-2
        title: 'Sentinel-2 MSI: MultiSpectral Instrument, Level-1C'
        description: |
          Sentinel-2 is a wide-swath, high-resolution, multi-spectral
          imaging mission...
        license: proprietary
        keywords:
          - copernicus
          - esa
          - eu
          - msi
          - radiance
          - sentinel
        providers:
          - name: ESA
            roles:
              - producer
              - licensor
            url: 'https://sentinel.esa.int/web/sentinel/user-guides/sentinel-2-msi'
        extent:
          spatial:
            bbox:
              - - -180
                - -56
                - 180
                - 83
          temporal:
            interval:
              - - '2015-06-23T00:00:00Z'
                - '2019-07-10T13:44:56Z'
        summaries:
          datetime:
            min: '2015-06-23T00:00:00Z'
            max: '2019-07-10T13:44:56Z'
          'sci:citation':
            - 'Copernicus Sentinel data [Year]'
          'eo:gsd':
            - 10
            - 30
            - 60
          'platform':
            - sentinel-2a
            - sentinel-2b
          'constellation':
            - sentinel-2
          'instruments':
            - msi
          'view:off_nadir':
            min: 0
            max: 100
          'view:sun_elevation':
            min: 6.78
            max: 89.9
          'eo:bands':
            - - name: B1
                common_name: coastal
                center_wavelength: 4.439
              - name: B2
                common_name: blue
                center_wavelength: 4.966
              - name: B3
                common_name: green
                center_wavelength: 5.6
              - name: B4
                common_name: red
                center_wavelength: 6.645
              - name: B5
                center_wavelength: 7.039
              - name: B6
                center_wavelength: 7.402
              - name: B7
                center_wavelength: 7.825
              - name: B8
                common_name: nir
                center_wavelength: 8.351
              - name: B8A
                center_wavelength: 8.648
              - name: B9
                center_wavelength: 9.45
              - name: B10
                center_wavelength: 1.3735
              - name: B11
                common_name: swir16
                center_wavelength: 1.6137
              - name: B12
                common_name: swir22
                center_wavelength: 2.2024
        links:
          - rel: self
            href: 'http://cool-sat.com/collections/Sentinel-2'
          - rel: root
            href: 'http://cool-sat.com/collections'
          - rel: license
            href: 'https://scihub.copernicus.eu/twiki/pub/SciHubWebPortal/TermsConditions/Sentinel_Data_Terms_and_Conditions.pdf'
            title: Legal notice on the use of Copernicus Sentinel Data and Service Information
    extent:
      type: object
      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.

        The first item in the array describes the overall extent of
        the data. All subsequent items describe more precise extents, 
        e.g., to identify clusters of data.
        Clients only interested in the overall extent will only need to
        access the first item in each array.
      required:
        - spatial
        - temporal
      properties:
        spatial:
          description: |-
            The spatial extent of the features in the collection.
          type: object
          required:
            - bbox
          properties:
            bbox:
              description: |-
                One or more bounding boxes that describe the spatial extent of the dataset.

                The first bounding box describes the overall spatial
                extent of the data. All subsequent bounding boxes describe 
                more precise bounding boxes, e.g., to identify clusters of data.
                Clients only interested in the overall spatial extent will
                only need to access the first item in each array.
              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
          required:
            - interval
          properties:
            interval:
              description: |-
                One or more time intervals that describe the temporal extent of the dataset.

                The first time interval describes the overall
                temporal extent of the data. All subsequent time intervals describe 
                more precise time intervals, e.g., to identify clusters of data.
                Clients only interested in the overall extent will only need
                to access the first item in each array.
              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.

                  The value `null` is supported and indicates an open time interval.
                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'
    links:
      type: array
      items:
        $ref: '#/components/schemas/link'
    link:
      title: Link
      type: object
      required:
        - href
        - rel
      properties:
        href:
          type: string
          format: uri
          description: The location of the resource
        rel:
          type: string
          description: Relation type of the link
        type:
          type: string
          description: The media type of the resource
        title:
          type: string
          description: Title of the resource
        method:
          type: string
          enum:
            - GET
            - POST
          default: GET
          description: Specifies the HTTP method that the resource expects
        headers:
          type: object
          description: Object key values pairs they map to headers
          example:
            Accept: application/json
        body:
          type: object
          description: For POST requests, the resource can specify the HTTP body as a JSON object.
        merge:
          type: boolean
          default: false
          description: |-
            This is only valid when the server is responding to POST request.

            If merge is true, the client is expected to merge the body value
            into the current request body before following the link.
            This avoids passing large post bodies back and forth when following
            links, particularly for navigating pages through the `POST /search`
            endpoint.

            NOTE: To support form encoding it is expected that a client be able
            to merge in the key value pairs specified as JSON
            `{"next": "token"}` will become `&next=token`.
    license:
      type: string
      description: |-
        License(s) of the data as a SPDX
        [License identifier](https://spdx.org/licenses/). Alternatively, use
        `proprietary` if the license is not on the SPDX license list or
        `various` if multiple licenses apply. In these two cases links to the
        license texts SHOULD be added, see the `license` link relation type.

        Non-SPDX licenses SHOULD add a link to the license text with the
        `license` relation in the links section. The license text MUST NOT be
        provided as a value of this field. If there is no public license URL
        available, it is RECOMMENDED to host the license text and
        link to it.
      example: Apache-2.0
    providers:
      type: array
      description: >-
        A list of providers, which may include all organizations capturing or
        processing the data or the hosting provider. Providers should be listed
        in chronological order with the most recent provider being the last
        element of the list.
      items:
        type: object
        title: Provider
        required:
          - name
        properties:
          name:
            description: The name of the organization or the individual.
            type: string
          description:
            description: >-
              Multi-line description to add further provider information such as
              processing details for processors and producers, hosting details
              for hosts or basic contact information.


              [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for
              rich text representation.
            type: string
          roles:
            description: |-
              Roles of the provider.

              The provider's role(s) can be one or more of the following
              elements:

              * licensor: The organization that is licensing the dataset under
                the license specified in the collection's license field.
              * producer: The producer of the data is the provider that
                initially captured and processed the source data, e.g. ESA for
                Sentinel-2 data.
              * processor: A processor is any provider who processed data to a
                derived product.
              * host: The host is the actual provider offering the data on their
                storage. There should be no more than one host, specified as last
                element of the list.
            type: array
            items:
              type: string
              enum:
                - producer
                - licensor
                - processor
                - host
          url:
            description: >-
              Homepage on which the provider describes the dataset and publishes
              contact information.
            type: string
            format: url
    bbox:
      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.

        Example: The bounding box of the New Zealand Exclusive Economic Zone in
        WGS 84 (from 160.6°E to 170°W and from 55.95°S to 25.89°S) would be
        represented in JSON as `[160.6, -55.95, -170, -25.89]` and in a query as
        `bbox=160.6,-55.95,-170,-25.89`.
      type: array
      minItems: 4
      maxItems: 6
      items:
        type: number
      example:
        - -110
        - 39.5
        - -105
        - 40.5
    datetime:
      type: string
      format: date-time
      nullable: true
      description: |-
        The searchable date and time of the assets, in UTC.
        It is formatted according to [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6).
        `null` is allowed, but requires `start_datetime` and `end_datetime` from common metadata to be set.
      example: '2018-02-12T00:00:00Z'
    stac_version:
      title: STAC version
      type: string
      example: 1.0.0
    stac_extensions:
      title: STAC extensions
      type: array
      uniqueItems: true
      items:
        anyOf:
          - title: Reference to a JSON Schema
            type: string
            format: uri
          - title: Reference to a core extension
            type: string
    item:
      description: A GeoJSON Feature augmented with foreign members that contain values relevant to a STAC entity
      type: object
      required:
        - stac_version
        - id
        - type
        - geometry
        - bbox
        - links
        - properties
        - assets
      properties:
        stac_version:
          $ref: '#/components/schemas/stac_version'
        stac_extensions:
          $ref: '#/components/schemas/stac_extensions'
        id:
          $ref: '#/components/schemas/itemId'
        bbox:
          $ref: '#/components/schemas/bbox'
        geometry:
          $ref: '#/components/schemas/geometryGeoJSON'
        type:
          $ref: '#/components/schemas/itemType'
        links:
          $ref: '#/components/schemas/links'
        assets:
          $ref: '#/components/schemas/assets'
      example:
        stac_version: 1.0.0
        stac_extensions:
          - 'https://stac-extensions.github.io/eo/v1.0.0/schema.json'
          - 'https://stac-extensions.github.io/view/v1.0.0/schema.json'
          - 'https://example.com/cs-extension/1.0/schema.json'
        type: Feature
        id: CS3-20160503_132131_05
        bbox:
          - -122.59750209
          - 37.48803556
          - -122.2880486
          - 37.613537207
        geometry:
          type: Polygon
          coordinates:
            - - - -122.308150179
                - 37.488035566
              - - -122.597502109
                - 37.538869539
              - - -122.576687533
                - 37.613537207
              - - -122.2880486
                - 37.562818007
              - - -122.308150179
                - 37.488035566
        properties:
          datetime: '2016-05-03T13:22:30.040Z'
          title: A CS3 item
          license: PDDL-1.0
          providers:
            - name: CoolSat
              roles:
                - producer
                - licensor
              url: 'https://cool-sat.com/'
          'view:sun_azimuth': 168.7
          'eo:cloud_cover': 0.12
          'view:off_nadir': 1.4
          'platform': coolsat2
          'instruments':
            - cool_sensor_v1
          'eo:bands': []
          'view:sun_elevation': 33.4
          'eo:gsd': 0.512
        collection: CS3
        links:
          - rel: self
            href: 'http://cool-sat.com/collections/CS3/items/20160503_132130_04'
          - rel: root
            href: 'http://cool-sat.com/collections'
          - rel: parent
            href: 'http://cool-sat.com/collections/CS3'
          - rel: collection
            href: 'http://cool-sat.com/collections/CS3'
        assets:
          analytic:
            href: 'http://cool-sat.com/static-catalog/CS3/20160503_132130_04/analytic.tif'
            title: 4-Band Analytic
          thumbnail:
            href: 'http://cool-sat.com/static-catalog/CS3/20160503_132130_04/thumbnail.png'
            title: Thumbnail
    itemId:
      type: string
      description: Provider identifier, a unique ID.
    itemType:
      type: string
      description: The GeoJSON type
      enum:
        - Feature
    properties:
      type: object
      required:
        - datetime
      description: provides the core metatdata fields plus extensions
      properties:
        datetime:
          $ref: '#/components/schemas/datetime'
      additionalProperties:
        description: Any additional properties added in via Item specification or extensions.
    assets:
      type: object
      additionalProperties:
        type: object
        required:
          - href
        properties:
          href:
            type: string
            format: url
            description: Link to the asset object
            example: >-
              http://cool-sat.com/catalog/collections/cs/items/CS3-20160503_132130_04/thumb.png
          title:
            type: string
            description: Displayed title
            example: Thumbnail
          description:
            type: string
            description: >-
              Multi-line description to explain the asset.


              [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for
              rich text representation.
            example: Small 256x256px PNG thumbnail for a preview.
          type:
            type: string
            description: Media type of the asset
            example: image/png
          roles:
            type: array
            items:
              type: string
            description: Purposes of the asset
            example:
              - thumbnail
    geometryGeoJSON:
      oneOf:
        - $ref: '#/components/schemas/pointGeoJSON'
        - $ref: '#/components/schemas/multipointGeoJSON'
        - $ref: '#/components/schemas/linestringGeoJSON'
        - $ref: '#/components/schemas/multilinestringGeoJSON'
        - $ref: '#/components/schemas/polygonGeoJSON'
        - $ref: '#/components/schemas/multipolygonGeoJSON'
        - $ref: '#/components/schemas/geometrycollectionGeoJSON'
    geometrycollectionGeoJSON:
      type: object
      required:
        - type
        - geometries
      properties:
        type:
          type: string
          enum:
            - GeometryCollection
        geometries:
          type: array
          items:
            $ref: '#/components/schemas/geometryGeoJSON'
    linestringGeoJSON:
      type: object
      required:
        - type
        - coordinates
      properties:
        type:
          type: string
          enum:
            - LineString
        coordinates:
          type: array
          minItems: 2
          items:
            type: array
            minItems: 2
            items:
              type: number
    multilinestringGeoJSON:
      type: object
      required:
        - type
        - coordinates
      properties:
        type:
          type: string
          enum:
            - MultiLineString
        coordinates:
          type: array
          items:
            type: array
            minItems: 2
            items:
              type: array
              minItems: 2
              items:
                type: number
    multipointGeoJSON:
      type: object
      required:
        - type
        - coordinates
      properties:
        type:
          type: string
          enum:
            - MultiPoint
        coordinates:
          type: array
          items:
            type: array
            minItems: 2
            items:
              type: number
    multipolygonGeoJSON:
      type: object
      required:
        - type
        - coordinates
      properties:
        type:
          type: string
          enum:
            - MultiPolygon
        coordinates:
          type: array
          items:
            type: array
            items:
              type: array
              minItems: 4
              items:
                type: array
                minItems: 2
                items:
                  type: number
    pointGeoJSON:
      type: object
      required:
        - type
        - coordinates
      properties:
        type:
          type: string
          enum:
            - Point
        coordinates:
          type: array
          minItems: 2
          items:
            type: number
    polygonGeoJSON:
      type: object
      required:
        - type
        - coordinates
      properties:
        type:
          type: string
          enum:
            - Polygon
        coordinates:
          type: array
          items:
            type: array
            minItems: 4
            items:
              type: array
              minItems: 2
              items:
                type: number
    featureCollectionGeoJSON:
      type: object
      required:
        - type
        - features
      properties:
        type:
          type: string
          enum:
            - FeatureCollection
        features:
          type: array
          items:
            $ref: '#/components/schemas/featureGeoJSON'
    featureGeoJSON:
      type: object
      required:
        - type
        - geometry
        - properties
      properties:
        type:
          type: string
          enum:
            - Feature
        geometry:
          $ref: '#/components/schemas/geometryGeoJSON'
        properties:
          type: object
          nullable: true