openapi.yaml

openapi: 3.0.3
info:
  title: The SpatioTemporal Asset Catalog API - Filter
  description: Adds parameters to compare properties and only return the items that match
  version: 1.0.0-rc.3

tags:
  - name: Core
    description: Part of STAC API - Core definition
  - name: Collections
    description: Part of STAC API - Collections definition
  - name: Features
    description: Part of STAC API - Features definition
  - name: Item Search 
    description: Part of STAC API - Item Search definition
  - name: Filter Extension
    description: Part of STAC API - Filter extension definition

paths:
  "/":
    get:
      description: Landing Page
      tags:
        - Core
      responses:
        "200":
          description: Landing Page
          links:
            queryables:
              operationId: getQueryables
              description: |-
                A link with rel=queryables for the entire catalog.

  /queryables:
    get:
      summary: Get the JSON Schema defining the list of variable terms that can be used in CQL2 expressions.
      operationId: getQueryables
      description: |-
        This endpoint returns a list of variable terms that can be used in CQL2 expressions. The
        precise definition of this can be found in the OGC API - Features - Part 3: Filtering and the 
        Common Query Language (CQL2) specification.
      tags:
        - Filter Extension
      responses:
        "200":
          $ref: "#/components/responses/Queryables"
        default:
          $ref: "#/components/responses/Error"
  /collections/{collectionId}:
    get:
      description: |-
        This endpoint returns a list of Collections.
      tags:
        - Features
        - Collections
      parameters:
        - in: path
          name: collectionId
          schema:
            type: string
          required: true
          description: ID of Collection
      responses:
        "200":
          description: Collection description
          links:
            queryables:
              operationId: getQueryablesForCollection
              description: |-
                A link with rel=queryables for queryables to only apply to this collection.
  /collections/{collectionId}/items:
    get:
      tags:
        - Features
        - Filter Extension
      summary: fetch features
      description: |-
        Fetch features of the feature collection with id `collectionId`.

        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.
      operationId: getFeatures
      parameters:
        - in: path
          name: collectionId
          schema:
            type: string
          required: true
          description: ID of Collection
        - $ref: "https://api.stacspec.org/v1.0.0/ogcapi-features/openapi.yaml#/components/parameters/limit"
        - $ref: "https://api.stacspec.org/v1.0.0/ogcapi-features/openapi.yaml#/components/parameters/bbox"
        - $ref: "https://api.stacspec.org/v1.0.0/ogcapi-features/openapi.yaml#/components/parameters/datetime"
        - $ref: "#/components/parameters/filter"
        - $ref: "#/components/parameters/filter-lang"
        - $ref: "#/components/parameters/filter-crs"
      responses:
        "200":
          $ref: "https://api.stacspec.org/v1.0.0/ogcapi-features/openapi.yaml#/components/responses/Features"
        "404":
          $ref: "https://api.stacspec.org/v1.0.0/ogcapi-features/openapi.yaml#/components/responses/NotFound"
        "4XX":
          $ref: "https://api.stacspec.org/v1.0.0/ogcapi-features/openapi.yaml#/components/responses/Error"
        "5XX":
          $ref: "https://api.stacspec.org/v1.0.0/ogcapi-features/openapi.yaml#/components/responses/Error"
  /collections/{collectionId}/queryables:
    get:
      summary: Get the JSON Schema defining the list of variable terms that can be used in CQL2 expressions.
      operationId: getQueryablesForCollection
      description: |-
        This endpoint returns a list of variable terms that can be used in CQL2 expressions. The
        precise definition of this can be found in the OGC API - Features - Part 3: Filtering and the 
        Common Query Language (CQL) specification.
      parameters:
        - in: path
          name: collectionId
          schema:
            type: string
          required: true
          description: ID of Collection
      tags:
        - Filter Extension
      responses:
        "200":
          $ref: "#/components/responses/Queryables"
        default:
          $ref: "#/components/responses/Error"
  /search:
    get:
      summary: Search STAC items with full-featured filtering.
      operationId: getItemSearch
      description: |-
        Retrieve Items matching filters. Intended as a shorthand API for simple
        queries.
        This method is required to implement.
        If this endpoint is implemented on a server, it is required to add a
        link referring to this endpoint with `rel` set to `search` to the
        `links` array in `GET /`. As `GET` is the default method, the `method`
        may not be set explicitly in the link.
      tags:
        - Item Search
        - Filter Extension
      parameters:
        - $ref: "#/components/parameters/filter"
        - $ref: "#/components/parameters/filter-lang"
        - $ref: "#/components/parameters/filter-crs"
      responses:
        "200":
          description: A feature collection.
          content:
            application/geo+json:
              schema:
                $ref: "https://api.stacspec.org/v1.0.0/item-search/openapi.yaml#/components/schemas/itemCollection"
            text/html:
              schema:
                type: string
        "4XX":
          $ref: "#/components/responses/Error"
        "5XX":
          $ref: "#/components/responses/Error"
    post:
      summary: Search STAC items with full-featured filtering.
      operationId: postItemSearch
      description: |-
        Retrieve items matching filters. Intended as the standard, full-featured
        query API.
        If this endpoint is implemented on a server, it is required to add a
        link referring to this endpoint with `rel` set to `search` and `method`
        set to `POST` to the `links` array in `GET /`.
      tags:
        - Item Search
        - Filter Extension
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/searchBody"
      responses:
        "200":
          description: A feature collection.
          content:
            application/geo+json:
              schema:
                $ref: "https://api.stacspec.org/v1.0.0/item-search/openapi.yaml#/components/schemas/itemCollection"
            text/html:
              schema:
                type: string
        "4XX":
          $ref: "#/components/responses/Error"
        "5XX":
          $ref: "#/components/responses/Error"
