openapi-collections.yaml

openapi: 3.0.3
info:
  title: STAC API - Collections
  version: v1.0.0
  description: >-
    This is an OpenAPI definition of the SpatioTemporal Asset Catalog API - Collections
    specification.  This is a subset of the STAC API - Features specification.
  contact:
    name: STAC Specification
    url: "http://stacspec.org"
  license:
    name: Apache License 2.0
    url: "http://www.apache.org/licenses/LICENSE-2.0"
  x-conformance-classes: ["https://api.stacspec.org/v1.0.0/collections"]
tags:
  - name: Core
    description: essential characteristics of a STAC API
  - name: Collections
    description: All endpoints related to STAC API - Collections
paths:
  "/":
    get:
      tags:
        - Core
      summary: landing page
      description: |-
        The landing page provides links to the sub-resources.
      operationId: getLandingPage
      responses:
        "200":
          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 Feature
            Collections (path `/collections`, link relation
            `data`).
          content:
            application/json:
              schema:
                $ref: "../core/openapi.yaml#/components/schemas/landingPage"
              example:
                stac_version: "1.0.0"
                type: Catalog
                id: sentinel
                title: Copernicus Sentinel Imagery
                description: Catalog of Copernicus Sentinel 1 and 2 imagery.
                conformsTo:
                  - "https://api.stacspec.org/v1.0.0/core"
                  - "http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/core"
                  - "http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/oas30"
                  - "http://www.opengis.net/spec/ogcapi-features-1/1.0/conf/geojson"
                links:
                  - href: "http://data.example.org/"
                    rel: self
                    type: application/json
                    title: this document
                  - href: "http://data.example.org/api"
                    rel: service-desc
                    type: application/vnd.oai.openapi+json;version=3.0
                    title: the API definition
                  - href: "http://data.example.org/api.html"
                    rel: service-doc
                    type: text/html
                    title: the API documentation
                  - href: "http://data.example.org/conformance"
                    rel: conformance
                    type: application/json
                    title: OGC API conformance classes implemented by this server
                  - href: "http://data.example.org/collections"
                    rel: data
                    type: application/json
                    title: Information about the feature collections
  "/collections":
    get:
      tags:
        - Collections
      summary: the feature collections in the dataset
      description: |-
        A body of Feature Collections that belong or are used together with additional links.
        Request may not return the full set of metadata per Feature Collection.
      operationId: getCollections
      responses:
        "200":
          $ref: "#/components/responses/Collections"
        "4XX":
          $ref: "../core/commons.yaml#/components/responses/Error"
        "5XX":
          $ref: "../core/commons.yaml#/components/responses/Error"
  "/collections/{collectionId}":
    get:
      tags:
        - Collections
      summary: |-
        describe the feature collection with id `collectionId`
      description: |-
        A single Feature Collection for the given if `collectionId`.
        Request this endpoint to get a full list of metadata for the Feature Collection.
      operationId: describeCollection
      parameters:
        - $ref: "#/components/parameters/collectionId"
      responses:
        "200":
          $ref: "#/components/responses/Collection"
        "404":
          $ref: "#/components/responses/NotFound"
        "4XX":
          $ref: "../core/commons.yaml#/components/responses/Error"
        "5XX":
          $ref: "../core/commons.yaml#/components/responses/Error"
components:
  parameters:
    collectionId:
      name: collectionId
      in: path
      description: local identifier of a collection
      required: true
      schema:
        type: string
  schemas:
    collections:
      type: object
      required:
        - links
        - collections
      properties:
        links:
          $ref: "../core/commons.yaml#/components/schemas/links"
        collections:
          type: array
          items:
            $ref: "../core/commons.yaml#/components/schemas/collection"
  responses:
    Collections:
      description: |-
        The feature collections shared by this API.

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

        The response contains the list of collections. For each collection, a link
        to 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 the items in the collection (the default value, if the indicator is not provided, is 'feature').
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/collections"
    Collection:
      description: |-
        Information about the feature collection with id `collectionId`.

        The response contains a link to 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 the items in the collection (the default value, if the indicator is not provided, is 'feature').
      content:
        application/json:
          schema:
            $ref: "../core/commons.yaml#/components/schemas/collection"
    NotFound:
      description: |-
        The requested URI was not found.