diff --git a/CHANGELOG.md b/CHANGELOG.md index 3250e59fd..408428f63 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,25 +6,61 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. ## Unreleased +## [v0.9.0-rc2] - 2020-02-12 + +### Added +- [Basics](item-spec/common-metadata.md#basics) added to Common Metadata definitions with new `description` field for +Item properties +- New fields to the `link` object to facilitate [pagination support for POST requests](api-spec/api-spec.md#paging-extension) +- Data role, as a suggestion for a common role for data files to be used in case data providers don't come up with their own names and semantics +- Clarification text on HTTP verbs in STAC API +- [View Geometry Extension](extensions/view/README.md) + +### Changed +- Item `title` definition moved from core Item fields to [Common Metadata Basics](item-spec/common-metadata.md#basics) +fields. No change is required for STAC Items. +- `putFeature` can return a `PreconditionFailed` to provide more explicit information when the resource has changed in the server +- [Sort extension](api-spec/extensions/sort) now uses "+" and "-" prefixes for GET requests to denote sort order. +- Clarified how `/search` links must be added to `/` and changed that links to both GET and POST must be provided now that the method can be specified in links. +- Moved angle definitions between extensions `view` and `sat` + - `sat:off_nadir_angle` -> `view:off_nadir` + - `sat:azimuth_angle` -> `view:azimuth` + - `sat:incidence_angle` -> `view:incidence_angle` + - `sat:sun_azimuth_angle` -> `view:sun_azimuth` + - `sat:sun_elevation_angle` -> `view:sun_elevation` + + +### Removed +- In API, removed any mention of using media type `multipart/form-data` and `x-www-form-urlencoded` + +### Fixed +- Fixed Item JSON Schema now `allOf` optional Common Metadata properties are evaluated +- Clarified usage of optional Common Metadata fields for STAC Items +- Clarified usage of paging options, especially in relation to what OGC API - Features offers +- Allow Commonmark in asset description, as it's allowed everywhere else +- Put asset description in the API +- Fixed API spec regarding license expressions +- Added missing schema in the API Version extension + ## [v0.9.0-rc1] - 2020-01-06 ### Added - ItemCollection requires `stac_version` field, `stac_extensions` has also been added -- A `description` field has been added to Item assets (also Asset definitions extension). +- A `description` field has been added to Item assets (also Asset definitions extension) - Field `mission` to [Common Metadata fields](item-spec/common-metadata.md). - Extensions: - [Version Indicators extension](extensions/version/README.md), adds `version` and `deprecated` fields to STAC Items and Collections - Data Cube extension can be used in Collections, added new field `description` - Added `description` and `roles` fields to the Asset in the [Asset Extension](extensions/asset/README.md) - - Projection Extension to describe Items with Assets that have an associated geospatial projection. + - Projection Extension to describe Items with Assets that have an associated geospatial projection - STAC API: - Added the [Item and Collection API Version extension](api-spec/extensions/version/README.md) to support versioning in the API specification - - Run `npm run serve` or `npm run serve-ext` to quickly render development versions of the OpenAPI spec in the browser. + - Run `npm run serve` or `npm run serve-ext` to quickly render development versions of the OpenAPI spec in the browser ### Changed - Support for [CommonMark 0.29 instead of CommonMark 0.28](https://spec.commonmark.org/0.29/changes.html) - Collection field `property` and the merge ability moved to a new extension 'Commons' -- Added attribute `roles` to Item assets (also Asset definitions extension), to be used similarly to Link `rel`. +- Added attribute `roles` to Item assets (also Asset definitions extension), to be used similarly to Link `rel` - Updated API yaml to clarify bbox filter should be implemented without brackets. Example: `bbox=160.6,-55.95,-170,-25.89` - Collection `summaries` merge array fields now. - Several fields have been moved from extensions or item fields to the [Common Metadata fields](item-spec/common-metadata.md): @@ -44,7 +80,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. - Fields extension has a simplified format for GET parameters - `search` extension renamed to `context` extension. JSON object renamed from `search:metadata` to `context` - Removed "next" from the search metadata and query parameter, added POST body and headers to the links for paging support - - Query Extension - type restrictions on query predicates are more accurate, which may require additional implementation support. + - Query Extension - type restrictions on query predicates are more accurate, which may require additional implementation support. ### Removed - `version` field in STAC Collections. Use [Version Extension](extensions/version/README.md) instead @@ -59,7 +95,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. - `data_type` and `unit` from the `sar:bands` object in the [SAR extension](extensions/sar/README.md) - Datetime Range (`dtr`) extension. Use the [Common Metadata fields](item-spec/common-metadata.md) instead. - STAC API: - - `next` from the search metadata and query parameter, added POST body and headers to the links for paging support + - `next` from the search metadata and query parameter ### Fixed @@ -275,6 +311,7 @@ Thanks @hgs-msmith, @matthewhanson, @hgs-trutherford, @rouault, @joshfix, @alkam [Unreleased]: https://github.com/radiantearth/stac-spec/compare/master...dev +[v0.9.0-rc2]: https://github.com/radiantearth/stac-spec/compare/v0.9.0-rc1...v0.9.0-rc2 [v0.9.0-rc1]: https://github.com/radiantearth/stac-spec/compare/v0.8.0...v0.9.0-rc1 [v0.8.1]: https://github.com/radiantearth/stac-spec/compare/v0.8.0...v0.8.1 [v0.8.0]: https://github.com/radiantearth/stac-spec/compare/v0.7.0...v0.8.0 diff --git a/README.md b/README.md index bce43a71f..d835cfd6a 100644 --- a/README.md +++ b/README.md @@ -29,7 +29,7 @@ The minimal amount is specified right now, but best practices should emerge with ## Current version and branches The [master branch](https://github.com/radiantearth/stac-spec/tree/master) is the 'stable' version of the spec. It is currently version -**0.9.0-rc1** of the specification. The +**0.9.0-rc2** of the specification. The [dev](https://github.com/radiantearth/stac-spec/tree/dev) branch is where active development takes place, and may have inconsistent examples. Whenever dev stabilizes a release is cut and we merge dev in to master. So master should be stable at any given time. It is possible that there may be small releases in quick succession, especially if they are nice improvements that do diff --git a/STAC-UML.drawio b/STAC-UML.drawio index ed9c3540b..f3c52a929 100644 --- a/STAC-UML.drawio +++ b/STAC-UML.drawio @@ -1 +1 @@ -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 \ No newline at end of file +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 \ No newline at end of file diff --git a/STAC-UML.pdf b/STAC-UML.pdf index f28ef1105..fb0f458b7 100644 Binary files a/STAC-UML.pdf and b/STAC-UML.pdf differ diff --git a/api-spec/STAC-extensions.yaml b/api-spec/STAC-extensions.yaml index 99b967893..94678f179 100644 --- a/api-spec/STAC-extensions.yaml +++ b/api-spec/STAC-extensions.yaml @@ -1,7 +1,7 @@ openapi: 3.0.1 info: title: The SpatioTemporal Asset Catalog API + Extensions - version: 0.9.0-rc1 + version: 0.9.0-rc2 license: name: Apache License 2.0 url: 'http://www.apache.org/licenses/LICENSE-2.0' @@ -226,6 +226,8 @@ paths: $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' + '412': + $ref: '#/components/responses/PreconditionFailed' 5XX: $ref: '#/components/responses/InternalServerError' default: @@ -240,7 +242,7 @@ paths: patch: summary: update an existing feature by Id with a partial item definition description: >- - Use this method to update an existing feature. Requires a GeoJSON + Use this method to update an existing feature. Requires a GeoJSON fragement (containing the fields to be updated) be submitted. operationId: patchFeature tags: @@ -315,13 +317,17 @@ paths: /search: get: summary: Search STAC items with simple filtering. - description: >- + description: |- Retrieve Items matching filters. Intended as a shorthand API for simple queries. - This method is optional, but you MUST implement `POST /search` if you want to implement this method. + + 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. operationId: getSearchSTAC tags: - STAC @@ -355,15 +361,14 @@ paths: type: string post: summary: Search STAC items with full-featured filtering. - description: >- + description: |- retrieve items matching filters. Intended as the standard, full-featured query API. - This method is mandatory to implement if `GET /search` is implemented. If this endpoint is implemented on a server, it is required to add a - link with `rel` set to `search` to the `links` array in `GET /` that - refers to this endpoint. + link referring to this endpoint with `rel` set to `search` and `method` + set to `POST` to the `links` array in `GET /`. operationId: postSearchSTAC tags: - STAC @@ -461,9 +466,10 @@ components: selected. The bounding box is provided as four or six numbers, depending on - whether the - coordinate reference system includes a vertical axis (height or depth): + whether the coordinate reference system includes a vertical axis (height + + or depth): * Lower left corner, coordinate axis 1 @@ -480,24 +486,23 @@ components: The coordinate reference system of the values is WGS 84 - longitude/latitude - (http://www.opengis.net/def/crs/OGC/1.3/CRS84) unless a different - coordinate + longitude/latitude (http://www.opengis.net/def/crs/OGC/1.3/CRS84) unless + + a different coordinate reference system is specified in the parameter - reference system is specified in the parameter `bbox-crs`. + `bbox-crs`. For WGS 84 longitude/latitude the values are in most cases the sequence - of - minimum longitude, minimum latitude, maximum longitude and maximum - latitude. + of minimum longitude, minimum latitude, maximum longitude and maximum - However, in cases where the box spans the antimeridian the first value + latitude. However, in cases where the box spans the antimeridian the - (west-most box edge) is larger than the third value (east-most box - edge). + first value (west-most box edge) is larger than the third value + + (east-most box edge). If the vertical axis is included, the third and the sixth number are @@ -506,21 +511,18 @@ components: If a feature has multiple spatial geometry properties, it is the - decision of the - server whether only a single spatial geometry property is used to - determine + decision of the server whether only a single spatial geometry property - the extent or all relevant geometries. + is used to determine the extent or all relevant geometries. Example: The bounding box of the New Zealand Exclusive Economic Zone in - WGS 84 - (from 160.6°E to 170°W and from 55.95°S to 25.89°S) would be represented - in JSON + WGS 84 (from 160.6°E to 170°W and from 55.95°S to 25.89°S) would be + + represented in JSON as `[160.6, -55.95, -170, -25.89]` and in a query as - as `[160.6, -55.95, -170, -25.89]` and in a query as `bbox=160.6,-55.95,-170,-25.89`. required: false schema: @@ -607,11 +609,9 @@ components: ids: name: ids in: query - description: > + description: |- Array of Item ids to return. All other filter parameters that further - restrict the number of - - search results are ignored + restrict the number of search results are ignored required: false schema: $ref: '#/components/schemas/ids' @@ -638,10 +638,13 @@ components: sortby: name: sortby in: query - description: Allows sorting results by the specified properties + description: |- + An array of property names, prefixed by either "+" for ascending or + "-" for descending. If no prefix is provided, "+" is assumed. required: false schema: type: string + example: '+id,-properties.eo:cloud_cover' style: form explode: false fields: @@ -695,14 +698,10 @@ components: type: string example: address description: - description: >- - Detailed multi-line description to fully explain the collection. - - - [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for - rich text representation. + description: a description of the features in the collection type: string example: An address. + $ref: '#/components/schemas/description' links: type: array items: @@ -745,7 +744,7 @@ components: providers: $ref: '#/components/schemas/providers' summaries: - description: >- + description: |- Summaries are either a unique set of all available values *or* statistics. Statistics by default only specify the range (minimum and maximum values), but can optionally be accompanied by additional @@ -766,7 +765,7 @@ components: description: A value of any type. - type: object title: Statistics - description: >- + description: |- By default, only ranges with a minimum and a maximum value can be specified. Ranges can be specified for ordinal values only, which means they need to have a rank order. Therefore, ranges @@ -787,7 +786,7 @@ components: - type: string - type: number example: - stac_version: 0.9.0-rc1 + stac_version: 0.9.0-rc2 stac_extensions: [] id: Sentinel-2 title: 'Sentinel-2 MSI: MultiSpectral Instrument, Level-1C' @@ -836,10 +835,10 @@ components: - sentinel-2 instruments: - msi - 'sat:off_nadir_angle': + 'view:off_nadir': min: 0 max: 100 - 'sat:sun_elevation_angle': + 'view:sun_elevation': min: 6.78 max: 89.9 'eo:bands': @@ -1263,17 +1262,18 @@ components: merge: type: boolean default: false - description: >- + description: |- This is only valid when the server is responding to POST request. If merge is true, the client is expected to merge the body value - into the current request body before following the link. This avoids - passing large post bodies back and forth when following links, - particularly for navigating pages through the POST /search endpoint. + into the current request body before following the link. + This avoids passing large post bodies back and forth when following + links, particularly for navigating pages through the `POST /search` + endpoint. NOTE: To support form encoding it is expected that a client be able - to merge in the key value pairs specified as JSON `{"next": - "token"}` will become `&next=token` + to merge in the key value pairs specified as JSON + `{"next": "token"}` will become `&next=token`. title: Link multilinestringGeoJSON: type: object @@ -1395,22 +1395,28 @@ components: type: string format: date-time example: '2017-08-17T08:05:32Z' - license: + description: type: string - description: >- - License(s) of the data as a SPDX [License - identifier](https://spdx.org/licenses/) or - [expression](https://spdx.org/spdx-specification-21-web-version#h.jxpfx0ykyb60). - Alternatively, use `proprietary` if the license is not on the SPDX - license list or `various` if multiple licenses apply. In these two cases - links to the license texts SHOULD be added, see the `license` link - relation type. + description: |- + Detailed multi-line description to fully explain the catalog or + collection. + [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for rich + text representation. + license: + type: string + description: |- + License(s) of the data as a SPDX + [License identifier](https://spdx.org/licenses/). Alternatively, use + `proprietary` if the license is not on the SPDX license list or + `various` if multiple licenses apply. In these two cases links to the + license texts SHOULD be added, see the `license` link relation type. Non-SPDX licenses SHOULD add a link to the license text with the `license` relation in the links section. The license text MUST NOT be provided as a value of this field. If there is no public license URL - available, it is RECOMMENDED to host the license text and link to it. + available, it is RECOMMENDED to host the license text and + link to it. example: Apache-2.0 providers: type: array @@ -1438,26 +1444,22 @@ components: CommonMark 0.29 syntax MAY be used for rich text representation. type: string roles: - description: >- + description: |- Roles of the provider. - 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 license field. - + the license specified in the collection's license field. * producer: The producer of the data is the provider that - initially captured and processed the source data, e.g. ESA for - Sentinel-2 data. - + 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. - + 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. + storage. There should be no more than one host, specified as last + element of the list. type: array items: type: string @@ -1493,63 +1495,37 @@ components: maximum: 10000 description: The maximum number of results to return (page size). Defaults to 10 bbox: - description: >- + description: |- Only features that have a geometry that intersects the bounding box are - selected. The bounding box is provided as four or six numbers, - depending on whether the coordinate reference system includes a - vertical axis (elevation or depth): - * Lower left corner, coordinate axis 1 - * Lower left corner, coordinate axis 2 - * Lower left corner, coordinate axis 3 (optional) - * Upper right corner, coordinate axis 1 - * Upper right corner, coordinate axis 2 - * Upper right corner, coordinate axis 3 (optional) - The coordinate reference system of the values is WGS84 - longitude/latitude (http://www.opengis.net/def/crs/OGC/1.3/CRS84) unless - a different coordinate reference system is specified in the parameter - `bbox-crs`. - For WGS84 longitude/latitude the values are in most cases the sequence - of minimum longitude, minimum latitude, maximum longitude and maximum - latitude. However, in cases where the box spans the antimeridian the - first value (west-most box edge) is larger than the third value - (east-most box edge). - If a feature has multiple spatial geometry properties, it is the - decision of the server whether only a single spatial geometry property - is used to determine the extent or all relevant geometries. - Example: The bounding box of the New Zealand Exclusive Economic Zone in - WGS 84 - - (from 160.6°E to 170°W and from 55.95°S to 25.89°S) would be represented - in JSON - - as `[160.6, -55.95, -170, -25.89]` and in a query as + WGS 84 (from 160.6°E to 170°W and from 55.95°S to 25.89°S) would be + represented in JSON as `[160.6, -55.95, -170, -25.89]` and in a query as `bbox=160.6,-55.95,-170,-25.89`. type: array minItems: 4 @@ -1569,18 +1545,16 @@ components: $ref: '#/components/schemas/bbox' collectionsArray: type: array - description: | + description: |- Array of Collection IDs to include in the search for items. - Only Items in one of the provided Collections will be searched + Only Items in one of the provided Collections will be searched. items: type: string ids: type: array - description: > + description: |- Array of Item ids to return. All other filter parameters that further - restrict the number of - - search results are ignored + restrict the number of search results are ignored items: type: string datetimeFilter: @@ -1615,38 +1589,28 @@ components: $ref: '#/components/schemas/collectionsArray' datetime: type: string - description: >- + description: |- Either a date-time or an interval, open or closed. Date and time - expressions - - adhere to RFC 3339. Open intervals are expressed using double-dots. - + expressions adhere to RFC 3339. Open intervals are expressed using + double-dots. Examples: - * A date-time: "2018-02-12T23:20:50Z" - * A closed interval: "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z" - * Open intervals: "2018-02-12T00:00:00Z/.." or "../2018-03-18T12:31:12Z" - Only features that have a temporal property that intersects the value of - `datetime` are selected. - If a feature has multiple temporal properties, it is the decision of the - server whether only a single temporal property is used to determine - the extent or all relevant temporal properties. example: '2018-02-12T00:00:00Z/2018-03-18T12:31:12Z' stac_version: title: STAC version type: string - example: 0.9.0-rc1 + example: 0.9.0-rc2 stac_extensions: title: STAC extensions type: array @@ -1732,9 +1696,10 @@ components: assets: $ref: '#/components/schemas/itemAssets' example: - stac_version: 0.9.0-rc1 + stac_version: 0.9.0-rc2 stac_extensions: - eo + - view - 'https://example.com/cs-extension/1.0/schema.json' type: Feature id: CS3-20160503_132131_05 @@ -1766,14 +1731,14 @@ components: - producer - licensor url: 'https://cool-sat.com/' - 'sat:sun_azimuth_angle': 168.7 + 'view:sun_azimuth': 168.7 'eo:cloud_cover': 0.12 - 'sat:off_nadir_angle': 1.4 + 'view:off_nadir': 1.4 platform: coolsat2 instruments: - cool_sensor_v1 'eo:bands': [] - 'sat:sun_elevation_angle': 33.4 + 'view:sun_elevation': 33.4 'eo:gsd': 0.512 collection: CS3 links: @@ -1820,6 +1785,14 @@ components: type: string description: Displayed title example: Thumbnail + description: + type: string + description: |- + Multi-line description to explain the asset. + + [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for + rich text representation. + example: Small 256x256px PNG thumbnail for a preview. type: type: string description: Media type of the asset @@ -2064,26 +2037,43 @@ components: properties: datetime: $ref: '#/components/schemas/datetime' + catalogDefinition: + type: object + required: + - stac_version + - id + - description + - links + properties: + stac_version: + $ref: '#/components/schemas/stac_version' + stac_extensions: + $ref: '#/components/schemas/stac_extensions' + id: + description: 'identifier of the catalog used, for example, in URIs' + type: string + title: + description: human readable title of the catalog + type: string + description: + $ref: '#/components/schemas/description' + links: + type: array + items: + $ref: '#/components/schemas/link' responses: LandingPage: - description: >- + 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`). - - A link to the search endpoint (path `/search`, link relation - - `search`) is **required** to be specified if the API implements - `/search` + Links to the search endpoints (path `/search`, link relation `search`, + method `GET` or `POST`) are **required** to be specified if the API + implements `/search` for any of the specified HTTP methods. content: application/json: schema: @@ -2116,7 +2106,7 @@ components: rel: search type: application/json title: Search across feature collections - stac_version: 0.9.0-rc1 + stac_version: 0.9.0-rc2 id: naip text/html: schema: @@ -2309,6 +2299,12 @@ components: application/json: schema: $ref: '#/components/schemas/exception' + PreconditionFailed: + description: Some condition specified by the request could not be met in the server + content: + application/json: + schema: + $ref: '#/components/schemas/exception' InternalServerError: description: >- The request was syntactically and semantically valid, but an error diff --git a/api-spec/STAC.yaml b/api-spec/STAC.yaml index dec386ec0..db7fba3a1 100644 --- a/api-spec/STAC.yaml +++ b/api-spec/STAC.yaml @@ -1,7 +1,7 @@ openapi: 3.0.1 info: title: The SpatioTemporal Asset Catalog API - version: 0.9.0-rc1 + version: 0.9.0-rc2 license: name: Apache License 2.0 url: 'http://www.apache.org/licenses/LICENSE-2.0' @@ -136,13 +136,17 @@ paths: /search: get: summary: Search STAC items with simple filtering. - description: >- + description: |- Retrieve Items matching filters. Intended as a shorthand API for simple queries. - This method is optional, but you MUST implement `POST /search` if you want to implement this method. + + 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. operationId: getSearchSTAC tags: - STAC @@ -173,15 +177,14 @@ paths: type: string post: summary: Search STAC items with full-featured filtering. - description: >- + description: |- retrieve items matching filters. Intended as the standard, full-featured query API. - This method is mandatory to implement if `GET /search` is implemented. If this endpoint is implemented on a server, it is required to add a - link with `rel` set to `search` to the `links` array in `GET /` that - refers to this endpoint. + link referring to this endpoint with `rel` set to `search` and `method` + set to `POST` to the `links` array in `GET /`. operationId: postSearchSTAC tags: - STAC @@ -219,9 +222,10 @@ components: selected. The bounding box is provided as four or six numbers, depending on - whether the - coordinate reference system includes a vertical axis (height or depth): + whether the coordinate reference system includes a vertical axis (height + + or depth): * Lower left corner, coordinate axis 1 @@ -238,24 +242,23 @@ components: The coordinate reference system of the values is WGS 84 - longitude/latitude - (http://www.opengis.net/def/crs/OGC/1.3/CRS84) unless a different - coordinate + longitude/latitude (http://www.opengis.net/def/crs/OGC/1.3/CRS84) unless + + a different coordinate reference system is specified in the parameter - reference system is specified in the parameter `bbox-crs`. + `bbox-crs`. For WGS 84 longitude/latitude the values are in most cases the sequence - of - minimum longitude, minimum latitude, maximum longitude and maximum - latitude. + of minimum longitude, minimum latitude, maximum longitude and maximum + + latitude. However, in cases where the box spans the antimeridian the - However, in cases where the box spans the antimeridian the first value + first value (west-most box edge) is larger than the third value - (west-most box edge) is larger than the third value (east-most box - edge). + (east-most box edge). If the vertical axis is included, the third and the sixth number are @@ -264,21 +267,18 @@ components: If a feature has multiple spatial geometry properties, it is the - decision of the - server whether only a single spatial geometry property is used to - determine + decision of the server whether only a single spatial geometry property - the extent or all relevant geometries. + is used to determine the extent or all relevant geometries. Example: The bounding box of the New Zealand Exclusive Economic Zone in - WGS 84 - (from 160.6°E to 170°W and from 55.95°S to 25.89°S) would be represented - in JSON + WGS 84 (from 160.6°E to 170°W and from 55.95°S to 25.89°S) would be + + represented in JSON as `[160.6, -55.95, -170, -25.89]` and in a query as - as `[160.6, -55.95, -170, -25.89]` and in a query as `bbox=160.6,-55.95,-170,-25.89`. required: false schema: @@ -365,11 +365,9 @@ components: ids: name: ids in: query - description: > + description: |- Array of Item ids to return. All other filter parameters that further - restrict the number of - - search results are ignored + restrict the number of search results are ignored required: false schema: $ref: '#/components/schemas/ids' @@ -404,14 +402,10 @@ components: type: string example: address description: - description: >- - Detailed multi-line description to fully explain the collection. - - - [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for - rich text representation. + description: a description of the features in the collection type: string example: An address. + $ref: '#/components/schemas/description' links: type: array items: @@ -454,7 +448,7 @@ components: providers: $ref: '#/components/schemas/providers' summaries: - description: >- + description: |- Summaries are either a unique set of all available values *or* statistics. Statistics by default only specify the range (minimum and maximum values), but can optionally be accompanied by additional @@ -475,7 +469,7 @@ components: description: A value of any type. - type: object title: Statistics - description: >- + description: |- By default, only ranges with a minimum and a maximum value can be specified. Ranges can be specified for ordinal values only, which means they need to have a rank order. Therefore, ranges @@ -496,7 +490,7 @@ components: - type: string - type: number example: - stac_version: 0.9.0-rc1 + stac_version: 0.9.0-rc2 stac_extensions: [] id: Sentinel-2 title: 'Sentinel-2 MSI: MultiSpectral Instrument, Level-1C' @@ -545,10 +539,10 @@ components: - sentinel-2 instruments: - msi - 'sat:off_nadir_angle': + 'view:off_nadir': min: 0 max: 100 - 'sat:sun_elevation_angle': + 'view:sun_elevation': min: 6.78 max: 89.9 'eo:bands': @@ -972,17 +966,18 @@ components: merge: type: boolean default: false - description: >- + description: |- This is only valid when the server is responding to POST request. If merge is true, the client is expected to merge the body value - into the current request body before following the link. This avoids - passing large post bodies back and forth when following links, - particularly for navigating pages through the POST /search endpoint. + into the current request body before following the link. + This avoids passing large post bodies back and forth when following + links, particularly for navigating pages through the `POST /search` + endpoint. NOTE: To support form encoding it is expected that a client be able - to merge in the key value pairs specified as JSON `{"next": - "token"}` will become `&next=token` + to merge in the key value pairs specified as JSON + `{"next": "token"}` will become `&next=token`. title: Link multilinestringGeoJSON: type: object @@ -1104,22 +1099,28 @@ components: type: string format: date-time example: '2017-08-17T08:05:32Z' - license: + description: type: string - description: >- - License(s) of the data as a SPDX [License - identifier](https://spdx.org/licenses/) or - [expression](https://spdx.org/spdx-specification-21-web-version#h.jxpfx0ykyb60). - Alternatively, use `proprietary` if the license is not on the SPDX - license list or `various` if multiple licenses apply. In these two cases - links to the license texts SHOULD be added, see the `license` link - relation type. + description: |- + Detailed multi-line description to fully explain the catalog or + collection. + [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for rich + text representation. + license: + type: string + description: |- + License(s) of the data as a SPDX + [License identifier](https://spdx.org/licenses/). Alternatively, use + `proprietary` if the license is not on the SPDX license list or + `various` if multiple licenses apply. In these two cases links to the + license texts SHOULD be added, see the `license` link relation type. Non-SPDX licenses SHOULD add a link to the license text with the `license` relation in the links section. The license text MUST NOT be provided as a value of this field. If there is no public license URL - available, it is RECOMMENDED to host the license text and link to it. + available, it is RECOMMENDED to host the license text and + link to it. example: Apache-2.0 providers: type: array @@ -1147,26 +1148,22 @@ components: CommonMark 0.29 syntax MAY be used for rich text representation. type: string roles: - description: >- + description: |- Roles of the provider. - 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 license field. - + the license specified in the collection's license field. * producer: The producer of the data is the provider that - initially captured and processed the source data, e.g. ESA for - Sentinel-2 data. - + 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. - + 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. + storage. There should be no more than one host, specified as last + element of the list. type: array items: type: string @@ -1199,63 +1196,37 @@ components: maximum: 10000 description: The maximum number of results to return (page size). Defaults to 10 bbox: - description: >- + description: |- Only features that have a geometry that intersects the bounding box are - selected. The bounding box is provided as four or six numbers, - depending on whether the coordinate reference system includes a - vertical axis (elevation or depth): - * Lower left corner, coordinate axis 1 - * Lower left corner, coordinate axis 2 - * Lower left corner, coordinate axis 3 (optional) - * Upper right corner, coordinate axis 1 - * Upper right corner, coordinate axis 2 - * Upper right corner, coordinate axis 3 (optional) - The coordinate reference system of the values is WGS84 - longitude/latitude (http://www.opengis.net/def/crs/OGC/1.3/CRS84) unless - a different coordinate reference system is specified in the parameter - `bbox-crs`. - For WGS84 longitude/latitude the values are in most cases the sequence - of minimum longitude, minimum latitude, maximum longitude and maximum - latitude. However, in cases where the box spans the antimeridian the - first value (west-most box edge) is larger than the third value - (east-most box edge). - If a feature has multiple spatial geometry properties, it is the - decision of the server whether only a single spatial geometry property - is used to determine the extent or all relevant geometries. - Example: The bounding box of the New Zealand Exclusive Economic Zone in - WGS 84 - - (from 160.6°E to 170°W and from 55.95°S to 25.89°S) would be represented - in JSON - - as `[160.6, -55.95, -170, -25.89]` and in a query as + WGS 84 (from 160.6°E to 170°W and from 55.95°S to 25.89°S) would be + represented in JSON as `[160.6, -55.95, -170, -25.89]` and in a query as `bbox=160.6,-55.95,-170,-25.89`. type: array minItems: 4 @@ -1275,18 +1246,16 @@ components: $ref: '#/components/schemas/bbox' collectionsArray: type: array - description: | + description: |- Array of Collection IDs to include in the search for items. - Only Items in one of the provided Collections will be searched + Only Items in one of the provided Collections will be searched. items: type: string ids: type: array - description: > + description: |- Array of Item ids to return. All other filter parameters that further - restrict the number of - - search results are ignored + restrict the number of search results are ignored items: type: string datetimeFilter: @@ -1321,38 +1290,28 @@ components: $ref: '#/components/schemas/collectionsArray' datetime: type: string - description: >- + description: |- Either a date-time or an interval, open or closed. Date and time - expressions - - adhere to RFC 3339. Open intervals are expressed using double-dots. - + expressions adhere to RFC 3339. Open intervals are expressed using + double-dots. Examples: - * A date-time: "2018-02-12T23:20:50Z" - * A closed interval: "2018-02-12T00:00:00Z/2018-03-18T12:31:12Z" - * Open intervals: "2018-02-12T00:00:00Z/.." or "../2018-03-18T12:31:12Z" - Only features that have a temporal property that intersects the value of - `datetime` are selected. - If a feature has multiple temporal properties, it is the decision of the - server whether only a single temporal property is used to determine - the extent or all relevant temporal properties. example: '2018-02-12T00:00:00Z/2018-03-18T12:31:12Z' stac_version: title: STAC version type: string - example: 0.9.0-rc1 + example: 0.9.0-rc2 stac_extensions: title: STAC extensions type: array @@ -1419,9 +1378,10 @@ components: assets: $ref: '#/components/schemas/itemAssets' example: - stac_version: 0.9.0-rc1 + stac_version: 0.9.0-rc2 stac_extensions: - eo + - view - 'https://example.com/cs-extension/1.0/schema.json' type: Feature id: CS3-20160503_132131_05 @@ -1453,14 +1413,14 @@ components: - producer - licensor url: 'https://cool-sat.com/' - 'sat:sun_azimuth_angle': 168.7 + 'view:sun_azimuth': 168.7 'eo:cloud_cover': 0.12 - 'sat:off_nadir_angle': 1.4 + 'view:off_nadir': 1.4 platform: coolsat2 instruments: - cool_sensor_v1 'eo:bands': [] - 'sat:sun_elevation_angle': 33.4 + 'view:sun_elevation': 33.4 'eo:gsd': 0.512 collection: CS3 links: @@ -1507,6 +1467,14 @@ components: type: string description: Displayed title example: Thumbnail + description: + type: string + description: |- + Multi-line description to explain the asset. + + [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for + rich text representation. + example: Small 256x256px PNG thumbnail for a preview. type: type: string description: Media type of the asset @@ -1543,24 +1511,17 @@ components: http://api.cool-sat.com/search?next=ANsXtp9mrqN0yrKWhf-y2PUpHRLQb1GT-mtxNcXou8TwkXhi1Jbk responses: LandingPage: - description: >- + 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`). - - A link to the search endpoint (path `/search`, link relation - - `search`) is **required** to be specified if the API implements - `/search` + Links to the search endpoints (path `/search`, link relation `search`, + method `GET` or `POST`) are **required** to be specified if the API + implements `/search` for any of the specified HTTP methods. content: application/json: schema: @@ -1593,7 +1554,7 @@ components: rel: search type: application/json title: Search across feature collections - stac_version: 0.9.0-rc1 + stac_version: 0.9.0-rc2 id: naip text/html: schema: diff --git a/api-spec/api-spec.md b/api-spec/api-spec.md index 57d4e779f..2e26eb41c 100644 --- a/api-spec/api-spec.md +++ b/api-spec/api-spec.md @@ -1,26 +1,83 @@ # STAC API Specification -The STAC API is intended to be a superset of the *OGC API - Features - Part 1: Core* (OAFeat) standard. STAC API currently bases on [OAFeat version 1.0](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html), previously known as OGC Web Feature Service (WFS). We'll try to align with [upcoming versions](https://github.com/opengeospatial/ogcapi-features). +The STAC API is intended to be a superset of the *OGC API - Features - Part 1: Core* (OAFeat) standard. STAC API +currently bases on [OAFeat version 1.0](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html), previously known as +OGC Web Feature Service (WFS). We'll try to align with +[upcoming versions](https://github.com/opengeospatial/ogcapi-features). + +The OGC API - Features is a standard API that represents collections of geospatial data. It is the latest iteration of +that standard and defines the RESTful interface to query geospatial data, with GeoJSON as a main return type. With +OAFeat you can return any `Feature`, which is a geometry plus any number of properties. In the STAC specification an +`Item` is a `Feature`, with additional required fields for `datetime` and `assets`. OAFeat also defines the concept of +a Collection, which contains Features. A STAC `Collection` aligns with (and extends slightly) a OAFeat `Collection`; it +contains Items. + +In OAFeat Collections are the sets of data that can be queried +([7.11](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#_collections_)), and each describes basic information +about the geospatial dataset, like its name and description, as well as the spatial and temporal extents of all the data +contained. [STAC collections](../collection-spec/README.md) contain this same information, along with other STAC +specific fields and thus are compliant with both OAFeat Collections and STAC Collections and is returned from the +`/collections/{collection_id}` endpoint. + +In OAFeat Features are the individual records within a Collection and are provided in GeoJSON format. +[STAC Items](../item-spec/README.md) are analogous to OAFeat Features, are in GeoJSON, and are returned from the +`/collections/{collection_id}/items/{item_id}` endpoint. + +A typical OAFeat will have multiple collections, and each will just offer simple search for its particular collection at +`GET /collections/{collectionId}/items`. +The main STAC endpoint specified beyond what OAFeat offers is `/search`, which offers cross-collection search. A primary +use case of STAC is to search diverse imagery collections (like Landsat, Sentinel, MODIS) by location and cloud cover for any +relevant image. So the ability to do searches across Collections is required, and is not yet specified by OAFeat. Due to the +limited parameter support in OGC API - Features, it is recommended to use the STAC API endpoint +`POST /search` for advanced queries, as it supports richer options. +The filtering is made to be compatible between STAC API and OGC API - Features whenever feasible, and the two specs seek +to share the general query and filtering patterns, and STAC will align with OGC API when it offers advanced filtering. + +Implementations may **optionally** provide support for the full superset of STAC API query parameters to the +`/collections/{collectionId}/items` endpoint, +where the collection ID in the path is equivalent to providing that single value in the `collections` query parameter in +STAC API. -The OGC API - Features is a standard API that represents collections of geospatial data. It is the latest iteration of that standard and defines the RESTful interface to query geospatial data, with GeoJSON as a main return type. With OAFeat you can return any `Feature`, which is a geometry plus any number of properties. In the STAC specification an `Item` is a `Feature`, with additional required fields for `datetime` and `assets`. OAFeat also defines the concept of a Collection, which contains Features. A STAC `Collection` aligns with (and extends slightly) a OAFeat `Collection`; it contains Items. +## HTTP Request Methods and Content Types -In OAFeat Collections are the sets of data that can be queried ([7.11](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#_collections_)), and each describes basic information about the geospatial dataset, like its name and description, as well as the spatial and temporal extents of all the data contained. [STAC collections](../collection-spec/README.md) contain this same information, along with other STAC specific fields and thus are compliant with both OAFeat Collections and STAC Collections and is returned from the `/collections/{collection_id}` endpoint. +The OAFeat and STAC APIs follow a RESTful model. A core principal of this is the use of HTTP Request Methods ("verbs") and +the `Content-Type` header to drive behavior on resources ("nouns"). This section describes how these are used in the OAFeat and STAC endpoints. -In OAFeat Features are the individual records within a Collection and are provided in GeoJSON format. [STAC Items](../item-spec/README.md) are analogous to OAFeat Features, are in GeoJSON, and are returned from the `/collections/{collection_id}/items/{item_id}` endpoint. +#### GET -## HTTP Request Methods and Content Types +**Required**: OAFeat 1.0 only specifies GET query parameters, and they are all required. STAC's cross-collection `/search` also requires +GET queries for all implementations, and generally aligns with OAFeat's single Collection search. + +#### POST + +1. **Recommended** STAC `/search` is strongly recommended to implement POST `Content-Type: application/json`, where the content body is a JSON +object representing a query and filter, as defined in the [STAC API OpenAPI specification document](STAC.yaml). +2. **Prohibited** OAFeat: POST `Content-Type: application/json` on the `/collections/{collectionId}/items`, where the content body is a JSON +object representing a filter, is not allowed. This is prohibited due to conflict with the +[Transaction Extension](extensions/transaction/README.md), which defines a POST `Content-Type: application/json` +operation to create an Item. Any query against a single OAFeat collection endpoint should be possible against the STAC `/search` endpoint, specifying +the collection name in the `collections` query parameter. -The OAFeat and STAC APIs follow a RESTful model. A core principal of this is the use of HTTP Request Methods (verbs) and the `Content-Type` header to drive behavior. This section describes how these are used in the OAFeat and STAC endpoints. +It is recommended for clients use POST for querying (if the STAC API supports it), especially when using the +`intersects` query parameter, for two reasons: -1. **Required** GET (both OAFeat and STAC) -2. **Recommended** POST `Content-Type: application/x-www-form-urlencoded` with the corresponding content body format. -3. **Recommended** POST `Content-Type: multipart/form-data` with the corresponding content body format. -4. **Optional** **STAC endpoint /search only** POST `Content-Type: application/json`, where the content body is a JSON object representing a filter, as defined in the [STAC API OpenAPI specification document](STAC.yaml). -5. **Prohibited** **OAFeat endpoints only** POST `Content-Type: application/json`, where the content body is a JSON object representing a filter. This is prohibited due to conflict with the [Transaction Extension](extensions/transaction/README.md), which defines a POST `Content-Type: application/json` operation to create an Item. +1. In practice, the allowed size for an HTTP GET request is significantly less than that allowed for a POST request, +so if a large geometry is used in the query it may cause a GET request to fail. +2. The parameters for a GET request must be escaped properly, making it more difficult to construct when using JSON +parameters (such as intersect). + +**STAC API extensions** allow for more sophisticated searching, such as the ability to search by geometries and +searching on specific Item properties. + +#### PUT / PATCH / DELETE + +The other HTTP verbs are not supported in the core STAC specification. The [Transaction Extension](extensions/transaction/README.md) +does implement them, for STAC and OAFeat implementations that want to enable writing and deleting items. ## OGC API - Features Endpoints -The core OGC API - Features endpoints are shown below, with details provided in an [OpenAPI specification document](openapi/OAFeat.yaml). +The core OGC API - Features endpoints are shown below, with details provided in an +[OpenAPI specification document](openapi/OAFeat.yaml). | Endpoint | Returns | Description | | ------------ | ------------- | ----------- | @@ -32,22 +89,31 @@ The core OGC API - Features endpoints are shown below, with details provided in | /collections/{collectionId}/items/{featureId} | Item | Returns single Item (GeoJSON Feature) | The `/collections/{collection_id}/items` endpoint accepts parameters for filtering the results (also called filters). -Items in the collection should match all filters to be returned when querying. This implies a logical AND operation. If an OR operation is needed, it should be specified through an extension filter. +Items in the collection should match all filters to be returned when querying. This implies a logical AND operation. If +an OR operation is needed, it should be specified through an extension filter. ## STAC Endpoints -STAC provides some additional endpoints for the root Catalog itself, as well as the capability to search the Catalog. Note that a STAC API does not need to implement OAFeat, in which case it would only support the endpoints given below. See the [OpenAPI specification document](openapi/STAC.yaml). +STAC provides some additional endpoints for the root Catalog itself, as well as the capability to search the Catalog. +Note that a STAC API does not need to implement OAFeat, in which case it would only support the endpoints given below. +See the [OpenAPI specification document](openapi/STAC.yaml). | Endpoint | Returns | Description | | ------------- | ------- | ----------- | | / | Catalog | Extends `/` from OAFeat to return a full STAC catalog. | -| /search | [ItemCollection](../item-spec/itemcollection-spec.md) | Retrieves a group of Items matching the provided search predicates, probably containing search metadata from the `search` extension | +| /search | [ItemCollection](../item-spec/itemcollection-spec.md) | Retrieves a group of Items matching the +provided search predicates, probably containing search metadata from the `search` extension | -The `/` endpoint should function as a complete `Catalog` representation of all the data contained in the API and linked to in some way from root through `Collections` and `Items`. +The `/` endpoint should function as a complete `Catalog` representation of all the data contained in the API and linked +to in some way from root through `Collections` and `Items`. -The `/search` endpoint is similar to the `/collections/{collectionId}/items` endpoint in OGC API - Features in that it accepts parameters for filtering, however it performs the filtering across all collections. The parameters accepted are the same as the Filter Parameters above, however the *[extensions](extensions/README.md)* also provide advanced querying parameters. +The `/search` endpoint is similar to the `/collections/{collectionId}/items` endpoint in OGC API - Features in that it +accepts parameters for filtering, however it performs the filtering across all collections. The parameters accepted are +the same as the Filter Parameters above, however the *[extensions](extensions/README.md)* also provide advanced querying +parameters. -If the `/search` endpoint is implemented, it is **required** to add a link with the `rel` type set to `search` to the `links` array in `/` that refers to the search endpoint in the `href` property. +If the `/search` endpoint is implemented, it is **required** to add a link with the `rel` type set to `search` to the +`links` array in `/` that refers to the search endpoint in the `href` property. ## Filter Parameters and Fields @@ -104,3 +170,57 @@ All Extensions **should** use attribute names qualified from the root of Item, r | query | string \| QueryFilter | Placeholder parameter for [API Query Extension](extensions/query/README.md) query value. | **query** Represents a query in the query language. + +### Paging Extension + +OGC API supports paging through hypermedia links and STAC follows the same pattern for the cross collection search. For +GET requests, a link with `rel` type `next` is supplied. This link may contain any URL parameter that is necessary +for the implementation to understand how to provide the next page of results, eg: `page`, `next`, `token`, etc. The +parameter name is defined by the implementor and is not necessarily part of the API specification. For example: + +```json +{ + "type": "FeatureCollection", + "features": [], + "links": [ + { + "rel": "next", + "href": "http://api.cool-sat.com/search?page=2" + } + ] +} +``` + +The href may contain any arbitrary URL parameter: + +* `http://api.cool-sat.com/search?page=2` +* `http://api.cool-sat.com/search?next=8a35eba9c` +* `http://api.cool-sat.com/search?token=f32890a0bdb09ac3` + +OAFeat does not support POST requests for searches, however the STAC API spec does. Hypermedia links are not designed +for anything other than GET requests, so providing a next link for a POST search request becomes problematic. STAC has +decided to extend the `link` object to support additional fields that provide hints to the client as to how it should +execute a subsequent request for the next page of results. + +The following fields have been added to the `link` object specification for the API spec: + +| Parameter | Type | Description | +| --------- | ---------------- | ----------- | +| method | string | The HTTP method of the request, usually `GET` or `POST`. Defaults to `GET` | +| headers | object | A dictionary of header values that should be included in the next request | +| body | object | A JSON object containing fields/values that should be included in the body of the next request | +| merge | boolean | If `true`, the headers/body fields in the `next` link should be merged into the original request and be sent combined in the next request. Defaults to `false` | + +The implementor has the freedom to decide exactly how to apply these extended fields for their particular pagination +mechanism. The same freedom that exists for GET requests, where the actual URL parameter used to defined the next page +of results is purely up to the implementor and not defined in the API spec, if the implementor decides to use headers, +there are no specific or required header names defined in the specification. Implementors may use any names or fields +of their choosing. Pagination can be provided solely through header values, solely through body values, or through some +combination. + +To avoid returning the entire original request body in a POST response which may be arbitrarily large, the `merge` +property can be specified. This indicates that the client should send the same post body that it sent in the original +request, but with the specified headers/body values merged in. This allows servers to indicate what needs to change +to get to the next page without mirroring the entire query structure back to the client. + +Example requests can be found in the [examples document](./examples.md#paging). diff --git a/api-spec/examples.md b/api-spec/examples.md index a4b8c36b1..3ca3e3f6a 100644 --- a/api-spec/examples.md +++ b/api-spec/examples.md @@ -1,13 +1,5 @@ # STAC API Examples -A typical OAFeat will have multiple collections, and each will just offer simple search for its particular collection at `GET /collections/{collectionId}/items`. -Due to the limited parameter support in OGC API - Features, it is recommended to use the STAC API endpoint `POST /search` for advanced queries. -The filtering is made to be compatible between STAC API and OGC API - Features whenever feasible, and the two specs seek to share the general query and filtering patterns. -The key difference is that the STAC API search endpoints will do cross collection search. - -Implementations may **optionally** provide support for the full superset of STAC API query parameters to the `/collections/{collectionId}/items` endpoint, -where the collection ID in the path is equivalent to providing that single value in the `collections` query parameter in STAC API. - ## OGC API - Features (OAFeat) Note that the OAFeat endpoints _only_ supports HTTP GET. HTTP POST requests are not supported. @@ -38,14 +30,8 @@ GET /collections/mycollection/items?datetime=2019-01-01T00:00:00Z/2019-03-31T23: ## STAC API -A STAC API supports both GET and POST requests. It is best to use POST when using the intersects query for two reasons: - -1. the size limit for a GET request is less than that of POST, so if a complex geometry is used GET may fail. -2. The parameters for a GET request must be escaped properly, making it more difficult to construct when using JSON parameters (such as intersect) - -**STAC API extensions** allow for more sophisticated searching, such as the ability to search by geometries and searching on specific Item properties. - -Use the *[Query](extensions/query/README.md)* extension to search for any data falling within a specific geometry collected between Jan 1st and May 1st, 2019: +Use the *[Query](extensions/query/README.md)* extension to search for any data falling within a specific geometry +collected between Jan 1st and May 1st, 2019: ``` POST /search @@ -69,17 +55,15 @@ Body: ### Paging -OGC API supports paging through hypermedia links. STAC follows the same pattern for the cross collection search. However, there is one difference. STAC search supports POST and hypermedia links are not designed for anything other than GET. STAC has decided to extend the Link object to support hinting to the client what it should provide as headers and body content when following a hypermedia link. This allows the client to navigate to the next page via an HTTP POST or to use header based paging. - -In addition, to avoid passing large post body values to and from the server a "merge" property can be specified. This indicates that the client should send the same post body that it sent on the previous request, but with the specified body value merged on top. This allows servers to indicate what needs to change to get to the next page without mirroring the entire query structure back to the client. - -Simple GET based search just uses the standard next link: +#### Simple GET based search: +Request: ``` HTTP GET /search?bbox=-110,39.5,-105,40.5 ``` Response: ```json +200 OK { "type": "FeatureCollection", "features": [], @@ -91,11 +75,12 @@ Response: ] } ``` +Following the link http://api.cool-sat.com/search?page=2 will send the user to the next page of results. -For more complex post searches: +#### POST search with body and merge fields: +Request: ```json HTTP POST /search - { "bbox": [-110, 39.5, -105, 40.5] } @@ -122,7 +107,10 @@ Response: } ``` -This tells the client to post to the search endpoint with a body of: +This tells the client to POST to the search endpoint using the original request with the `page` and `limit` fields +merged in to obtain the next set of results: + +Request: ```json POST /search { @@ -132,23 +120,66 @@ POST /search } ``` -This can be even more effective when using continuation tokens on the server. +This can be even more effective when using continuation tokens on the server, as the entire request body need not be +repeated in the subsequent request: +Response: ```json +200 OK { "rel": "next", "href": "http://api.cool-sat.com/search", "method": "POST", "body": { - "next": "token" + "next": "a9f3kfbc98e29a0da23" } } ``` -The above link tells the client not to merge (default of false) so it is only required to pass the token. +The above link tells the client not to merge (default of false) so it is only required to pass the next token in the body. +Request: ```json POST /search { - "next": "token" + "next": "a9f3kfbc98e29a0da23" +} +``` + +#### POST search using headers: +Request: +```json +HTTP POST /search +{ + "bbox": [-110, 39.5, -105, 40.5], + "page": 2, + "limit": 10 +} +``` + +Response: +```json +200 OK +{ + "type": "FeatureCollection", + "features": [], + "links": [ + { + "rel": "next", + "href": "http://api.cool-sat.com/search", + "method": "POST", + "headers": { + "Search-After": "LC81530752019135LGN00" + } + } + ] } -``` \ No newline at end of file +``` + +This tells the client to POST to the search endpoint with the header `Search-After` to obtain the next set of results: + +Request: +```json +POST /search +Search-After: LC81530752019135LGN00 +``` + diff --git a/api-spec/extensions/sort/README.md b/api-spec/extensions/sort/README.md index e7056abe3..12c6f967c 100644 --- a/api-spec/extensions/sort/README.md +++ b/api-spec/extensions/sort/README.md @@ -2,27 +2,44 @@ **Extension [Maturity Classification](../../../extensions/README.md#extension-maturity): Pilot** -By default, the STAC search endpoint `/search` returns results in no specified order. Whatever order the results are in is up to the implementor, and will typically default to an arbitrary that is fastest for the underlying data store to retrieve results. +By default, the STAC search endpoint `/search` returns results in no specified order. Whatever order the results are in +is up to the implementor, and will typically default to an arbitrary order that is fastest for the underlying data store +to retrieve results. - The Sort API Extension adds a new parameter, `sortby`, that allows the user to define fields by which to sort results. Only string, numeric, and datetime attributes of Item (`id` and `collection` only) or Item Properties (any attributes) may be used to sort results. It is not required that implementations support sorting over all attributes, but implementations should return an error when attempting to sort over a field that does not support sorting. +The Sort API Extension adds a new parameter, `sortby`, that allows the user to define fields by which to sort results. +Only string, numeric, and datetime attributes of Item (`id` and `collection` only) or Item Properties (any attributes) +may be used to sort results. It is not required that implementations support sorting over all attributes, but +implementations should return an error when attempting to sort over a field that does not support sorting. -Two values for direction are supported: "asc" (ascending) or "desc" (descending). If the direction is not specified, the value is ascending. The `sortby` value is an array, so multiple sort fields can be defined which will be used to sort the data in the order provided (e.g., first by `datetime`, then by `eo:cloud_cover`). +Fields may be sorted in ascending or descending order. The syntax between GET requests and POST requests with a JSON +body vary. The `sortby` value is an array, so multiple sort fields can be defined which will be used to sort +the data in the order provided (e.g., first by `datetime`, then by `eo:cloud_cover`). -## GET or POST Form +## HTTP GET (or POST Form) -When calling `/search` using GET or POST with `Content-Type: application/x-www-form-urlencoded` or `Content-Type: multipart/form-data`, the semantics are the same, except the syntax is a single parameter `sortby` with a comma-separated list of "|" definitions. It is recommended that in implementations, direction be mandatory, and that an error should result from not specifying a direction. +When calling `/search` using GET (or POST with `Content-Type: application/x-www-form-urlencoded` or +`Content-Type: multipart/form-data)`, a single parameter `sortby` with a comma-separated list of item field names should +be provided. The field names may be prefixed with either "+" for ascending, or "-" for descending. If no sign is +provided before the field name, it will be assumed to be "+". Examples of `sortby` parameter: - GET /search?sortby=created|asc + 1. GET /search?sortby=properties.created - GET /search?sortby=created|asc,id|desc + 2. GET /search?sortby=+properties.created - GET /search?sortby=properties.eo:cloud_cover|desc - -# POST JSON Entity + 3. GET /search?sortby=properties.created,-id + + 4. GET /search?sortby=+properties.created,-id + + 5. GET /search?sortby=-properties.eo:cloud_cover + +Note that examples 1 and 2 are symantically equivalent, as well as examples 3 and 4. +ß +# HTTP POST JSON Entity -When calling `/search` using POST with`Content-Type: application/json`, this extension adds an attribute `sortby` with an object value to the core JSON search request body. +When calling `/search` using POST with`Content-Type: application/json`, this extension adds an attribute `sortby` with +an object value to the core JSON search request body. The syntax for the `sortby` attribute is: @@ -41,7 +58,7 @@ The syntax for the `sortby` attribute is: { "sortby": [ { - "field": "created", + "field": "properties.created", "direction": "asc" }, { diff --git a/api-spec/extensions/sort/sort.fragment.yaml b/api-spec/extensions/sort/sort.fragment.yaml index e0cf81b7b..3dee926e3 100644 --- a/api-spec/extensions/sort/sort.fragment.yaml +++ b/api-spec/extensions/sort/sort.fragment.yaml @@ -9,10 +9,13 @@ components: sortby: name: sortby in: query - description: Allows sorting results by the specified properties + description: |- + An array of property names, prefixed by either "+" for ascending or + "-" for descending. If no prefix is provided, "+" is assumed. required: false schema: type: string + example: '+id,-properties.eo:cloud_cover' style: form explode: false schemas: diff --git a/api-spec/extensions/transaction/transaction.fragment.yaml b/api-spec/extensions/transaction/transaction.fragment.yaml index 9c519c723..683ce974e 100644 --- a/api-spec/extensions/transaction/transaction.fragment.yaml +++ b/api-spec/extensions/transaction/transaction.fragment.yaml @@ -94,6 +94,8 @@ paths: $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' + '412': + $ref: '#/components/responses/PreconditionFailed' '5XX': $ref: '#/components/responses/InternalServerError' default: @@ -108,7 +110,7 @@ paths: patch: summary: update an existing feature by Id with a partial item definition description: >- - Use this method to update an existing feature. Requires a GeoJSON + Use this method to update an existing feature. Requires a GeoJSON fragement (containing the fields to be updated) be submitted. operationId: patchFeature tags: @@ -247,6 +249,12 @@ components: application/json: schema: $ref: '#/components/schemas/exception' + PreconditionFailed: + description: Some condition specified by the request could not be met in the server + content: + application/json: + schema: + $ref: '#/components/schemas/exception' InternalServerError: description: The request was syntactically and semantically valid, but an error occurred while trying to act upon it content: diff --git a/api-spec/extensions/version/version.fragment.yaml b/api-spec/extensions/version/version.fragment.yaml index df7df4143..4aca94286 100644 --- a/api-spec/extensions/version/version.fragment.yaml +++ b/api-spec/extensions/version/version.fragment.yaml @@ -57,6 +57,31 @@ paths: '200': $ref: '#/components/responses/Collections' components: + schemas: + catalogDefinition: + type: object + required: + - stac_version + - id + - description + - links + properties: + stac_version: + $ref: '#/components/schemas/stac_version' + stac_extensions: + $ref: '#/components/schemas/stac_extensions' + id: + description: identifier of the catalog used, for example, in URIs + type: string + title: + description: human readable title of the catalog + type: string + description: + $ref: '#/components/schemas/description' + links: + type: array + items: + $ref: "#/components/schemas/link" parameters: versionId: name: versionId diff --git a/api-spec/openapi/STAC.yaml b/api-spec/openapi/STAC.yaml index 34bad122a..577ed1693 100644 --- a/api-spec/openapi/STAC.yaml +++ b/api-spec/openapi/STAC.yaml @@ -1,7 +1,7 @@ openapi: 3.0.1 info: title: The SpatioTemporal Asset Catalog API - version: 0.9.0-rc1 + version: 0.9.0-rc2 description: >- This is an OpenAPI definition of the core SpatioTemporal Asset Catalog API specification. Any service that implements this endpoint to allow search of @@ -34,12 +34,17 @@ paths: /search: get: summary: Search STAC items with simple filtering. - description: >- + description: |- Retrieve Items matching filters. Intended as a shorthand API for simple queries. + This method is optional, but you MUST implement `POST /search` if you + want to implement this method. - This method is optional, but you MUST implement `POST /search` if you want to implement this method. + 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. operationId: getSearchSTAC tags: - STAC @@ -72,12 +77,14 @@ paths: type: string post: summary: Search STAC items with full-featured filtering. - description: >- + description: |- retrieve items matching filters. Intended as the standard, full-featured query API. - - This method is mandatory to implement if `GET /search` is implemented. If this endpoint is implemented on a server, it is required to add a link with `rel` set to `search` to the `links` array in `GET /` that refers to this endpoint. + This method is mandatory to implement if `GET /search` is implemented. + 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 /`. operationId: postSearchSTAC tags: - STAC @@ -111,9 +118,9 @@ components: ids: name: ids in: query - description: | - Array of Item ids to return. All other filter parameters that further restrict the number of - search results are ignored + description: |- + Array of Item ids to return. All other filter parameters that further + restrict the number of search results are ignored required: false schema: $ref: '#/components/schemas/ids' @@ -134,8 +141,9 @@ components: in: query description: |- Only features that have a geometry that intersects the bounding box are selected. - The bounding box is provided as four or six numbers, depending on whether the - coordinate reference system includes a vertical axis (height or depth): + The bounding box is provided as four or six numbers, depending on + whether the coordinate reference system includes a vertical axis (height + or depth): * Lower left corner, coordinate axis 1 * Lower left corner, coordinate axis 2 @@ -144,25 +152,28 @@ components: * Upper right corner, coordinate axis 2 * Maximum value, coordinate axis 3 (optional) - The coordinate reference system of the values is WGS 84 longitude/latitude - (http://www.opengis.net/def/crs/OGC/1.3/CRS84) unless a different coordinate - reference system is specified in the parameter `bbox-crs`. + The coordinate reference system of the values is WGS 84 + longitude/latitude (http://www.opengis.net/def/crs/OGC/1.3/CRS84) unless + a different coordinate reference system is specified in the parameter + `bbox-crs`. - For WGS 84 longitude/latitude the values are in most cases the sequence of - minimum longitude, minimum latitude, maximum longitude and maximum latitude. - However, in cases where the box spans the antimeridian the first value - (west-most box edge) is larger than the third value (east-most box edge). + For WGS 84 longitude/latitude the values are in most cases the sequence + of minimum longitude, minimum latitude, maximum longitude and maximum + latitude. However, in cases where the box spans the antimeridian the + first value (west-most box edge) is larger than the third value + (east-most box edge). If the vertical axis is included, the third and the sixth number are the bottom and the top of the 3-dimensional bounding box. - If a feature has multiple spatial geometry properties, it is the decision of the - server whether only a single spatial geometry property is used to determine - the extent or all relevant geometries. + If a feature has multiple spatial geometry properties, it is the + decision of the server whether only a single spatial geometry property + is used to determine the extent or all relevant geometries. - Example: The bounding box of the New Zealand Exclusive Economic Zone in WGS 84 - (from 160.6°E to 170°W and from 55.95°S to 25.89°S) would be represented in JSON - as `[160.6, -55.95, -170, -25.89]` and in a query as `bbox=160.6,-55.95,-170,-25.89`. + Example: The bounding box of the New Zealand Exclusive Economic Zone in + WGS 84 (from 160.6°E to 170°W and from 55.95°S to 25.89°S) would be + represented in JSON as `[160.6, -55.95, -170, -25.89]` and in a query as + `bbox=160.6,-55.95,-170,-25.89`. required: false schema: type: array @@ -183,12 +194,13 @@ components: Collections (path `/collections`, link relation `data`). - A link to the search endpoint (path `/search`, link relation - `search`) is **required** to be specified if the API implements `/search` + Links to the search endpoints (path `/search`, link relation `search`, + method `GET` or `POST`) are **required** to be specified if the API + implements `/search` for any of the specified HTTP methods. content: application/json: example: - stac_version: 0.9.0-rc1 + stac_version: 0.9.0-rc2 id: naip title: NAIP Imagery description: Catalog of NAIP Imagery. @@ -204,6 +216,14 @@ components: schema: $ref: '#/components/schemas/item' schemas: + description: + type: string + description: |- + Detailed multi-line description to fully explain the catalog or + collection. + + [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for rich + text representation. # This schema extends OAFeat.yaml#/components/schemas/collection to add and require additional fields and add an example. collection: type: object @@ -218,12 +238,7 @@ components: stac_extensions: $ref: '#/components/schemas/stac_extensions' description: - description: >- - Detailed multi-line description to fully explain the collection. - - - [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for rich - text representation. + $ref: '#/components/schemas/description' keywords: type: array description: List of keywords describing the collection. @@ -234,8 +249,18 @@ components: providers: $ref: '#/components/schemas/providers' summaries: - description: >- - Summaries are either a unique set of all available values *or* statistics. Statistics by default only specify the range (minimum and maximum values), but can optionally be accompanied by additional statistical values. The range can specify the potential range of values, but it is recommended to be as precise as possible. The set of values must contain at least one element and it is strongly recommended to list all values. It is recommended to list as many properties as reasonable so that consumers get a full overview of the Collection. Properties that are covered by the Collection specification (e.g. `providers` and `license`) may not be repeated in the summaries. + description: |- + Summaries are either a unique set of all available values *or* + statistics. Statistics by default only specify the range (minimum + and maximum values), but can optionally be accompanied by additional + statistical values. The range can specify the potential range of + values, but it is recommended to be as precise as possible. The set + of values must contain at least one element and it is strongly + recommended to list all values. It is recommended to list as many + properties as reasonable so that consumers get a full overview of + the Collection. Properties that are covered by the Collection + specification (e.g. `providers` and `license`) may not be repeated + in the summaries. type: object additionalProperties: oneOf: @@ -245,8 +270,14 @@ components: description: A value of any type. - type: object title: Statistics - description: >- - By default, only ranges with a minimum and a maximum value can be specified. Ranges can be specified for ordinal values only, which means they need to have a rank order. Therefore, ranges can only be specified for numbers and some special types of strings. Examples: grades (A to F), dates or times. Implementors are free to add other derived statistical values to the object, for example `mean` or `stddev`. + description: |- + By default, only ranges with a minimum and a maximum value can + be specified. Ranges can be specified for ordinal values only, + which means they need to have a rank order. Therefore, ranges + can only be specified for numbers and some special types of + strings. Examples: grades (A to F), dates or times. + Implementors are free to add other derived statistical values + to the object, for example `mean` or `stddev`. required: - min - max @@ -260,7 +291,7 @@ components: - type: string - type: number example: - stac_version: 0.9.0-rc1 + stac_version: 0.9.0-rc2 stac_extensions: [] id: Sentinel-2 title: 'Sentinel-2 MSI: MultiSpectral Instrument, Level-1C' @@ -309,10 +340,10 @@ components: - sentinel-2 'instruments': - msi - 'sat:off_nadir_angle': + 'view:off_nadir': min: 0 max: 100 - 'sat:sun_elevation_angle': + 'view:sun_elevation': min: 6.78 max: 89.9 'eo:bands': @@ -408,19 +439,26 @@ components: merge: type: boolean default: false - description: >- + description: |- This is only valid when the server is responding to POST request. - If merge is true, the client is expected to merge the body value into the current request body before following the link. - This avoids passing large post bodies back and forth when following links, particularly for navigating pages through the POST /search endpoint. + If merge is true, the client is expected to merge the body value + into the current request body before following the link. + This avoids passing large post bodies back and forth when following + links, particularly for navigating pages through the `POST /search` + endpoint. - NOTE: To support form encoding it is expected that a client be able to merge in the key value pairs specified as JSON - `{"next": "token"}` will become `&next=token` + NOTE: To support form encoding it is expected that a client be able + to merge in the key value pairs specified as JSON + `{"next": "token"}` will become `&next=token`. license: type: string - description: >- - License(s) of the data as a SPDX [License identifier](https://spdx.org/licenses/) or [expression](https://spdx.org/spdx-specification-21-web-version#h.jxpfx0ykyb60). Alternatively, use `proprietary` if the license is not on the SPDX license list or `various` if multiple licenses apply. In these two cases links to the license texts SHOULD be added, see the `license` link relation type. - + description: |- + License(s) of the data as a SPDX + [License identifier](https://spdx.org/licenses/). Alternatively, use + `proprietary` if the license is not on the SPDX license list or + `various` if multiple licenses apply. In these two cases links to the + license texts SHOULD be added, see the `license` link relation type. Non-SPDX licenses SHOULD add a link to the license text with the `license` relation in the links section. The license text MUST NOT be @@ -454,26 +492,22 @@ components: CommonMark 0.29 syntax MAY be used for rich text representation. type: string roles: - description: >- + description: |- Roles of the provider. - 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 license field. - + the license specified in the collection's license field. * producer: The producer of the data is the provider that - initially captured and processed the source data, e.g. ESA for - Sentinel-2 data. - + 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. - + 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. + storage. There should be no more than one host, specified as last + element of the list. type: array items: type: string @@ -538,9 +572,10 @@ components: decision of the server whether only a single spatial geometry property is used to determine the extent or all relevant geometries. - Example: The bounding box of the New Zealand Exclusive Economic Zone in WGS 84 - (from 160.6°E to 170°W and from 55.95°S to 25.89°S) would be represented in JSON - as `[160.6, -55.95, -170, -25.89]` and in a query as `bbox=160.6,-55.95,-170,-25.89`. + Example: The bounding box of the New Zealand Exclusive Economic Zone in + WGS 84 (from 160.6°E to 170°W and from 55.95°S to 25.89°S) would be + represented in JSON as `[160.6, -55.95, -170, -25.89]` and in a query as + `bbox=160.6,-55.95,-170,-25.89`. type: array minItems: 4 maxItems: 6 @@ -559,16 +594,16 @@ components: $ref: '#/components/schemas/bbox' collectionsArray: type: array - description: | + description: |- Array of Collection IDs to include in the search for items. - Only Items in one of the provided Collections will be searched + Only Items in one of the provided Collections will be searched. items: type: string ids: type: array - description: | - Array of Item ids to return. All other filter parameters that further restrict the number of - search results are ignored + description: |- + Array of Item ids to return. All other filter parameters that further + restrict the number of search results are ignored items: type: string datetimeFilter: @@ -605,8 +640,9 @@ components: datetime: type: string description: |- - Either a date-time or an interval, open or closed. Date and time expressions - adhere to RFC 3339. Open intervals are expressed using double-dots. + Either a date-time or an interval, open or closed. Date and time + expressions adhere to RFC 3339. Open intervals are expressed using + double-dots. Examples: @@ -624,7 +660,7 @@ components: stac_version: title: STAC version type: string - example: 0.9.0-rc1 + example: 0.9.0-rc2 stac_extensions: title: STAC extensions type: array @@ -701,9 +737,10 @@ components: assets: $ref: '#/components/schemas/itemAssets' example: - stac_version: 0.9.0-rc1 + stac_version: 0.9.0-rc2 stac_extensions: - eo + - view - 'https://example.com/cs-extension/1.0/schema.json' type: Feature id: CS3-20160503_132131_05 @@ -735,14 +772,14 @@ components: - producer - licensor url: 'https://cool-sat.com/' - 'sat:sun_azimuth_angle': 168.7 + 'view:sun_azimuth': 168.7 'eo:cloud_cover': 0.12 - 'sat:off_nadir_angle': 1.4 + 'view:off_nadir': 1.4 'platform': coolsat2 'instruments': - cool_sensor_v1 'eo:bands': [] - 'sat:sun_elevation_angle': 33.4 + 'view:sun_elevation': 33.4 'eo:gsd': 0.512 collection: CS3 links: @@ -787,6 +824,14 @@ components: type: string description: Displayed title example: Thumbnail + description: + type: string + description: |- + Multi-line description to explain the asset. + + [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for + rich text representation. + example: Small 256x256px PNG thumbnail for a preview. type: type: string description: Media type of the asset diff --git a/api-spec/package-lock.json b/api-spec/package-lock.json index c6c1d1ffc..3e1ea51fc 100644 --- a/api-spec/package-lock.json +++ b/api-spec/package-lock.json @@ -1,6 +1,6 @@ { "name": "api-spec", - "version": "0.9.0-rc1", + "version": "0.9.0-rc2", "lockfileVersion": 1, "requires": true, "dependencies": { diff --git a/api-spec/package.json b/api-spec/package.json index 30b058bdd..4161747fd 100644 --- a/api-spec/package.json +++ b/api-spec/package.json @@ -1,6 +1,6 @@ { "name": "api-spec", - "version": "0.9.0-rc1", + "version": "0.9.0-rc2", "description": "Generate STAC openapi defintions from fragments.", "repository": "https://github.com/radiantearth/stac-spec", "license": "Apache-2.0", diff --git a/catalog-spec/catalog-spec.md b/catalog-spec/catalog-spec.md index 5b98fb685..501dfc5b4 100644 --- a/catalog-spec/catalog-spec.md +++ b/catalog-spec/catalog-spec.md @@ -145,7 +145,7 @@ might look something like this: ```json { - "stac_version": "0.9.0-rc1", + "stac_version": "0.9.0-rc2", "id": "NAIP", "description": "Catalog of NAIP Imagery", "links": [ @@ -163,7 +163,7 @@ A typical '_child_' sub-catalog could look similar: ```json { - "stac_version": "0.9.0-rc1", + "stac_version": "0.9.0-rc2", "id": "NAIP", "description": "Catalog of NAIP Imagery - 30087", "links": [ diff --git a/catalog-spec/examples/catalog.json b/catalog-spec/examples/catalog.json index 9920f3f83..b9d3e5922 100644 --- a/catalog-spec/examples/catalog.json +++ b/catalog-spec/examples/catalog.json @@ -1,5 +1,5 @@ { - "stac_version": "0.9.0-rc1", + "stac_version": "0.9.0-rc2", "id": "sample", "description": "This is a very basic sample catalog.", "links": [ diff --git a/catalog-spec/json-schema/catalog.json b/catalog-spec/json-schema/catalog.json index f39a498b0..18cec5bf8 100644 --- a/catalog-spec/json-schema/catalog.json +++ b/catalog-spec/json-schema/catalog.json @@ -22,7 +22,7 @@ "stac_version": { "title": "STAC version", "type": "string", - "const": "0.9.0-rc1" + "const": "0.9.0-rc2" }, "stac_extensions": { "title": "STAC extensions", diff --git a/collection-spec/examples/landsat-collection.json b/collection-spec/examples/landsat-collection.json index 8e18ee857..0dd0ec39f 100644 --- a/collection-spec/examples/landsat-collection.json +++ b/collection-spec/examples/landsat-collection.json @@ -1,7 +1,9 @@ { - "stac_version": "0.9.0-rc1", + "stac_version": "0.9.0-rc2", "stac_extensions": [ - "commons" + "commons", + "view", + "eo" ], "id": "landsat-8-l1", "title": "Landsat 8 L1", @@ -62,7 +64,7 @@ "properties": { "platform": "landsat-8", "instruments": ["oli", "tirs"], - "sat:off_nadir_angle": 0, + "view:off_nadir": 0, "eo:gsd": 30, "eo:bands": [ { @@ -151,4 +153,4 @@ "href": "https://example.com/stac/collections/landsat-8-l1/items" } ] - } \ No newline at end of file + } diff --git a/collection-spec/examples/landsat-item.json b/collection-spec/examples/landsat-item.json index 000281f73..76d377b7f 100644 --- a/collection-spec/examples/landsat-item.json +++ b/collection-spec/examples/landsat-item.json @@ -1,8 +1,9 @@ { - "stac_version": "0.9.0-rc1", + "stac_version": "0.9.0-rc2", "stac_extensions": [ "commons", "eo", + "view", "https://example.com/stac/landsat-extension/1.0/schema.json" ], "id": "LC08_L1TP_107018_20181001_20181001_01_RT", @@ -44,8 +45,8 @@ "properties": { "datetime": "2018-10-01T01:08:32.033Z", "eo:cloud_cover": 78, - "sat:sun_azimuth_angle": 168.8989761, - "sat:sun_elevation_angle": 26.32596431, + "view:sun_azimuth": 168.8989761, + "view:sun_elevation": 26.32596431, "landsat:path": 107, "landsat:row": 18 }, @@ -177,4 +178,4 @@ "href": "https:///stac" } ] -} \ No newline at end of file +} diff --git a/collection-spec/examples/sentinel2.json b/collection-spec/examples/sentinel2.json index efe9e716f..cce11aec1 100644 --- a/collection-spec/examples/sentinel2.json +++ b/collection-spec/examples/sentinel2.json @@ -1,5 +1,5 @@ { - "stac_version": "0.9.0-rc1", + "stac_version": "0.9.0-rc2", "stac_extensions": [], "id": "COPERNICUS/S2", "title": "Sentinel-2 MSI: MultiSpectral Instrument, Level-1C", @@ -52,11 +52,11 @@ "platform": ["sentinel-2a","sentinel-2b"], "constellation": ["sentinel-2"], "instruments": ["msi"], - "sat:off_nadir_angle": { + "view:off_nadir": { "min": 0.0, "max": 100 }, - "sat:sun_elevation_angle": { + "view:sun_elevation": { "min": 6.78, "max": 89.9 }, @@ -144,4 +144,4 @@ "title": "Legal notice on the use of Copernicus Sentinel Data and Service Information" } ] -} \ No newline at end of file +} diff --git a/collection-spec/json-schema/collection.json b/collection-spec/json-schema/collection.json index 7f97368b2..5d512bfae 100644 --- a/collection-spec/json-schema/collection.json +++ b/collection-spec/json-schema/collection.json @@ -39,7 +39,9 @@ "asset", "commons", "checksum", - "scientific" + "datacube", + "scientific", + "version" ] } ] diff --git a/extensions/README.md b/extensions/README.md index a36c45f33..926c6e70e 100644 --- a/extensions/README.md +++ b/extensions/README.md @@ -60,6 +60,7 @@ An extension can add new fields to STAC entities (content extension), or can add | [Scientific](scientific/README.md) (`sci`) | Item, Collection | Scientific metadata is considered to be data that indicate from which publication data originates and how the data itself should be cited or referenced. | *Proposal* | | [Single File STAC](single-file-stac/README.md) (-) | ItemCollection | An extension to provide a set of Collections and Items as a single file catalog. | *Proposal* | | [Versioning Indicators](version/README.md) (-) | Item, Collection | Provides fields and link relation types to provide a version and indicate deprecation. | *Proposal* | +| [View Geometry](view/README.md) | Item | View Geometry adds metadata related to angles of sensors and other radiance angles that affect the view of resulting data | *Proposal* | ## Third-party / vendor extensions @@ -113,10 +114,10 @@ An example of this can be seen in a Landsat example: "start_datetime":"2018-01-01T13:21:30Z", "end_datetime":"2018-01-01T13:31:30Z", - "sat:off_nadir_angle": -0.001, + "view:off_nadir": -0.001, "eo:cloud_cover": 10.31, - "sat:sun_azimuth_angle": 149.01607154, - "sat:sun_elevation_angle": 59.21424700, + "view:sun_azimuth": 149.01607154, + "view:sun_elevation": 59.21424700, "eo:gsd": 30, "l8:data_type": "L1T", diff --git a/extensions/asset/README.md b/extensions/asset/README.md index 594af6506..4339799db 100644 --- a/extensions/asset/README.md +++ b/extensions/asset/README.md @@ -27,12 +27,12 @@ Additioanlly the remaining fields, `title` and `type` are required in the Asset An asset is an object that contains details about the datafiles that will be included in member Items. Assets included at the Collection level do not imply that all assets are available from all Items. However, it is recommended that the Asset Definition is a complete set of all assets that may be available from any member Items. -| Field Name | Type | Description | -| ----------- | ------ | ----------- | -| title | string | The displayed title for clients and users. | -| description | string | A description of the Asset providing additional details, such as how it was processed or created. | -| type | string | [Media type](../../item-spec/item-spec.md#media-types) of the asset. | -| roles | [string] | The semantic roles of the asset, similar to the use of `rel` in links. | +| Field Name | Type | Description | +| ----------- | -------- | ----------- | +| title | string | The displayed title for clients and users. | +| description | string | A description of the Asset providing additional details, such as how it was processed or created. [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for rich text representation. | +| type | string | [Media type](../../item-spec/item-spec.md#media-types) of the asset. | +| roles | [string] | The [semantic roles](../../item-spec/item-spec.md#asset-role-types) of the asset, similar to the use of `rel` in links. | Other custom fields, or fields from other extensions may also be included in the Asset object. diff --git a/extensions/asset/examples/example-landsat8.json b/extensions/asset/examples/example-landsat8.json index 03414efe7..96f916e5e 100644 --- a/extensions/asset/examples/example-landsat8.json +++ b/extensions/asset/examples/example-landsat8.json @@ -7,7 +7,7 @@ "earth observation", "usgs" ], - "stac_version": "0.9.0-rc1", + "stac_version": "0.9.0-rc2", "stac_extensions": [ "asset", "commons" @@ -70,7 +70,7 @@ "oli", "tirs" ], - "sat:off_nadir_angle": 0, + "view:off_nadir": 0, "eo:bands": [ { "name": "B1", @@ -243,4 +243,4 @@ }, "links": [] } -} \ No newline at end of file +} diff --git a/extensions/checksum/examples/sentinel1.json b/extensions/checksum/examples/sentinel1.json index 830d6c927..d32a04c48 100644 --- a/extensions/checksum/examples/sentinel1.json +++ b/extensions/checksum/examples/sentinel1.json @@ -1,7 +1,7 @@ { "id": "S1A_EW_GRDM_1SSH_20181103T235855_20181103T235955_024430_02AD5D_5616", "type": "Feature", - "stac_version": "0.9.0-rc1", + "stac_version": "0.9.0-rc2", "stac_extensions": [ "checksum" ], diff --git a/extensions/commons/README.md b/extensions/commons/README.md index a5973920d..3c81d288a 100644 --- a/extensions/commons/README.md +++ b/extensions/commons/README.md @@ -16,7 +16,7 @@ In **API implementations** the Commons extension should not be used as it leads Unlike other extensions the Commons extension does not add any fields to a STAC Item, instead it allows one to move fields out of Item and into the parent STAC Collection, from which any member Item will inherit. Any field under an Items `properties` field can be removed and added to the Collection `properties` field. Since a Collection contains no properties itself, anything under properties are metadata fields that are common across all member Items. -This provides maximum flexibility to data providers, as the set of common metadata fields can vary between different types of data. For instance, Landsat and Sentinel data always has a `sat:off_nadir_angle` value of `0`, because those satellites are always pointed downward (i.e., nadir), while satellite that can be pointed will have varying `sat:off_nadir_angle` values. The Commons extension allow the data provider to define the set of metadata that defines the collection. While some metadata fields are more likely to be part of the common set, such as or `instrument` rather than `eo:cloud_cover`, it depends on how the data provider chooses to organize their data. +This provides maximum flexibility to data providers, as the set of common metadata fields can vary between different types of data. For instance, Landsat and Sentinel data always has a `view:off_nadir` value of `0`, because those satellites are always pointed downward (i.e., nadir), while satellite that can be pointed will have varying `view:off_nadir` values. The Commons extension allow the data provider to define the set of metadata that defines the collection. While some metadata fields are more likely to be part of the common set, such as or `instrument` rather than `eo:cloud_cover`, it depends on how the data provider chooses to organize their data. If a metadata field is specified in the Collection properties, it will be ignored in any Item that links to that Collection. This is important because a Collection is the metadata that is common across all Item objects. If a field is variable at all, it should not be part of the Commons. @@ -44,7 +44,7 @@ To get the complete record of an Item (both individual and commons properties), An incomplete Collection: ``` { - "stac_version": "0.9.0-rc1", + "stac_version": "0.9.0-rc2", "stac_extensions": ["commons"], "id": "landsat-8-l1", "title": "Landsat 8 L1", @@ -56,7 +56,7 @@ An incomplete Collection: "constellation": "landsat-8", "instruments": ["oli", "tirs"], "eo:gsd": 30, - "sat:off_nadir_angle": 0, + "view:off_nadir": 0, "eo:bands": [ { "name": "B1", @@ -74,8 +74,8 @@ An incomplete Collection: An incomplete item: ``` { - "stac_version": "0.9.0-rc1", - "stac_extensions": ["commons", "eo", "sat"], + "stac_version": "0.9.0-rc2", + "stac_extensions": ["commons", "eo", "view"], "type": "Feature", "id": "LC08_L1TP_107018_20181001_20181001_01_RT", "bbox": [...], @@ -84,8 +84,8 @@ An incomplete item: "properties": { "datetime": "2018-10-01T01:08:32.033Z", "eo:cloud_cover": 78, - "sat:sun_azimuth_angle": 168.8989761, - "sat:sun_elevation_angle": 26.32596431 + "view:sun_azimuth": 168.8989761, + "view:sun_elevation": 26.32596431 }, "assets": {...}, "links": [...] @@ -96,8 +96,8 @@ The merged Item then looks like this: ``` { - "stac_version": "0.9.0-rc1", - "stac_extensions": ["eo", "sat"], + "stac_version": "0.9.0-rc2", + "stac_extensions": ["eo", "view"], "type": "Feature", "id": "LC08_L1TP_107018_20181001_20181001_01_RT", "bbox": [...], @@ -109,10 +109,10 @@ The merged Item then looks like this: "constellation": "landsat-8", "instruments": ["oli", "tirs"], "eo:cloud_cover": 78, - "sat:sun_azimuth_angle": 168.8989761, - "sat:sun_elevation_angle": 26.32596431, + "view:sun_azimuth": 168.8989761, + "view:sun_elevation": 26.32596431, "eo:gsd": 30, - "sat:off_nadir_angle": 0, + "view:off_nadir": 0, "eo:bands": [ { "name": "B1", @@ -130,4 +130,4 @@ The merged Item then looks like this: ## Implementations -[sat-api](https://github.com/sat-utils/sat-api/) has pioneered this functionality. You can see it in action at [https://sat-api.developmentseed.org/stac](https://sat-api.developmentseed.org/stac). \ No newline at end of file +[sat-api](https://github.com/sat-utils/sat-api/) has pioneered this functionality. You can see it in action at [https://sat-api.developmentseed.org/stac](https://sat-api.developmentseed.org/stac). diff --git a/extensions/commons/examples/landsat-collection.json b/extensions/commons/examples/landsat-collection.json index 7645cce15..145007e79 100644 --- a/extensions/commons/examples/landsat-collection.json +++ b/extensions/commons/examples/landsat-collection.json @@ -1,5 +1,5 @@ { - "stac_version": "0.9.0-rc1", + "stac_version": "0.9.0-rc2", "stac_extensions": [ "commons" ], @@ -63,7 +63,7 @@ "eo:gsd": 30, "platform": "landsat-8", "instruments": ["oli", "tirs"], - "sat:off_nadir_angle": 0, + "view:off_nadir": 0, "eo:bands": [ { "name": "B1", @@ -151,4 +151,4 @@ "href": "https://example.com/stac/collections/landsat-8-l1/items" } ] - } \ No newline at end of file + } diff --git a/extensions/commons/examples/landsat-item.json b/extensions/commons/examples/landsat-item.json index 50e03da60..87f73a265 100644 --- a/extensions/commons/examples/landsat-item.json +++ b/extensions/commons/examples/landsat-item.json @@ -1,5 +1,5 @@ { - "stac_version": "0.9.0-rc1", + "stac_version": "0.9.0-rc2", "stac_extensions": [ "commons", "eo", @@ -45,8 +45,8 @@ "properties": { "datetime": "2018-10-01T01:08:32.033Z", "eo:cloud_cover": 78, - "sat:sun_azimuth_angle": 168.8989761, - "sat:sun_elevation_angle": 26.32596431, + "view:sun_azimuth": 168.8989761, + "view:sun_elevation": 26.32596431, "landsat:path": 107, "landsat:row": 18 }, @@ -178,4 +178,4 @@ "href": "https:///stac" } ] -} \ No newline at end of file +} diff --git a/extensions/datacube/examples/example-collection.json b/extensions/datacube/examples/example-collection.json index abfb9726f..7373563a3 100644 --- a/extensions/datacube/examples/example-collection.json +++ b/extensions/datacube/examples/example-collection.json @@ -1,5 +1,5 @@ { - "stac_version": "0.9.0-rc1", + "stac_version": "0.9.0-rc2", "stac_extensions": [ "datacube" ], @@ -127,4 +127,4 @@ "title": "Legal notice on the use of Copernicus Sentinel Data and Service Information" } ] -} \ No newline at end of file +} diff --git a/extensions/datacube/examples/example-item.json b/extensions/datacube/examples/example-item.json index 72bdcd4cb..f573e869b 100644 --- a/extensions/datacube/examples/example-item.json +++ b/extensions/datacube/examples/example-item.json @@ -1,5 +1,5 @@ { - "stac_version": "0.9.0-rc1", + "stac_version": "0.9.0-rc2", "stac_extensions": [ "datacube" ], @@ -115,4 +115,4 @@ "href": "http://cool-sat.com/catalog/datacube-123/example-item.json" } ] -} \ No newline at end of file +} diff --git a/extensions/eo/README.md b/extensions/eo/README.md index ad7f59d76..f30a9ae73 100644 --- a/extensions/eo/README.md +++ b/extensions/eo/README.md @@ -20,6 +20,8 @@ It is not necessary, but recommended to use the [Commons extension](../commons/R If the data has been collected by a satellite, it is strongly recommended to use the [`sat` extension](../sat/README.md), which in turn requires the [Instrument Fields](../../item-spec/common-metadata.md#instrument). If the data has been collected on an airborne platform it is strongly recommended to use the [Instrument Fields](../../item-spec/common-metadata.md#instrument). +For defining view geometry of data, it is strongly recommended to use the [`view` extension](../view/README.md). + - [Example (Landsat 8)](examples/example-landsat8.json) - [JSON Schema](json-schema/schema.json) @@ -31,6 +33,9 @@ If the data has been collected by a satellite, it is strongly recommended to use | eo:bands | [[Band Object](#band-object)] | **REQUIRED.** This is a list of the available bands where each item is a [Band Object](#band-object). | | eo:cloud_cover | number | Estimate of cloud cover as a percentage (0-100) of the entire scene. If not available the field should not be provided. | + +### Ground Sampling Distance + **eo:gsd** is the nominal Ground Sample Distance for the data, as measured in meters on the ground. There are many definitions of GSD. The value of this attribute should be related to the spatial resolution at the sensor, rather than the pixel size of images after orthorectification, pansharpening, or scaling. @@ -96,7 +101,7 @@ Asset definitions that contain band data should reference the band index. Each a See [example-landsat8.json](examples/example-landsat8.json) for a full example. ``` { - "stac_version": "0.9.0-rc1", + "stac_version": "0.9.0-rc2", "stac_extensions": ["eo"], "id": "LC08_L1TP_107018_20181001_20181001_01_RT", "type": "Feature", @@ -152,7 +157,7 @@ Planet example: ``` { - "stac_version": "0.9.0-rc1", + "stac_version": "0.9.0-rc2", "stac_extensions": ["eo"], "id": "20171110_121030_1013", "type": "Feature", @@ -204,6 +209,7 @@ the eo:bands portion is still being fleshed out. The [extensions page](../README.md) gives an overview about related extensions. Of particular relevance to EO data: * the [Sat Extension Specification](../sat/README.md) to describe SAR data collected from a satellite. +* the [View Geometry Extension Specification](../view/README.md) to describe angles of sensors collecting earth observation data from above the earth. ### Placing common fields in Collections A lot of EO data will have common metadata across many Items. It is not necessary, but recommended diff --git a/extensions/eo/examples/example-landsat8.json b/extensions/eo/examples/example-landsat8.json index 741159c36..900b9bcd1 100644 --- a/extensions/eo/examples/example-landsat8.json +++ b/extensions/eo/examples/example-landsat8.json @@ -1,7 +1,8 @@ { - "stac_version": "0.9.0-rc1", + "stac_version": "0.9.0-rc2", "stac_extensions": [ "eo", + "view", "https://example.com/stac/landsat-extension/1.0/schema.json" ], "id": "LC08_L1TP_107018_20181001_20181001_01_RT", @@ -44,9 +45,9 @@ "platform": "landsat-8", "instrument": ["oli", "tirs"], "datetime": "2018-10-01T01:08:32.033Z", - "sat:sun_azimuth_angle": 168.8989761, - "sat:sun_elevation_angle": 26.32596431, - "sat:off_nadir_angle": 0, + "view:sun_azimuth": 168.8989761, + "view:sun_elevation": 26.32596431, + "view:off_nadir": 0, "landsat:path": 107, "landsat:row": 18, "eo:gsd": 30, diff --git a/extensions/label/examples/multidataset/catalog.json b/extensions/label/examples/multidataset/catalog.json index 3ca1d9409..bb7d520d6 100644 --- a/extensions/label/examples/multidataset/catalog.json +++ b/extensions/label/examples/multidataset/catalog.json @@ -2,7 +2,7 @@ "id": "label_extension_demo", "title": "label extension demo", "description": "Sample ML training data labels in the STAC format", - "stac_version": "0.9.0-rc1", + "stac_version": "0.9.0-rc2", "links": [ { diff --git a/extensions/label/examples/multidataset/spacenet-buildings/AOI_2_Vegas_img2636.json b/extensions/label/examples/multidataset/spacenet-buildings/AOI_2_Vegas_img2636.json index 93ee9ecea..32ab0beb3 100644 --- a/extensions/label/examples/multidataset/spacenet-buildings/AOI_2_Vegas_img2636.json +++ b/extensions/label/examples/multidataset/spacenet-buildings/AOI_2_Vegas_img2636.json @@ -1,5 +1,5 @@ { - "stac_version": "0.9.0-rc1", + "stac_version": "0.9.0-rc2", "stac_extensions": [ "label", "version" @@ -17,7 +17,7 @@ "coordinates": [ [ -115.23556259985658, - 36.12654269972625, + 36.12654269972625 ], [ -115.23556259985658, @@ -29,7 +29,7 @@ ], [ -115.23412932899998, - 36.12654269972625, + 36.12654269972625 ] ] }, diff --git a/extensions/label/examples/multidataset/spacenet-buildings/AOI_3_Paris_img1648.json b/extensions/label/examples/multidataset/spacenet-buildings/AOI_3_Paris_img1648.json index d9bc589a7..6fe3947d4 100644 --- a/extensions/label/examples/multidataset/spacenet-buildings/AOI_3_Paris_img1648.json +++ b/extensions/label/examples/multidataset/spacenet-buildings/AOI_3_Paris_img1648.json @@ -1,5 +1,5 @@ { - "stac_version": "0.9.0-rc1", + "stac_version": "0.9.0-rc2", "stac_extensions": [ "label", "version" diff --git a/extensions/label/examples/multidataset/spacenet-buildings/AOI_4_Shanghai_img3344.json b/extensions/label/examples/multidataset/spacenet-buildings/AOI_4_Shanghai_img3344.json index 729d8df98..00cedce17 100644 --- a/extensions/label/examples/multidataset/spacenet-buildings/AOI_4_Shanghai_img3344.json +++ b/extensions/label/examples/multidataset/spacenet-buildings/AOI_4_Shanghai_img3344.json @@ -1,5 +1,5 @@ { - "stac_version": "0.9.0-rc1", + "stac_version": "0.9.0-rc2", "stac_extensions": [ "label", "version" @@ -17,7 +17,7 @@ "coordinates": [ [ 121.66563419996653, - 31.234725900085653, + 31.234725900085653 ], [ 121.66563419996653, diff --git a/extensions/label/examples/multidataset/spacenet-buildings/collection.json b/extensions/label/examples/multidataset/spacenet-buildings/collection.json index 2adf7e119..7b921eb15 100644 --- a/extensions/label/examples/multidataset/spacenet-buildings/collection.json +++ b/extensions/label/examples/multidataset/spacenet-buildings/collection.json @@ -1,5 +1,5 @@ { - "stac_version": "0.9.0-rc1", + "stac_version": "0.9.0-rc2", "id": "spacenet-buildings-collection", "title": "spacenet-buildings AoI", "description": "Collection of training labels for spacenet-buildings", diff --git a/extensions/label/examples/multidataset/zanzibar/collection.json b/extensions/label/examples/multidataset/zanzibar/collection.json index d8cd9f1da..41a111171 100644 --- a/extensions/label/examples/multidataset/zanzibar/collection.json +++ b/extensions/label/examples/multidataset/zanzibar/collection.json @@ -1,5 +1,5 @@ { - "stac_version": "0.9.0-rc1", + "stac_version": "0.9.0-rc2", "id": "zanzibar-collection", "title": "zanzibar AoI", "description": "Collection of training labels for zanzibar", diff --git a/extensions/label/examples/multidataset/zanzibar/znz001.json b/extensions/label/examples/multidataset/zanzibar/znz001.json index 0ce2bc116..bc4a744f4 100644 --- a/extensions/label/examples/multidataset/zanzibar/znz001.json +++ b/extensions/label/examples/multidataset/zanzibar/znz001.json @@ -1,5 +1,5 @@ { - "stac_version": "0.9.0-rc1", + "stac_version": "0.9.0-rc2", "stac_extensions": [ "label", "version" @@ -17,7 +17,7 @@ "coordinates": [ [ 39.28919876472999, - -5.743028283012867, + -5.743028283012867 ], [ 39.31302874892266, @@ -31,6 +31,7 @@ 39.28919876472999, -5.722212794937691 ] + ] }, "assets": { "labels": { diff --git a/extensions/label/examples/multidataset/zanzibar/znz029.json b/extensions/label/examples/multidataset/zanzibar/znz029.json index d01c9508e..bfda5e80c 100644 --- a/extensions/label/examples/multidataset/zanzibar/znz029.json +++ b/extensions/label/examples/multidataset/zanzibar/znz029.json @@ -1,5 +1,5 @@ { - "stac_version": "0.9.0-rc1", + "stac_version": "0.9.0-rc2", "stac_extensions": [ "label", "version" diff --git a/extensions/label/examples/spacenet-roads/roads_collection.json b/extensions/label/examples/spacenet-roads/roads_collection.json index 6695e1cfa..6ac238d74 100644 --- a/extensions/label/examples/spacenet-roads/roads_collection.json +++ b/extensions/label/examples/spacenet-roads/roads_collection.json @@ -1,5 +1,5 @@ { - "stac_version": "0.9.0-rc1", + "stac_version": "0.9.0-rc2", "id": "spacenet-roads-sample", "description": "A sample of the SpaceNet Roads dataset built during STAC Sprint 4. The dataset contains hand-labeled roads.", "keywords": [ diff --git a/extensions/label/examples/spacenet-roads/roads_item.json b/extensions/label/examples/spacenet-roads/roads_item.json index c3c43b535..f77222028 100644 --- a/extensions/label/examples/spacenet-roads/roads_item.json +++ b/extensions/label/examples/spacenet-roads/roads_item.json @@ -1,5 +1,5 @@ { - "stac_version": "0.9.0-rc1", + "stac_version": "0.9.0-rc2", "stac_extensions": [ "label", "version" @@ -166,4 +166,4 @@ "type": "application/geo+json" } } -} \ No newline at end of file +} diff --git a/extensions/label/examples/spacenet-roads/roads_source.json b/extensions/label/examples/spacenet-roads/roads_source.json index 9f15b4fc3..a1ecd70e1 100644 --- a/extensions/label/examples/spacenet-roads/roads_source.json +++ b/extensions/label/examples/spacenet-roads/roads_source.json @@ -1,5 +1,5 @@ { - "stac_version": "0.9.0-rc1", + "stac_version": "0.9.0-rc2", "stac_extensions": [], "type": "Feature", "bbox": [2.23379639995, 49.0178709, 2.23730639995, 49.0213809], diff --git a/extensions/pointcloud/examples/example-autzen.json b/extensions/pointcloud/examples/example-autzen.json index 619e2b0c7..26ee44acf 100644 --- a/extensions/pointcloud/examples/example-autzen.json +++ b/extensions/pointcloud/examples/example-autzen.json @@ -1,5 +1,5 @@ { - "stac_version": "0.9.0-rc1", + "stac_version": "0.9.0-rc2", "stac_extensions": [ "pointcloud" ], @@ -299,4 +299,4 @@ "title": "USGS 3DEP LiDAR" }, "type": "Feature" -} \ No newline at end of file +} diff --git a/extensions/projection/examples/example-landsat8.json b/extensions/projection/examples/example-landsat8.json index b1b363183..81a9bb44d 100644 --- a/extensions/projection/examples/example-landsat8.json +++ b/extensions/projection/examples/example-landsat8.json @@ -1,5 +1,5 @@ { - "stac_version": "0.9.0-rc1", + "stac_version": "0.9.0-rc2", "stac_extensions": [ "eo", "proj" @@ -225,4 +225,4 @@ "href": "https://odu9mlf7d6.execute-api.us-east-1.amazonaws.com/stage/search?id=LC08_L1TP_107018_20181001_20181001_01_RT" } ] -} \ No newline at end of file +} diff --git a/extensions/sar/examples/envisat.json b/extensions/sar/examples/envisat.json index 04e00f3a9..1f60b2408 100644 --- a/extensions/sar/examples/envisat.json +++ b/extensions/sar/examples/envisat.json @@ -1,5 +1,5 @@ { - "stac_version": "0.9.0-rc1", + "stac_version": "0.9.0-rc2", "stac_extensions": [ "sat", "sar" @@ -61,4 +61,4 @@ "type": "text/html" } ] -} \ No newline at end of file +} diff --git a/extensions/sar/examples/sentinel1.json b/extensions/sar/examples/sentinel1.json index d75c04b06..496a2b387 100644 --- a/extensions/sar/examples/sentinel1.json +++ b/extensions/sar/examples/sentinel1.json @@ -1,5 +1,5 @@ { - "stac_version": "0.9.0-rc1", + "stac_version": "0.9.0-rc2", "stac_extensions": [ "checksum", "sar", @@ -28,7 +28,7 @@ "constellation": "sentinel-1", "instruments": ["c-sar"], "sat:orbit_state": "ascending", - "relative_orbit": 33, + "sat:relative_orbit": 33, "sar:instrument_mode": "EW", "sar:polarizations": ["HH"], "sar:resolution_range": 50, diff --git a/extensions/sat/README.md b/extensions/sat/README.md index 5a620666b..254f67104 100644 --- a/extensions/sat/README.md +++ b/extensions/sat/README.md @@ -2,7 +2,7 @@ **Extension [Maturity Classification](../README.md#extension-maturity): Proposal** -This document explains the fields of the Satellite Extension to a STAC Item. Sat adds metadata related to a satellite that carries an instrument for collecting data. It will often be combined with other extensions that describe the actual data, such as the `eo` or `sar` extensions. In many instances, satellite data will share common properties about the spacecraft across all of the Items. It is not necessary, but recommended to place common fields in [STAC Collections](../../collection-spec/collection-spec.md) using the [Commons extension](../commons/). +This document explains the fields of the Satellite Extension to a STAC Item. Sat adds metadata related to a satellite that carries an instrument for collecting data. It will often be combined with other extensions that describe the actual data, such as the `eo`, `os` or `sar` extensions. The Satellite extension requires the [Instrument Fields](../../item-spec/common-metadata.md#instrument). @@ -13,56 +13,17 @@ The Satellite extension requires the [Instrument Fields](../../item-spec/common- | Field Name | Type | Description | | ---------------- | ------------------------ | ----------- | -| sat:off_nadir_angle | number | The angle from the sensor between nadir (straight down) and the scene center. Measured in degrees (0-90). | -| sat:incidence_angle | number | The incidence angle is the angle between the vertical (normal) to the intercepting surface and the line of sight back to the satellite at the scene center. Measured in degrees (0-90). | -| sat:azimuth_angle | number | Viewing azimuth angle. The angle measured from the sub-satellite point (point on the ground below the platform) between the scene center and true north. Measured clockwise from north in degrees (0-360). | -| sat:sun_azimuth_angle | number | Sun azimuth angle. From the scene center point on the ground, this is the angle between truth north and the sun. Measured clockwise in degrees (0-360). | -| sat:sun_elevation_angle | number | Sun elevation angle. The angle from the tangent of the scene center point to the sun. Measured from the horizon in degrees (0-90). | -| sat:orbit_state | string | The state of the orbit. Either `ascending` or `descending` for polar orbiting satellites, or `geostationary` for geosynchronous satellites | -| sat:relative_orbit | integer | The relative orbit number at the time of acquisition. | +| sat:orbit_state | string | The state of the orbit. Either `ascending` or `descending` for polar orbiting satellites, or `geostationary` for geosynchronous satellites | +| sat:relative_orbit | integer | The relative orbit number at the time of acquisition. | **sat:orbit_state** indicates the type and current state of orbit. Satellites are either geosynchronous in which case they have one state: `geostationary`, or they are sun synchronous (i.e., polar orbiting satellites) in which case they are either `ascending` or `descending`. For sun synchronous satellites it is daytime during one of these states, and nighttime during the other. **sat:relative_orbit** is a count of orbits from 1 to the number of orbits contained in a repeat cycle, where relative orbit 1 starts from a specific reference location of the sub-satellite point (the point on the earth directly below the satellite). It resets to 1 when the sub-satellite point revisits the refernece location. -### Viewing and sun geometry - -The angles `off_nadir_angle`, `incidence_angle`, and `sun_elevation_angle` are angles measured on a 2d plane formed: satellite location, sub-satellite point on the earth, the sun, and the center of the viewed area. - -The off-nadir angle and the incidence angle are related. When the off-nadir angle is low (high incidence angle) then the two angles sum to about 90, so one can be calculated from the other. However, at high off-nadir angles with high altitude sensors the curvature of the earth has an impact and their sum will be less than 90. If only providing one of the two angles, the off-nadir angle is preferred. - -The angles `azimuth_angle` and `sun_azimuth_angle` indicate the position of the viewed scene and the sun by the angle from true north, as shown below. - - -Example: -``` -{ - "stac_version": "0.9.0-rc1", - "stac_extensions": [ - "sat" - ], - "id": "20171110", - "type": "Feature", - ... - "properties": { - "platform": "mysatellite", - "instruments": ["mycamera1", "mycamera2"], - "constellation": "allmysatellites", - "sat:off_nadir_angle": 0, - "sat:incidence_angle": 90, - "sat:sun_elevation_angle": 45.0, - "sat:azimuth_angle": 23.9, - "sat:sun_azimuth_angle": 56.4, - "sat:orbit_state": "descending", - "sat:relative_orbit": 4 - } -} -``` - ## Implementations - No implementations yet ## Extensions -The [extensions page](../README.md) gives an overview about related extensions. Of particular relevance to sat data. \ No newline at end of file +The [extensions page](../README.md) gives an overview about related extensions. Of particular relevance to sat data. diff --git a/extensions/sat/examples/example-landsat8.json b/extensions/sat/examples/example-landsat8.json index 58d140de9..53f1e35b9 100644 --- a/extensions/sat/examples/example-landsat8.json +++ b/extensions/sat/examples/example-landsat8.json @@ -1,7 +1,8 @@ { - "stac_version": "0.9.0-rc1", + "stac_version": "0.9.0-rc2", "stac_extensions": [ - "sat" + "sat", + "view" ], "id": "LC08_L1TP_107018_20181001", "collection": "landsat-8-l1", @@ -41,13 +42,13 @@ }, "properties": { "datetime": "2018-10-01T01:08:32.033Z", - "sat:sun_azimuth_angle": 168.8989761, - "sat:sun_elevation_angle": 26.32596431, + "view:sun_azimuth": 168.8989761, + "view:sun_elevation": 26.32596431, "platform": "landsat-8", "instruments": ["oli", "tirs"], "constellation": "landsat", "sat:orbit_state": "ascending", - "sat:off_nadir_angle": 0 + "view:off_nadir": 0 }, "assets": { "blue": { diff --git a/extensions/sat/json-schema/schema.json b/extensions/sat/json-schema/schema.json index 49b614dac..03da5a238 100644 --- a/extensions/sat/json-schema/schema.json +++ b/extensions/sat/json-schema/schema.json @@ -11,7 +11,7 @@ "$ref": "#/definitions/sat" }, { - "$ref": "../instrument/json-schema/schema.json" + "$ref": "../../../item-spec/json-schema/instrument.json" } ], "definitions": { @@ -25,36 +25,6 @@ "type": "object", "required": [], "properties": { - "sat:off_nadir_angle": { - "title": "Off Nadir", - "type": "number", - "minimum": 0, - "maximum": 90 - }, - "sat:incidence_angle": { - "title": "Center incidence angle", - "type": "number", - "minimum": 0, - "maximum": 90 - }, - "sat:azimuth_angle": { - "title": "Azimuth angle", - "type": "number", - "minimum": 0, - "maximum": 360 - }, - "sat:sun_azimuth_angle": { - "title": "Sun Azimuth angle", - "type": "number", - "minimum": 0, - "maximum": 360 - }, - "sat:sun_elevation_angle": { - "title": "Sun Elevation angle", - "type": "number", - "minimum": 0, - "maximum": 90 - }, "sat:relative_orbit": { "type": "integer", "minimum": 1 diff --git a/extensions/scientific/README.md b/extensions/scientific/README.md index 07f3c725e..b5257971e 100644 --- a/extensions/scientific/README.md +++ b/extensions/scientific/README.md @@ -12,8 +12,7 @@ can be registered at registration agencies affiliated with the This extension applies to STAC Items and STAC Collections. As these scientific information are often closely bound to the collection level and therefore are shared across all items, -it is recommended to use the [Commons extension](../commons/README.md) to add the fields to a corresponding -[STAC Collection](../../collection-spec/README.md). +it is recommended adding the fields to the corresponding [STAC Collection](../../collection-spec/README.md). - Examples: [Collection](examples/collection.json), [Item](examples/item.json) - [JSON Schema](json-schema/schema.json) diff --git a/extensions/scientific/examples/collection.json b/extensions/scientific/examples/collection.json index abc41d07d..c5e7c9e92 100644 --- a/extensions/scientific/examples/collection.json +++ b/extensions/scientific/examples/collection.json @@ -1,5 +1,5 @@ { - "stac_version": "0.9.0-rc1", + "stac_version": "0.9.0-rc2", "stac_extensions": ["scientific"], "id": "MERRAclim", "title": "MERRAclim, a high-resolution global dataset of remotely sensed bioclimatic variables for ecological modelling.", @@ -44,4 +44,4 @@ "href": "https://doi.org/10.1038/sdata.2017.78" } ] -} \ No newline at end of file +} diff --git a/extensions/scientific/examples/item.json b/extensions/scientific/examples/item.json index 86d75d10a..858378465 100644 --- a/extensions/scientific/examples/item.json +++ b/extensions/scientific/examples/item.json @@ -1,5 +1,5 @@ { - "stac_version": "0.9.0-rc1", + "stac_version": "0.9.0-rc2", "stac_extensions": [ "scientific", "checksum" diff --git a/extensions/single-file-stac/examples/example-search.json b/extensions/single-file-stac/examples/example-search.json index 2dd26e83c..17baf2ceb 100644 --- a/extensions/single-file-stac/examples/example-search.json +++ b/extensions/single-file-stac/examples/example-search.json @@ -40,8 +40,8 @@ }, "properties": { "datetime": "2018-02-08T18:02:15.719478+00:00", - "sat:sun_azimuth_angle": 152.63804142, - "sat:sun_elevation_angle": 31.82216637, + "view:sun_azimuth": 152.63804142, + "view:sun_elevation": 31.82216637, "eo:cloud_cover": 19, "eo:row": "033", "eo:column": "037", @@ -207,8 +207,8 @@ }, "properties": { "datetime": "2018-02-03T17:43:44.623405+00:00", - "sat:sun_azimuth_angle": 153.39513457, - "sat:sun_elevation_angle": 30.41894816, + "view:sun_azimuth": 153.39513457, + "view:sun_elevation": 30.41894816, "eo:cloud_cover": 36, "eo:row": "033", "eo:column": "034", @@ -346,7 +346,7 @@ "earth observation", "usgs" ], - "stac_version": "0.9.0-rc1", + "stac_version": "0.9.0-rc2", "extent": { "spatial": [ -180, @@ -394,7 +394,7 @@ "eo:gsd": 15, "platform": "landsat-8", "instruments": ["oli", "tirs"], - "sat:off_nadir_angle": 0, + "view:off_nadir": 0, "eo:bands": [ { "name": "B1", @@ -601,4 +601,4 @@ } } } -} \ No newline at end of file +} diff --git a/extensions/version/examples/collection.json b/extensions/version/examples/collection.json index 99dcad883..797d102cf 100644 --- a/extensions/version/examples/collection.json +++ b/extensions/version/examples/collection.json @@ -1,5 +1,5 @@ { - "stac_version": "0.9.0-rc1", + "stac_version": "0.9.0-rc2", "stac_extensions": ["version"], "id": "merraclim", "title": "MERRAclim", @@ -33,4 +33,4 @@ "href": "https://datadryad.org/resource/doi:10.5061/dryad.s2v81/v2/collection.json" } ] -} \ No newline at end of file +} diff --git a/extensions/version/examples/item.json b/extensions/version/examples/item.json index 08cbe7e5a..e4ce689ed 100644 --- a/extensions/version/examples/item.json +++ b/extensions/version/examples/item.json @@ -1,5 +1,5 @@ { - "stac_version": "0.9.0-rc1", + "stac_version": "0.9.0-rc2", "stac_extensions": [ "version" ], diff --git a/extensions/view/README.md b/extensions/view/README.md new file mode 100644 index 000000000..c3bb3fc0d --- /dev/null +++ b/extensions/view/README.md @@ -0,0 +1,59 @@ +# View Geometry Extension Specification (`view`) + +**Extension [Maturity Classification](../README.md#extension-maturity): Proposal** + +This document explains the fields of the View Geometry Extension to a STAC Item. View Geometry adds metadata related to angles of sensors and other radiance angles that affect the view of resulting data. It will often be combined with other extensions that describe the actual data, such as the `eo`, `sat` or `sar` extensions. + +- [Example (Landsat 8)](../eo/examples/example-landsat8.json) +- [JSON Schema](json-schema/schema.json) + +## Item fields + +| Field Name | Type | Description | +| ---------------- | ------------------------ | ----------- | +| view:off_nadir | number | The angle from the sensor between nadir (straight down) and the scene center. Measured in degrees (0-90). | +| view:incidence_angle | number | The incidence angle is the angle between the vertical (normal) to the intercepting surface and the line of sight back to the satellite at the scene center. Measured in degrees (0-90). | +| view:azimuth | number | Viewing azimuth angle. The angle measured from the sub-satellite point (point on the ground below the platform) between the scene center and true north. Measured clockwise from north in degrees (0-360). | +| view:sun_azimuth | number | Sun azimuth angle. From the scene center point on the ground, this is the angle between truth north and the sun. Measured clockwise in degrees (0-360). | +| view:sun_elevation | number | Sun elevation angle. The angle from the tangent of the scene center point to the sun. Measured from the horizon in degrees (0-90). | + +The angles `off_nadir`, `incidence_angle`, and `sun_elevation` are angles measured on a 2d plane formed: sensor location, sub-sensor point on the earth, the sun, and the center of the viewed area. + +The off-nadir angle and the incidence angle are related. When the off-nadir angle is low (high incidence angle) then the two angles sum to about 90, so one can be calculated from the other. However, at high off-nadir angles with high altitude sensors the curvature of the earth has an impact and their sum will be less than 90. If only providing one of the two angles, the off-nadir angle is preferred. + +The angles `azimuth` and `sun_azimuth` indicate the position of the viewed scene and the sun by the angle from true north, as shown below. + + +Example: +``` +{ + "stac_version": "0.9.0-rc2", + "stac_extensions": [ + "view", + "sat" + ], + "id": "20171110", + "type": "Feature", + ... + "properties": { + "platform": "mysatellite", + "instruments": ["mycamera1", "mycamera2"], + "constellation": "allmysatellites", + "view:off_nadir": 0, + "view:incidence_angle": 90, + "view:azimuth": 23.9, + "view:sun_elevation": 45.0, + "view:sun_azimuth": 56.4, + "sat:orbit_state": "descending", + "sat:relative_orbit": 4 + } +} +``` + +## Implementations + +- No implementations yet + +## Extensions + +The [extensions page](../README.md) gives an overview about related extensions. Of particular relevance to View Geometry data. \ No newline at end of file diff --git a/extensions/view/examples/example-landsat8.json b/extensions/view/examples/example-landsat8.json new file mode 100644 index 000000000..a387fc8b4 --- /dev/null +++ b/extensions/view/examples/example-landsat8.json @@ -0,0 +1,88 @@ +{ + "stac_version": "0.9.0-rc2", + "stac_extensions": [ + "sat", + "view" + ], + "id": "LC08_L1TP_107018_20181001", + "collection": "landsat-8-l1", + "type": "Feature", + "bbox": [ + 148.13933, + 59.51584, + 152.52758, + 60.63437 + ], + "geometry": { + "type": "Polygon", + "coordinates": [ + [ + [ + 152.52758, + 60.63437 + ], + [ + 149.1755, + 61.19016 + ], + [ + 148.13933, + 59.51584 + ], + [ + 151.33786, + 58.97792 + ], + [ + 152.52758, + 60.63437 + ] + ] + ] + }, + "properties": { + "datetime": "2018-10-01T01:08:32.033Z", + "view:sun_azimuth": 168.8989761, + "view:sun_elevation": 26.32596431, + "view:off_nadir": 0, + "view:incidence_angle": 0, + "view:azimuth": 23.4, + "platform": "landsat-8", + "instruments": ["oli", "tirs"], + "constellation": "landsat", + "sat:orbit_state": "ascending" + }, + "assets": { + "blue": { + "href": "https://landsat-pds.s3.amazonaws.com/c1/L8/107/018/LC08_L1TP_107018_20181001_20181001_01_RT/LC08_L1TP_107018_20181001_20181001_01_RT_B2.TIF", + "type": "image/tiff; application=geotiff", + "title": "Band 2 (blue)" + }, + "green": { + "href": "https://landsat-pds.s3.amazonaws.com/c1/L8/107/018/LC08_L1TP_107018_20181001_20181001_01_RT/LC08_L1TP_107018_20181001_20181001_01_RT_B3.TIF", + "type": "image/tiff; application=geotiff", + "title": "Band 3 (green)" + }, + "red": { + "href": "https://landsat-pds.s3.amazonaws.com/c1/L8/107/018/LC08_L1TP_107018_20181001_20181001_01_RT/LC08_L1TP_107018_20181001_20181001_01_RT_B4.TIF", + "type": "image/tiff; application=geotiff", + "title": "Band 4 (red)" + }, + "thumbnail": { + "href": "https://landsat-pds.s3.amazonaws.com/c1/L8/107/018/LC08_L1TP_107018_20181001_20181001_01_RT/LC08_L1TP_107018_20181001_20181001_01_RT_thumb_large.jpg", + "title": "Thumbnail image", + "type": "image/jpeg" + }, + "index": { + "href": "https://landsat-pds.s3.amazonaws.com/c1/L8/107/018/LC08_L1TP_107018_20181001_20181001_01_RT/index.html", + "type": "text/html", + "title": "HTML index page" + } + }, + "links": [ + { + "rel": "collection", + "href": "http://landsat-stac.s3.amazonaws.com/landsat-8-l1/catalog.json" + } + ] +} diff --git a/extensions/view/json-schema/schema.json b/extensions/view/json-schema/schema.json new file mode 100644 index 000000000..7bba8abda --- /dev/null +++ b/extensions/view/json-schema/schema.json @@ -0,0 +1,60 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "schema.json#", + "title": "View Geometry Extension", + "description": "STAC View Geometry Extension to a STAC Item.", + "allOf": [ + { + "$ref": "../../../item-spec/json-schema/item.json" + }, + { + "$ref": "#/definitions/view" + } + ], + "definitions": { + "view": { + "type": "object", + "required": [ + "properties" + ], + "properties": { + "properties": { + "type": "object", + "required": [], + "properties": { + "view:off_nadir": { + "title": "Off Nadir", + "type": "number", + "minimum": 0, + "maximum": 90 + }, + "view:incidence_angle": { + "title": "Center incidence angle", + "type": "number", + "minimum": 0, + "maximum": 90 + }, + "view:azimuth": { + "title": "Azimuth angle", + "type": "number", + "minimum": 0, + "maximum": 360 + }, + "view:sun_azimuth": { + "title": "Sun Azimuth", + "type": "number", + "minimum": 0, + "maximum": 360 + }, + "view:sun_elevation": { + "title": "Sun Elevation", + "type": "number", + "minimum": 0, + "maximum": 90 + } + } + } + } + } + } +} \ No newline at end of file diff --git a/implementations.md b/implementations.md index c6b58e289..58a88d556 100644 --- a/implementations.md +++ b/implementations.md @@ -83,6 +83,16 @@ of the spec. - Examples: https://github.com/TDG-Platform/dg-stac/tree/master/examples ## API (Active Catalog) Examples + +### Radiant MLHub (0.8) + +Radiant MLHub is an implementation of the STAC API which hosts datasets for training machine learning algorithms. Authentication is required for this API and an access token can be acquired by visiting the [dashboard](https://dashboard.mlhub.earth). + +* Dashboard: https://dashboard.mlhub.earth +* API Endpoint: https://api.radiant.earth/mlhub/v1/ +* Documentation: http://docs.mlhub.earth +* Tutorials: https://github.com/radiantearth/mlhub-tutorials + ### Boundless STAC Server (0.6) * Search endpoint: https://stac.boundlessgeo.io/search/stac diff --git a/item-spec/common-metadata.md b/item-spec/common-metadata.md index d7ee28319..d6a28617a 100644 --- a/item-spec/common-metadata.md +++ b/item-spec/common-metadata.md @@ -1,5 +1,8 @@ # STAC Common Metadata +This document outlines all commonly used fields for STAC Item properties. These fields are +included by default in the core [Item schema](json-schema/item.json) but implementation is not required. +* [Basics](#basics) * [Date and Time](#date-and-time) * [Licensing](#licensing) * [Provider](#provider) @@ -9,6 +12,18 @@ Various *examples* are available in the folder [`examples`](examples/). *JSON Schemas* can be found in the folder [`json-schema`](json-schema/). +## Basics + +Descriptive fields to give a basic overview of a STAC Item. + +- [JSON Schema](json-schema/basics.json) + +| Field Name | Type | Description | +| ----------- | ------ | ------------------------------------------------------------ | +| title | string | A human readable title describing the Item. | +| description | string | Detailed multi-line description to fully explain the Item. [CommonMark 0.29](https://commonmark.org/) syntax MAY be used for rich text representation. | + + ## Date and Time Fields to provide additional temporal information such as ranges with a start and an end datetime stamp. @@ -17,7 +32,7 @@ Fields to provide additional temporal information such as ranges with a start an - [JSON Schema](json-schema/datetimerange.json) -While a STAC item can have a nominal datetime describing the capture, this extension allows an item to have a range +While a STAC item can have a nominal datetime describing the capture, these properties allow an item to have a range of capture datetimes. An example of this is the [MODIS 16 day vegetation index product.](https://lpdaac.usgs.gov/products/mod13q1v006/). The datetime property in a STAC item and these fields are not mutually exclusive. @@ -85,8 +100,8 @@ The object provides information about a provider. A provider is any of the organ ## Instrument -Adds metadata specifying a platform and instrument used in a data collection mission. It will often be combined with -other extensions that describe the actual data, such as the `eo` or `sar` extensions. +Adds metadata specifying a platform and instrument used in a data collection mission. These fields will often be combined +with domain-specific extensions that describe the actual data, such as the `eo` or `sar` extensions. - [JSON Schema](json-schema/instrument.json) @@ -133,4 +148,4 @@ Fields to describe the metadata file itself. These fields do NOT describe the as | Field Name | Type | Description | | ---------- | ------ | ----------- | | created | string | Creation date and time of the metadata file. This is NOT the timestamp the asset was created. MUST be formatted according to [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6). | -| updated | string | Date and time the metadata file was updated last. This is NOT the timestamp the asset was updated last. MUST be formatted according to [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6). | \ No newline at end of file +| updated | string | Date and time the metadata file was updated last. This is NOT the timestamp the asset was updated last. MUST be formatted according to [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6). | diff --git a/item-spec/examples/CBERS_4_MUX_20181029_177_106_L4.json b/item-spec/examples/CBERS_4_MUX_20181029_177_106_L4.json index e89b67743..84a025b11 100755 --- a/item-spec/examples/CBERS_4_MUX_20181029_177_106_L4.json +++ b/item-spec/examples/CBERS_4_MUX_20181029_177_106_L4.json @@ -1,8 +1,9 @@ { - "stac_version": "0.9.0-rc1", + "stac_version": "0.9.0-rc2", "stac_extensions": [ "eo", "proj", + "view", "https://example.com/stac/cbers-extension/1.0/schema.json" ], "id": "CBERS_4_MUX_20181029_177_106_L4", @@ -44,9 +45,9 @@ ], "properties": { "datetime": "2018-10-29T14:24:54Z", - "sat:sun_azimuth_angle": 111.113, - "sat:sun_elevation_angle": 65.8018, - "sat:off_nadir_angle": -0.00751271, + "view:sun_azimuth": 111.113, + "view:sun_elevation": 65.8018, + "view:off_nadir": -0.00751271, "proj:epsg": 32763, "cbers:data_type": "L4", "cbers:path": 177, @@ -108,4 +109,4 @@ ] } } -} \ No newline at end of file +} diff --git a/item-spec/examples/datetimerange.json b/item-spec/examples/datetimerange.json index c4da2d568..f07184f9d 100644 --- a/item-spec/examples/datetimerange.json +++ b/item-spec/examples/datetimerange.json @@ -1,5 +1,5 @@ { - "stac_version": "0.9.0-rc1", + "stac_version": "0.9.0-rc2", "stac_extensions": [], "type":"Feature", "id":"half-moon-bay/video-2018-01-01-0001", @@ -59,4 +59,4 @@ "title":"Thumbnail" } } -} \ No newline at end of file +} diff --git a/item-spec/examples/digitalglobe-sample.json b/item-spec/examples/digitalglobe-sample.json index 0e7f1c589..b7d04489d 100644 --- a/item-spec/examples/digitalglobe-sample.json +++ b/item-spec/examples/digitalglobe-sample.json @@ -1,8 +1,9 @@ { - "stac_version": "0.9.0-rc1", + "stac_version": "0.9.0-rc2", "stac_extensions": [ "eo", "proj", + "view", "https://example.digitalglobe.com/stac/1.0/schema.json" ], "id": "103001004B316600_P002_MUL", @@ -71,12 +72,12 @@ "DigitalGlobeProduct", "1BProduct" ], - "sat:sun_azimuth_angle": 168.7, + "view:sun_azimuth": 168.7, "eo:cloud_cover": 50, - "sat:off_nadir_angle": 18.4, - "sat:azimuth_angle": 34.5, + "view:off_nadir": 18.4, + "view:azimuth": 34.5, "platform": "worldview02", - "sat:sun_elevation_angle": 33.4, + "view:sun_elevation": 33.4, "eo:gsd": 2.047, "proj:epsg": null, "dg:catalog_id": "103001004B316600", diff --git a/item-spec/examples/itemcollection-sample-full.json b/item-spec/examples/itemcollection-sample-full.json index 7cc6fb797..641e9bc4e 100644 --- a/item-spec/examples/itemcollection-sample-full.json +++ b/item-spec/examples/itemcollection-sample-full.json @@ -1,10 +1,10 @@ { - "stac_version": "0.9.0-rc1", + "stac_version": "0.9.0-rc2", "stac_extensions": [], "type": "FeatureCollection", "features": [ { - "stac_version": "0.9.0-rc1", + "stac_version": "0.9.0-rc2", "stac_extensions": [], "type": "Feature", "id": "CS3-20160503_132131_05", @@ -86,4 +86,4 @@ "href": "http://stac.example.com/search?collection=CS3" } ] -} \ No newline at end of file +} diff --git a/item-spec/examples/itemcollection-sample-minimal.json b/item-spec/examples/itemcollection-sample-minimal.json index d2717f1b6..0005766cc 100644 --- a/item-spec/examples/itemcollection-sample-minimal.json +++ b/item-spec/examples/itemcollection-sample-minimal.json @@ -1,6 +1,6 @@ { - "stac_version": "0.9.0-rc1", + "stac_version": "0.9.0-rc2", "stac_extensions": [], "type": "FeatureCollection", "features": [] -} \ No newline at end of file +} diff --git a/item-spec/examples/landsat8-sample.json b/item-spec/examples/landsat8-sample.json index acbf18303..e941ee0c7 100644 --- a/item-spec/examples/landsat8-sample.json +++ b/item-spec/examples/landsat8-sample.json @@ -1,7 +1,8 @@ { - "stac_version": "0.9.0-rc1", + "stac_version": "0.9.0-rc2", "stac_extensions": [ "eo", + "view", "https://example.com/stac/landsat-extension/1.0/schema.json" ], "id": "LC81530252014153LGN00", @@ -40,10 +41,10 @@ "collection": "L1T", "eo:gsd": 30.0, "eo:cloud_cover" : 10, - "sat:off_nadir_angle" : 0.000, - "sat:azimuth_angle": 0.00, - "sat:sun_azimuth_angle" : 149.01607154, - "sat:sun_elevation_angle" : 59.21424700, + "view:off_nadir" : 0.000, + "view:azimuth": 0.00, + "view:sun_azimuth" : 149.01607154, + "view:sun_elevation" : 59.21424700, "landsat:wrs_path": 153, "landsat:wrs_row": 25, "landsat:earth_sun_distance": 1.0141560, @@ -75,7 +76,6 @@ "metadata": { "href": "http://landsat-pds.s3.amazonaws.com/L8/153/025/LC81530252014153LGN00/LC81530252014153LGN00_MTL.txt", "type": "mtl", - "role": "metadata", "title": "Original Metadata", "description": "The original MTL metadata file provided for each Landsat scene", "roles": ["metadata"] diff --git a/item-spec/examples/planet-sample.json b/item-spec/examples/planet-sample.json index c850ed208..d33a87c9d 100644 --- a/item-spec/examples/planet-sample.json +++ b/item-spec/examples/planet-sample.json @@ -1,7 +1,8 @@ { - "stac_version": "0.9.0-rc1", + "stac_version": "0.9.0-rc2", "stac_extensions": [ "eo", + "view", "https://example.planet.com/stac/1.0/schema.json" ], "links": [ @@ -62,9 +63,9 @@ "datetime": "2017-11-10T12:10:30.535417Z", "eo:cloud_cover": 23, "eo:gsd": 3.7, - "sat:sun_azimuth_angle": 101.8, - "sat:sun_elevation_angle": 58.8, - "sat:off_nadir_angle": 1, + "view:sun_azimuth": 101.8, + "view:sun_elevation": 58.8, + "view:off_nadir": 1, "pl:acquired": "2017-11-10T12:10:30.535417Z", "pl:anomalous_pixels": 0.14, "pl:columns": 9111, @@ -130,4 +131,4 @@ } } -} \ No newline at end of file +} diff --git a/item-spec/examples/sample-full.json b/item-spec/examples/sample-full.json index 7bea47ada..f1586df91 100644 --- a/item-spec/examples/sample-full.json +++ b/item-spec/examples/sample-full.json @@ -1,7 +1,8 @@ { - "stac_version": "0.9.0-rc1", + "stac_version": "0.9.0-rc2", "stac_extensions": [ "eo", + "view", "https://example.com/cs-extension/1.0/schema.json" ], "type": "Feature", @@ -35,13 +36,13 @@ ], "created": "2016-05-04T00:00:01Z", "updated": "2017-01-01T00:30:55Z", - "sat:sun_azimuth_angle": 168.7, + "view:sun_azimuth": 168.7, "eo:cloud_cover": 0.12, - "sat:off_nadir_angle": 1.4, + "view:off_nadir": 1.4, "platform": "coolsat2", "instruments": ["cool_sensor_v1"], "eo:bands": [], - "sat:sun_elevation_angle": 33.4, + "view:sun_elevation": 33.4, "eo:gsd": 0.512, "cs:type": "scene", "cs:anomalous_pixels": 0.14, diff --git a/item-spec/examples/sample.json b/item-spec/examples/sample.json index f5c60976f..73839ddcd 100644 --- a/item-spec/examples/sample.json +++ b/item-spec/examples/sample.json @@ -1,5 +1,5 @@ { - "stac_version": "0.9.0-rc1", + "stac_version": "0.9.0-rc2", "stac_extensions": [], "type": "Feature", "id": "CS3-20160503_132130_04", @@ -41,4 +41,4 @@ "roles": [ "thumbnail" ] } } -} \ No newline at end of file +} diff --git a/item-spec/examples/sentinel2-sample.json b/item-spec/examples/sentinel2-sample.json index b14a527e5..6bc22b4c5 100644 --- a/item-spec/examples/sentinel2-sample.json +++ b/item-spec/examples/sentinel2-sample.json @@ -1,7 +1,8 @@ { - "stac_version": "0.9.0-rc1", + "stac_version": "0.9.0-rc2", "stac_extensions": [ "eo", + "view", "proj" ], "type": "Feature", @@ -304,6 +305,6 @@ "platform": "sentinel-2", "proj:epsg": 32635, "eo:cloud_cover": 88.459539, - "sat:sun_azimuth_angle" : 176.091667178268 + "view:sun_azimuth" : 176.091667178268 } } diff --git a/item-spec/item-spec.md b/item-spec/item-spec.md index cccce45c9..7369db060 100644 --- a/item-spec/item-spec.md +++ b/item-spec/item-spec.md @@ -66,17 +66,13 @@ Items that are linked to, but the best practices around this are still emerging. ### Properties Object -The Properties object adds additional metadata to the GeoJSON Object. Additional fields can be introduced through -extensions. It is generally allowed to add custom fields. - -It is recommended to add multiple attributes for related values instead of a nested object, e.g., two fields `eo:cloud_cover` and `sat:sun_azimuth_angle` instead of a field `eo` with an object value containing the two fields. The convention (as used within Extensions) is for related attributes to use a common prefix on the attribute names to group them, e.g. `eo`. A nested data structure should only be used when the data itself is nested, as with `eo:bands`. +Additional metadata fields can be added to the GeoJSON Object Properties. The only required field +is `datetime` but it is recommended to add more fields, see [Additional Fields](#additional-fields) +resources below. | Field Name | Type | Description | | ---------- | ------ | ------------------------------------------------------------ | | datetime | string | **REQUIRED.** The searchable date and time of the assets, in UTC. It is formatted according to [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6). | -| title | string | A human readable title describing the item. | - -**For more fields see the [STAC Common Metadata](common-metadata.md) and the [Content Extensions](../extensions/README.md#list-of-content-extensions).** **datetime** is likely the acquisition (in the case of single camera type captures) or the 'nominal' or representative time in the case of assets that are combined together. Though time can be a @@ -85,6 +81,18 @@ data, so use whatever single date and time is most useful for a user to search f extensions may further specify the meaning of the main `datetime` field, and many will also add more datetime fields. +#### Additional Fields +* [STAC Common Metadata](common-metadata.md#stac-common-metadata) - A list of fields commonly used +throughout all domains. These optional fields are included for STAC Items by default. +* [Content Extensions](../extensions/README.md#list-of-content-extensions) - Domain-specific fields +such as EO, SAR and point clouds. +* [Custom Extensions](../extensions/README.md#extending-stac) - It is generally allowed to add custom +fields but it is recommended to add multiple attributes for related values instead of a nested object, +e.g., two fields `eo:cloud_cover` and `eo:gsd` instead of a field `eo` with an object +value containing the two fields. The convention (as used within Extensions) is for related attributes +to use a common prefix on the attribute names to group them, e.g. `eo`. A nested data structure should +only be used when the data itself is nested, as with `eo:bands`. + ### Link Object This object describes a relationship with another entity. Data providers are advised to be liberal @@ -105,7 +113,7 @@ Currently, the JSON schema for links does not require them to be formatted as UR implementors to provide relative links. In general, Catalog APIs should aim to provide absolute links whenever possible. Static Catalogs are potentially more portable if they incorporate only relative links, so that every link doesn't need to be rewritten when the data is copied. Additional -recommendations for particular ```rel``` types are given in the ```rel``` type description. +recommendations for particular `rel` types are given in the `rel` type description. #### Relation types @@ -149,13 +157,13 @@ using the [Commons extension](../extensions/commons/README.md) to avoid duplicat An asset is an object that contains a link to data associated with the Item that can be downloaded or streamed. It is allowed to add additional fields. -| Field Name | Type | Description | -| ----------- | ------ | ----------- | -| href | string | **REQUIRED.** Link to the asset object. Relative and absolute links are both allowed. | -| title | string | The displayed title for clients and users. | -| description | string | A description of the Asset providing additional details, such as how it was processed or created. | -| type | string | [Media type](#media-types) of the asset. | -| roles | [string] | The semantic role of the asset, similar to the use of `rel` in links. +| Field Name | Type | Description | +| ----------- | -------- | ----------- | +| href | string | **REQUIRED.** Link to the asset object. Relative and absolute links are both allowed. | +| title | string | The displayed title for clients and users. | +| description | string | A description of the Asset providing additional details, such as how it was processed or created. [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for rich text representation. | +| type | string | [Media type](#media-types) of the asset. | +| roles | [string] | The [semantic roles](#asset-role-types) of the asset, similar to the use of `rel` in links. #### Asset Role Types @@ -163,10 +171,15 @@ Like the Link `rel` field, the `roles` field can be given any value, however her | Role Name | Description | | --------- | ------------------------------------------------------------------------------------- | -| thumbnail | STRONGLY RECOMMENDED. An asset that represents a thumbnail of the item, typically a true color image (for items with assets in the visible wavelengths), lower-resolution (typically smaller 600x600 pixels), and typically a JPEG or PNG (suitable for display in a web browser). Multiple assets may have this purpose, but it recommended that the `type` and `roles` be unique tuples. For example, Sentinel-2 L2A provides thumbnail images in both JPEG and JPEG2000 formats, and would be distinguished by their media types. | -| overview | An asset that represents a possibly larger view than the thumbnail of the Item , for example, a true color composite of multi-band data. | +| thumbnail | An asset that represents a thumbnail of the item, typically a true color image (for items with assets in the visible wavelengths), lower-resolution (typically smaller 600x600 pixels), and typically a JPEG or PNG (suitable for display in a web browser). Multiple assets may have this purpose, but it recommended that the `type` and `roles` be unique tuples. For example, Sentinel-2 L2A provides thumbnail images in both JPEG and JPEG2000 formats, and would be distinguished by their media types. | +| overview | An asset that represents a possibly larger view than the thumbnail of the Item, for example, a true color composite of multi-band data. | +| data | The data itself. This is a suggestion for a common role for data files to be used in case data providers don't come up with their own names and semantics. | | metadata | A metadata sidecar file describing the data in this item, for example the Landsat-8 MTL file. | +It is STRONGLY RECOMMENDED to add to each STAC Item +* a thumbnail with the role `thumbnail` for preview purposes +* one or more data file although it doesn't need to use the suggested role `data` + #### Media Types The media type of an Asset can be used by STAC browsers to better determine what to render and display diff --git a/item-spec/json-schema/basics.json b/item-spec/json-schema/basics.json new file mode 100644 index 000000000..858fddb18 --- /dev/null +++ b/item-spec/json-schema/basics.json @@ -0,0 +1,18 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "basics.json#", + "title": "Basic Descriptive Fields", + "type": "object", + "properties": { + "title": { + "title": "Item Title", + "description": "A human-readable title describing the Item.", + "type": "string" + }, + "description": { + "title": "Item Description", + "description": "Detailed multi-line description to fully explain the Item.", + "type": "string" + } + } +} \ No newline at end of file diff --git a/item-spec/json-schema/item.json b/item-spec/json-schema/item.json index 289bf7595..831643649 100644 --- a/item-spec/json-schema/item.json +++ b/item-spec/json-schema/item.json @@ -12,7 +12,10 @@ ], "definitions": { "common_metadata": { - "anyOf": [ + "allOf": [ + { + "$ref": "basics.json" + }, { "$ref": "datetimerange.json" }, @@ -49,7 +52,7 @@ "stac_version": { "title": "STAC version", "type": "string", - "const": "0.9.0-rc1" + "const": "0.9.0-rc2" }, "stac_extensions": { "title": "STAC extensions", @@ -68,12 +71,16 @@ "enum": [ "checksum", "commons", - "cube", + "datacube", "eo", "label", "pointcloud", + "projection", "sar", - "scientific" + "sat", + "scientific", + "version", + "view" ] } ] @@ -120,11 +127,6 @@ "description": "The searchable date/time of the assets, in UTC (Formatted in RFC 3339) ", "type": "string", "format": "date-time" - }, - "title": { - "title": "Item Title", - "description": "A human-readable title describing the item.", - "type": "string" } } }, diff --git a/item-spec/json-schema/itemcollection.json b/item-spec/json-schema/itemcollection.json index e5ec5ebd9..4b22dda9f 100644 --- a/item-spec/json-schema/itemcollection.json +++ b/item-spec/json-schema/itemcollection.json @@ -30,7 +30,7 @@ "stac_version": { "title": "STAC version", "type": "string", - "const": "0.9.0-rc1" + "const": "0.9.0-rc2" }, "stac_extensions": { "title": "STAC extensions",