components:
  parameters:
    filter:
      name: filter
      x-stac-api-fragment: filter
      in: query
      description: |-
        **Extension:** Filter

        A CQL2 filter expression for filtering items.
      required: true
      schema:
        oneOf:
          - $ref: "#/components/schemas/filter-cql2-json"
          - $ref: "#/components/schemas/filter-cql2-text"
    filter-lang:
      name: filter-lang
      x-stac-api-fragment: filter
      in: query
      description: |-
        **Extension:** Filter

        The CQL2 filter encoding that the 'filter' value uses. Must be one of 'cql2-text' or 'cql2-json'.
      required: false
      schema:
        $ref: "#/components/schemas/filter-lang"
    filter-crs:
      name: filter-crs
      x-stac-api-fragment: filter
      in: query
      description: |-
        **Extension:** Filter

        The CRS used by spatial predicates in the filter parameter. In STAC API, only value that must be accepted
        is 'http://www.opengis.net/def/crs/OGC/1.3/CRS84'.
      required: false
      schema:
        $ref: "#/components/schemas/filter-crs"
  schemas:
    searchBody:
      type: object
      x-stac-api-fragment: filter
      description: |-
        **Extension:** Filter

        A filter for properties in Items.
      allOf: # Combines the searchBody of Item-filter and the inline model
        - $ref: "https://api.stacspec.org/v1.0.0/item-search/openapi.yaml#/components/schemas/searchBody"
      properties:
        filter:
          $ref: "#/components/schemas/filter-cql2-json"
        filter-lang:
          $ref: "#/components/schemas/filter-lang"
        filter-crs:
          $ref: "#/components/schemas/filter-crs"
    filter-cql2-text:
      description: |
        A CQL2 filter expression in the 'cql2-text' encoding.
      type: string
    filter-cql2-json:
      $ref: "https://raw.githubusercontent.com/opengeospatial/ogcapi-features/master/cql2/standard/schema/cql2.yml#/components/schemas/booleanExpression"
    filter-lang:
      description: |
        The CQL2 filter encoding that the 'filter' value uses.
      type: string
      enum:
        - "cql2-text"
        - "cql2-json"
    filter-crs:
      description: |
        The coordinate reference system (CRS) used by spatial literals in the 'filter' value.  The only value that STAC APIs must
        accept is 'http://www.opengis.net/def/crs/OGC/1.3/CRS84'.
      type: string
      format: uri
    exception:
      type: object
      description: |-
        Information about the exception: an error code plus an optional description.
      required:
        - code
      properties:
        code:
          type: string
        description:
          type: string
  responses:
    Queryables:
      description: A JSON Schema defining the Queryables allowed in CQL2 expressions
      content:
        application/schema+json:
          schema:
            type: object
    Error:
      description: An error occurred.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/exception"