STAC-standalone.yaml

openapi: 3.0.1
info:
  title: The SpatioTemporal Asset Catalog API (standalone)
  version: 0.6.1
  description: >-
    This is an OpenAPI definition of the core SpatioTemporal Asset Catalog API
    specification. Any service that implements this endpoint to allow search of
    spatiotemporal assets can be considered a STAC API. The endpoint is also
    available as an OpenAPI fragment that can be integrated with other OpenAPI
    definitions, and is designed to slot seamlessly into a WFS 3 API definition.
  contact:
    name: Cool Sat Corp
    email: info@cool-sat.com
    url: 'http://cool-sat.com/contact/'
  license:
    name: Apache License 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0'
servers:
  - url: 'http://dev.cool-sat.com/'
    description: Development server
  - url: 'http://www.cool-sat.com'
    description: Production server
paths:
  /stac:
    get:
      summary: Return the root catalog or collection.
      description: >-
        Returns the root STAC Catalog or STAC Collection that is the entry point
        for users to browse with STAC Browser or for search engines to crawl.
        This can either return a single STAC Collection or more commonly a STAC
        catalog that usually lists sub-catalogs of STAC Collections, i.e. a
        simple catalog that lists all collections available through the API.
      tags:
        - STAC
      responses:
        '200':
          description: A catalog json definition. Used as an entry point for a crawler.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/catalogDefinition'
  /stac/search:
    get:
      summary: Search STAC items by simple filtering.
      description: >-
        Retrieve Items matching filters. Intended as a shorthand API for simple
        queries. This method is optional.
      operationId: getSearchSTAC
      tags:
        - STAC
      parameters:
        - $ref: '#/components/parameters/bbox'
        - $ref: '#/components/parameters/time'
        - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: A feature collection.
          content:
            application/geo+json:
              schema:
                $ref: '#/components/schemas/itemCollection'
            text/html:
              schema:
                type: string
        default:
          description: An error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/exception'
            text/html:
              schema:
                type: string
    post:
      summary: Search STAC items by full-featured filtering.
      description: >-
        retrieve items matching filters. Intended as the standard, full-featured
        query API. This method is mandatory.
      operationId: postSearchSTAC
      tags:
        - STAC
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/searchBody'
      responses:
        '200':
          description: A feature collection.
          content:
            application/geo+json:
              schema:
                $ref: '#/components/schemas/itemCollection'
            text/html:
              schema:
                type: string
        default:
          description: An error occurred.
          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 RFC3339. 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
    links:
      type: array
      items:
        $ref: '#/components/schemas/link'
    link:
      type: object
      required:
        - href
        - rel
      additionalProperties: true
      properties:
        href:
          type: string
          format: url
          example: 'http://www.geoserver.example/stac/naip/child/catalog.json'
        rel:
          type: string
          example: child
        type:
          type: string
          example: application/json
        title:
          type: string
          example: NAIP Child Catalog
    searchBody:
      description: The search criteria
      type: object
      allOf:
        - $ref: '#/components/schemas/bboxFilter'
        - $ref: '#/components/schemas/timeFilter'
        - $ref: '#/components/schemas/intersectsFilter'
        - type: object
          properties:
            limit:
              type: number
              example: 10
    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.
      type: array
      minItems: 4
      maxItems: 6
      items:
        type: number
      example:
        - -110
        - 39.5
        - -105
        - 40.5
    bboxFilter:
      type: object
      description: Only return items that intersect the provided bounding box.
      properties:
        bbox:
          $ref: '#/components/schemas/bbox'
    timeFilter:
      description: An object representing a time based filter.
      type: object
      properties:
        time:
          $ref: '#/components/schemas/time'
    intersectsFilter:
      type: object
      description: Only returns items that intersect with the provided polygon.
      properties:
        intersects:
          $ref: 'http://geojson.org/schema/Geometry.json'
    time:
      type: string
      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.
      example: '2018-02-12T00:00:00Z/2018-03-18T12:31:12Z'
    catalogDefinition:
      type: object
      required:
        - stac_version
        - id
        - description
        - links
      additionalProperties: true
      properties:
        stac_version:
          type: string
          example: 0.6.1
        id:
          type: string
          example: naip
        title:
          type: string
          example: NAIP Imagery
        description:
          type: string
          example: Catalog of NAIP Imagery.
        links:
          $ref: '#/components/schemas/links'
    itemCollection:
      type: object
      required:
        - features
        - type
      properties:
        type:
          type: string
          enum:
            - FeatureCollection
        features:
          type: array
          items:
            $ref: '#/components/schemas/item'
        links:
          $ref: '#/components/schemas/itemCollectionLinks'
    item:
      type: object
      required:
        - id
        - type
        - geometry
        - bbox
        - links
        - properties
        - assets
      properties:
        id:
          $ref: '#/components/schemas/itemId'
        bbox:
          $ref: '#/components/schemas/bbox'
        geometry:
          $ref: 'http://geojson.org/schema/Geometry.json'
        type:
          $ref: '#/components/schemas/itemType'
        properties:
          $ref: '#/components/schemas/itemProperties'
        links:
          $ref: '#/components/schemas/links'
        assets:
          $ref: '#/components/schemas/itemAssets'
      example:
        type: Feature
        id: CS3-20160503_132130_04
        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:21:30.040Z'
        links:
          - rel: self
            href: >-
              http://cool-sat.com/catalog/collections/cs/items/CS3-20160503_132130_04.json
        assets:
          analytic:
            title: 4-Band Analytic
            href: >-
              http://cool-sat.com/catalog/collections/cs/items/CS3-20160503_132130_04/analytic.tif
          thumbnail:
            title: Thumbnail
            href: >-
              http://cool-sat.com/catalog/collections/cs/items/CS3-20160503_132130_04/thumb.png
            type: image/png
    itemId:
      type: string
      example: path/to/example.tif
      description: 'Provider identifier, a unique ID, potentially a link to a file.'
    itemType:
      type: string
      description: The GeoJSON type
      enum:
        - Feature
    itemAssets:
      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
          type:
            type: string
            description: Media type of the asset
            example: image/png
    itemProperties:
      type: object
      required:
        - datetime
      description: provides the core metatdata fields plus extensions
      properties:
        datetime:
          $ref: '#/components/schemas/time'
      additionalProperties:
        description: Any additional properties added in via extensions.
    itemCollectionLinks:
      type: array
      description: >-
        An array of links. Can be used for pagination, e.g. by providing a link
        with the `next` relation type.
      items:
        $ref: '#/components/schemas/link'
      example:
        - rel: next
          href: >-
            http://api.cool-sat.com/query/gasd312fsaeg/ANsXtp9mrqN0yrKWhf-y2PUpHRLQb1GT-mtxNcXou8TwkXhi1Jbk
tags:
  - name: STAC
    description: Extension to WFS3 Core to support STAC metadata model and search API