STAC API - Context Extension Specification

• STAC API - Context Extension Specification
  • Overview
  • ItemCollection fields
  • Context Object
  • Example ItemCollection augmented with Context field

Overview

• Title: Context
• OpenAPI specification: openapi.yaml
• Conformance Classes:
  • STAC API - Item Search binding: https://api.stacspec.org/v1.0.0-rc.2/item-search#context
  • STAC API - Features binding: https://api.stacspec.org/v1.0.0-rc.2/ogcapi-features#context
• Scope: STAC API - Features, STAC API - Item Search
• Extension Maturity Classification: Deprecated
• Dependencies:
  • STAC API - Features
  • STAC API - Item Search
• Owner: none

This extension is intended to augment the core ItemCollection object when the ItemCollection is the result of a search, for example, from calling the /search API endpoint.

This fragment may be bound to either or both of STAC API - Item Search (/search endpoint) or STAC API - Features (/collections/{collectionId}/items endpoint) by advertising the relevant conformance class.

Note: OGC API Features - Part 1 has its own way returning numberMatched and numberReturned at the top level, instead of in a context object. We are hoping to align, but until then, it is required to implement both when implementing STAC Features.

• Example
• JSON Schema

ItemCollection fields

Element	Type	Description
context	Context Object	REQUIRED. The search-related metadata for the ItemCollection.

Context Object

Element	Type	Description
returned	integer	REQUIRED The count of results returned by this response. Equal to the cardinality of features array.
limit	integer | null	The maximum number of results to which the result was limited.
matched	integer	The count of total number of results that match for this query, possibly estimated, particularly in the context of NoSQL data stores.

The default sort of query results should be stable, but may not be depending on the data store's sorting performance. It is recommended that the Sort API Extension be implemented in conjunction with this extension and that fields conducive to stable sorting have sorting enabled over them.

limit - The maximum number of results requested explicitly, the default limit used by the service implementation if no parameter was provided, or the maximum limit used by the service implementation if the limit parameter was larger. null if no limit was placed on the query that retrieved these results, which should be a rare case in practice.

Example ItemCollection augmented with Context field

{
  "type": "FeatureCollection",
  "features": [ ],
  "context": {
    "returned": 9,
    "limit": 10, 
    "matched": 1092873
  }
}