This document explains the structure of a STAPI Product.
STAPI Product objects are represented in JSON format and are very flexible. Any JSON object that contains all the required fields is a valid STAPI Product. A Product object contains a minimal set of required properties to be valid and can be extended through the use of constraints and parameters.
| Element | Type | Description |
|---|---|---|
| products | [Product Object] | REQUIRED List of Product offered in the application. |
| links | [Link Object] | REQUIRED Links for e.g. pagination. |
| Element | Type | Description |
|---|---|---|
| type | string | REQUIRED. Must be set to Product to be a valid Product. |
| id | string | REQUIRED. Identifier for the Product that is unique across the provider. |
| conformsTo | [string] | Conformance classes that apply to the product specifically. |
| title | string | A short descriptive one-line title for the Product. |
| description | string | REQUIRED. Detailed multi-line description to fully explain the Collection. CommonMark 0.29 syntax MAY be used for rich text representation. |
| keywords | [string] | List of keywords describing the Product. |
| license | string | REQUIRED. Collection's license(s), either a SPDX License identifier, various if multiple licenses apply or proprietary for all other cases. |
| providers | [Provider Object] | A list of providers, which may include all organizations capturing or processing the data or the hosting provider. Providers should be listed in chronological order with the most recent provider being the last element of the list. |
| links | [Link Object] | REQUIRED. A list of references to other documents. |
Additional properties are allowed to be placed in the top-level object, comparable to how STAC Collections work. STAC Collection fields can be reused, including fields defined in STAC Collection extensions.
The object provides information about a provider. A provider is any of the organizations that captures or processes the content of the Collection and therefore influences the data offered by this Collection. May also include information about the final storage provider hosting the data.
| Field Name | Type | Description |
|---|---|---|
| name | string | REQUIRED. The name of the organization or the individual. |
| description | string | Multi-line description to add further provider information such as processing details for processors and producers, hosting details for hosts or basic contact information. CommonMark 0.29 syntax MAY be used for rich text representation. |
| roles | [string] | Role of the provider. Set to producer or reseller |
| url | string | Homepage on which the provider describes the dataset and publishes contact information. |
roles: The provider's role(s) can be one or more of the following elements:
- licensor: The organization that is licensing the dataset under the license specified in the Collection's
licensefield. - producer: The producer of the data is the provider that initially captured and processed the source data, e.g. ESA for Sentinel-2 data.
- processor: A processor is any provider who processed data to a derived product.
- host: The host is the actual provider offering the data on their storage. There should be no more than one host, specified as last element of the list.
This object describes a relationship with another entity. Data providers are advised to be liberal with links.
| Field Name | Type | Description |
|---|---|---|
| href | string | REQUIRED. The actual link in the format of an URL. Relative and absolute links are both allowed. |
| rel | string | REQUIRED. Relationship between the current document and the linked document. |
| type | string | Media Type of the referenced entity. |
| title | string | A human readable title to be used in rendered displays of the link. |
The relation type product-parameters is to be used to link to the GET /products/{productId}/parameters endpoint.
Parameters define the Opportunity and Order properties that can be used in CQL2 JSON filter statements to reduce the results set.
For example, a parameter might be eo:cloud_cover which allows users to filter Opportunities to only results with eo:cloud_cover within a certain range.
The parameters must be exposed as a separate endpoint that is provided at
GET /products/{productId}/parameters.
A The response body for parameters is a JSON Schema definition. Empty schemas are not allowed. It is recommended to use JSON Schema draft-07. For an introduction to JSON Schema, see Learn JSON Schema.
There are many Tasking parameters that cannot be represented by JSON Schema. For these parameters, strongly consider documenting the constraint in the "description" property of the relevant constraint or use the "links" attribute to link the user out to documentation that describes additional parameters.
TODO: Example TODO: Documented link type for client libraries to be able to find and surface to users