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.2

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: 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: getQueryables
              description: |-
                A link with rel=queryables for queryables to only apply to this collection.
  /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'
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.
      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'