diff --git a/.circleci/config.yml b/.circleci/config.yml index 7095d1c8..60cd9efe 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -1,6 +1,6 @@ version: 2 jobs: - test_examples: + test_examples_node: working_directory: ~/stac docker: - image: circleci/node:12 @@ -12,6 +12,18 @@ jobs: - run: name: validate command: npm run check-examples + # test_examples_python: + # working_directory: ~/stac + # docker: + # - image: circleci/python:3.8 + # steps: + # - checkout + # - run: + # name: install + # command: pip install stac-validator + # - run: + # name: validate + # command: find ./examples -type f -name "*.json" | xargs -L1 stac_validator test_docs: working_directory: ~/stac docker: @@ -43,7 +55,8 @@ workflows: version: 2 ci: jobs: - - test_examples + - test_examples_node + # - test_examples_python - test_docs - publish_schemas: filters: diff --git a/.circleci/rc.yaml b/.circleci/rc.yaml index 625a856a..b0dd538c 100644 --- a/.circleci/rc.yaml +++ b/.circleci/rc.yaml @@ -4,17 +4,15 @@ plugins: # Apply some recommended defaults for consistency - remark-preset-lint-consistent - remark-preset-lint-recommended -# No HTML for security - can't activate yet due to STAC logo in README.md -# - lint-no-html + - lint-no-html # General formatting -# - - remark-lint-emphasis-marker -# - '*' + - - remark-lint-emphasis-marker + - '*' - remark-lint-hard-break-spaces - remark-lint-blockquote-indentation - remark-lint-no-consecutive-blank-lines -# Detect overly long lines - be liberal for now and don't restrict to 80 yet -# - - remark-lint-maximum-line-length -# - 150 + - - remark-lint-maximum-line-length + - 150 # Code - remark-lint-fenced-code-flag - remark-lint-fenced-code-marker @@ -23,24 +21,23 @@ plugins: - 'fenced' # Headings - remark-lint-heading-increment - - remark-lint-no-duplicate-headings - remark-lint-no-multiple-toplevel-headings - remark-lint-no-heading-punctuation - - remark-lint-maximum-heading-length - 70 - - remark-lint-heading-style - atx + - - remark-lint-no-shortcut-reference-link + - false # Lists - remark-lint-list-item-bullet-indent - remark-lint-ordered-list-marker-style - remark-lint-ordered-list-marker-value - remark-lint-checkbox-character-style -# - - remark-lint-unordered-list-marker-style -# - '-' + - - remark-lint-unordered-list-marker-style + - '-' - - remark-lint-list-item-indent - space # Tables - remark-lint-table-pipes -# - remark-lint-table-pipe-alignment # Wait for https://github.com/remarkjs/remark-lint/issues/226 -# Urls - remark-lint-no-literal-urls \ No newline at end of file diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index e26fc2c9..bd3b2f95 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -10,5 +10,7 @@ - [ ] This PR is made against the dev branch (all proposed changes except releases should be against dev, not master). - [ ] This PR has **no** breaking changes. -- [ ] I have added my changes to the [CHANGELOG](https://github.com/radiantearth/stac-spec/blob/dev/CHANGELOG.md) **or** a CHANGELOG entry is not required. -- [ ] This PR affects the [STAC API spec](https://github.com/radiantearth/stac-api-spec), and I have opened issue/PR #XXX to track the change. +- [ ] I have added my changes to the [CHANGELOG](https://github.com/radiantearth/stac-spec/blob/dev/CHANGELOG.md) + **or** a CHANGELOG entry is not required. +- [ ] This PR affects the [STAC API spec](https://github.com/radiantearth/stac-api-spec), + and I have opened issue/PR #XXX to track the change. diff --git a/.remarkignore b/.remarkignore deleted file mode 100644 index 32524460..00000000 --- a/.remarkignore +++ /dev/null @@ -1 +0,0 @@ -/CHANGELOG.md \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md index 9a8027a1..47bf6e22 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,4 @@ + # Changelog All notable changes to this project will be documented in this file. @@ -6,6 +7,56 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. ## [Unreleased] +## [v1.0.0] - 2021-05-25 + +### Added + +- Updated best practices to add a recommendation to include title in links where possible. ([#1133](https://github.com/radiantearth/stac-spec/pull/1133)) + +### Changed + +- Updated version numbers for 1.0.0 release. +- Final UML tweaks for latest changes. ([#1134](https://github.com/radiantearth/stac-spec/pull/1134)) +- Removed ItemCollection from the STAC detection heuristic in Best Practices. It can't easily be differentiated from GeoJSON FeatureCollections any longer. ([API#141](https://github.com/radiantearth/stac-api-spec/issues/141)) + +## [v1.0.0-rc.4] - 2021-05-11 + +### Changed + +- An empty Catalog is now allowed, removed the requirement that it must have a child or item link. ([#1115](https://github.com/radiantearth/stac-spec/issues/1115)) +- An open date range to both sides is now allowed in the Collection's temporal extents. ([#1125](https://github.com/radiantearth/stac-spec/issues/1125)) +- Catalog and Collection JSON Schemas don't have a common JSON Schema any more. ([#1122](https://github.com/radiantearth/stac-spec/pull/1122)) + +### Removed + +- Catalogs don't support summaries any more. ([#1122](https://github.com/radiantearth/stac-spec/pull/1122)) + +### Fixed + +- Added clarification around when an extension should be included in `stac_extensions`. ([#1123](https://github.com/radiantearth/stac-spec/pull/1123)) +- JSON Schemas don't allow "shortcuts" for core extensions any longer. ([#1121](https://github.com/radiantearth/stac-spec/pull/1121)) +- Various examples fixes. + +## [v1.0.0-rc.3] - 2021-04-29 + +### Added + +- Summaries are allowed to specify JSON Schema in addition to ranges and sets of values. ([#1045](https://github.com/radiantearth/stac-spec/issues/1045)) +- Added `preview` relation type for interoperable thumbnails to best practices. ([#1090](https://github.com/radiantearth/stac-spec/issues/1090)) +- Recommendation to include both `root` and `parent` relation types when they point at the same file. ([#1098](https://github.com/radiantearth/stac-spec/issues/1098)) +- Overview section linking to various foundational standards. ([#1111](https://github.com/radiantearth/stac-spec/pull/1111)) + +### Changed + +- The first extent in a Collection is always the overall extent, followed by more specific extents. ([#1064](https://github.com/radiantearth/stac-spec/issues/1064), [opengeospatial/ogcapi-features#520](https://github.com/opengeospatial/ogcapi-features/pull/520)) +- Updated examples for automatic collection creation from code and validation ([#1080](https://github.com/radiantearth/stac-spec/pull/1080)) +- Clarified that stac_extensions should also list extensions that are used in Collection summaries. ([#1077](https://github.com/radiantearth/stac-spec/issues/1077)) +- The Stats Object for Summaries has been renamed to Range Object (no functional change). ([#1093](https://github.com/radiantearth/stac-spec/pull/1093)) +- `changed`, `created` (common metadata) and temporal extents (collections): Timestamps must be always in UTC ([#1095](https://github.com/radiantearth/stac-spec/issues/1095)) +- Clarified that collection summaries do not require that all property fields are summarized. ([#1106](https://github.com/radiantearth/stac-spec/issues/1106)) +- Clarified that gsd should only be used on an asset to represent the sensor, not just different processing. ([#1105](https://github.com/radiantearth/stac-spec/pull/1105)) +- Clarified that leaving a field out is not equivalent to setting it as null. ([#1111](https://github.com/radiantearth/stac-spec/pull/1111)) + ## [v1.0.0-rc.2] - 2021-03-30 ### Changed @@ -19,6 +70,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. ### Fixed +- Examples - Collection Assets were specified as required (only in written text, not in JSON Schema), but that was incorrectly copied over from the former `collection-assets` extension. Collection Assets are not required. - Clarified that the values in summaries (both for ranges and sets of values) must follow the data type of the property they summarize. ([#1069](https://github.com/radiantearth/stac-spec/pull/1069)) @@ -38,7 +90,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. ### Changed -- The [Stats Object](collection-spec/collection-spec.md#stats-object) for Collection `summaries` changed `min` to `minimum` and `max` to `maximum` to align with JSON Schema. ([#967](https://github.com/radiantearth/stac-spec/pull/967)) +- The [Stats Object](collection-spec/collection-spec.md#range-object) for Collection `summaries` changed `min` to `minimum` and `max` to `maximum` to align with JSON Schema. ([#967](https://github.com/radiantearth/stac-spec/pull/967)) - URIs (usually found int properties like `href`, `url`) are now validated using the `iri-reference` format in JSON Schema (allows international characters in URIs) ([#953](https://github.com/radiantearth/stac-spec/pull/953)) - Enhanced the way the spec talks about ID's to encourage more global uniqueness. ([#883](https://github.com/radiantearth/stac-spec/pull/883)) - Clarified how collection-level asset object properties do not remove the need for item-level asset object properties in the `item-assets` extension ([#880](https://github.com/radiantearth/stac-spec/pull/880)) @@ -81,7 +133,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. - The API portion of STAC has been split off into a [new repository: stac-api-spec](https://github.com/radiantearth/stac-api-spec) and will start being versioned and released separately than the core STAC spec. - proj4 string from proj extension - Various warnings about how the spec is very early and likely will change. -- implementations.md (migrated to https://stacspec.org) and how-to-help.md (migrated to https://github.com/stac-utils/stac-ecosystem). +- implementations.md (migrated to ) and how-to-help.md (migrated to ). - `commons` extension completely removed: Items should contain all properties and not default to a common set at the Collection level - ItemCollection removed from stac-spec core repo, will migrate to [stac-api-spec](https://github.com/radiantearth/stac-api-spec) as that is the only place it is used. @@ -96,17 +148,17 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. - Instructions on how to run check-markdown locally - Timestamps extensions (adds fields `published`, `expires` and `unpublished`) - `created` and `updated` can be used in the assets to specify the creation / update times of the assets. -- [Tiled Assets extension](extensions/tiled-assets/README.md), for representing data that has been split into tiles +- [Tiled Assets extension](https://github.com/stac-extensions/tiled-assets/blob/main/README.md), for representing data that has been split into tiles ### Changed -- [Label extension](extensions/label/README.md) types were clarified and types in README and JSON schema were brought into alignment +- [Label extension](https://github.com/stac-extensions/label/blob/main/README.md) types were clarified and types in README and JSON schema were brought into alignment - Moved item recommendations to best practices, and added a bit more in item spec about 'search' - Moved `eo:gsd` from `eo` extension to core `gsd` field in Item common metadata - `asset` extension renamed to `item-assets` and renamed `assets` field in Collections to `item_assets` - `item-assets` extension only requires any two fields to be available, not the two specific fields `title` and `type` - `datetime` allows `null` as value, but requires `start_datetime` and `end_datetime` then - Extensions `sat`, `scientific` and `view`: At least one field is required to be specified. -- [Single File STAC extension](extensions/single-file-stac/README.md) changed to be a complete STAC catalog + GeoJSON FeatureCollection that contains collections and items. +- [Single File STAC extension](https://github.com/stac-extensions/single-file-stac/blob/main/README.md) changed to be a complete STAC catalog + GeoJSON FeatureCollection that contains collections and items. - Improved several JSON Schemas ### Fixed @@ -119,11 +171,11 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. - 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), new `version` and `deprecated` fields in STAC Items and Collections + - [Version Indicators extension](https://github.com/stac-extensions/version/blob/main/README.md), new `version` and `deprecated` fields in STAC Items and Collections - Data Cube extension can be used in Collections, added new field `description` - - [Asset Extension](extensions/asset/README.md): new `description` and `roles` fields - - New [Projection Extension](extensions/projection/README.md) to describe Items with Assets that have an associated geospatial projection - - New [View Geometry Extension](extensions/view/README.md) + - [Asset Extension](https://github.com/stac-extensions/item-assets/blob/main/README.md): new `description` and `roles` fields + - New [Projection Extension](https://github.com/stac-extensions/projection/blob/main/README.md) to describe Items with Assets that have an associated geospatial projection + - New [View Geometry Extension](https://github.com/stac-extensions/view/blob/main/README.md) - STAC API: - Added the [Item and Collection API Version extension](https://github.com/radiantearth/stac-api-spec/tree/master/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 @@ -153,8 +205,8 @@ Item properties - `eo:sun_elevation` -> `view:sun_elevation` - Extensions: - Data Cube extension: Changed allowed formats (removed PROJ string, added PROJJSON / WKT2) for reference systems - - [Checksum extension](extensions/checksum/README.md) is now using self-identifiable hashes ([Multihash](https://github.com/multiformats/multihash)) - - Changed `sar:type` to `sar:product_type` and `sar:polarization` to `sar:polarizations` in the [SAR extension](extensions/sar/README.md) + - [Checksum extension](https://github.com/stac-extensions/checksum/blob/main/README.md) is now using self-identifiable hashes ([Multihash](https://github.com/multiformats/multihash)) + - Changed `sar:type` to `sar:product_type` and `sar:polarization` to `sar:polarizations` in the [SAR extension](https://github.com/stac-extensions/sar/blob/main/README.md) - STAC API: - The endpoint `/stac` has been merged with `/` - The endpoint `/stac/search` is now called `/search` @@ -170,16 +222,16 @@ fields. No change is required for STAC Items. - 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 ### Removed -- `version` field in STAC Collections. Use [Version Extension](extensions/version/README.md) instead +- `version` field in STAC Collections. Use [Version Extension](https://github.com/stac-extensions/version/blob/main/README.md) instead - `summaries` field from Catalogs. Use Collections instead - Asset Types (pre-defined values for the keys of individual assets, *not* media types) in Items. Use the asset's `roles` instead - `license` field doesn't allow SPDX expressions any longer. Use `various` and links instead - Extensions: - - `eo:platform`, `eo:instrument`, `eo:constellation` from EO extension, and `sar:platform`, `sar:instrument`, `sar:constellation` from the [SAR extension](extensions/sar/README.md) + - `eo:platform`, `eo:instrument`, `eo:constellation` from EO extension, and `sar:platform`, `sar:instrument`, `sar:constellation` from the [SAR extension](https://github.com/stac-extensions/sar/blob/main/README.md) - Removed from EO extension field `eo:epsg` in favor of `proj:epsg` - - `gsd` and `accuracy` from `eo:bands` in the [EO extension](extensions/eo/README.md) - - `sar:absolute_orbit` and `sar:center_wavelength` fields from the [SAR extension](extensions/sar/README.md) - - `data_type` and `unit` from the `sar:bands` object in the [SAR extension](extensions/sar/README.md) + - `gsd` and `accuracy` from `eo:bands` in the [EO extension](https://github.com/stac-extensions/eo/blob/main/README.md) + - `sar:absolute_orbit` and `sar:center_wavelength` fields from the [SAR extension](https://github.com/stac-extensions/sar/blob/main/README.md) + - `data_type` and `unit` from the `sar:bands` object in the [SAR extension](https://github.com/stac-extensions/sar/blob/main/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 @@ -213,11 +265,11 @@ fields. No change is required for STAC Items. ### Changed - Updated specification to base on WFS3 draft 2 (OGC API - Features - Part 1: Core, v1.0.0-draft.2). This leads to many changes in the API and one change in STAC collections, notably: - - The structure of the field `extent` in STAC and WFS Collections changed. - - Query parameter `time` was renamed to `datetime` and accepts slightly different values. - - WFS links have additional fields `hreflang` and `length`. - - WFS Collections have additional fields `crs` and `itemType`. - - `time` API parameter changed to `datetime` + - The structure of the field `extent` in STAC and WFS Collections changed. + - Query parameter `time` was renamed to `datetime` and accepts slightly different values. + - WFS links have additional fields `hreflang` and `length`. + - WFS Collections have additional fields `crs` and `itemType`. + - `time` API parameter changed to `datetime` - The API intersects parameter now accepts a GeoJSON Geometry (any type) *instead* of a GeoJSON Feature. - API: Clarification on `include` and `exclude` parameters in the field extension and notes on default values. - API: queries should contain either `bbox` or `intersects`. @@ -235,21 +287,21 @@ fields. No change is required for STAC Items. - Property `summaries` have been added to catalogs and collections. - API Transaction extension supports optimistic locking through use of the ETag header. - Asset Definition Extension added to Collections to allow specifying details about Assets that may appear in member Items. -- [Single File Catalog extension](extensions/single-file-stac/README.md) added as a format to have a set of Collections and Items in a single file. -- [Label extension](extensions/label/README.md) added with additional fields for describing labeled data, such as used for training data or from the output of a classification +- [Single File Catalog extension](https://github.com/stac-extensions/single-file-stac/blob/main/README.md) added as a format to have a set of Collections and Items in a single file. +- [Label extension](https://github.com/stac-extensions/label/blob/main/README.md) added with additional fields for describing labeled data, such as used for training data or from the output of a classification - Timestamp fields added to `Item`: `created` and `updated` to refer to the datetime the metadata file was created or updated. - Added Search Metadata API extension which adds fields to a response from a STAC API such as the number of items found and how many were returned. - ItemCollection class added to spec that is a GeoJSON FeatureCollection of Items, such as what would be returned from a search. Located in item directory. - `in` operator added to the query extension (to check if value is in a list of values) -- New bands added to the [common band names](extensions/eo/README.md#common-band-names) for the EO extension: yellow, rededge, and 2 narrow NIR bands -- [Scientific extension](extensions/scientific/README.md) can be used in Collections. +- New bands added to the [common band names](https://github.com/stac-extensions/eo/blob/main/README.md#common-band-names) for the EO extension: yellow, rededge, and 2 narrow NIR bands +- [Scientific extension](https://github.com/stac-extensions/scientific/blob/main/README.md) can be used in Collections. ### Fixed - Updated language, fixed typos and examples. - Renamed `pc:schema` to `pc:schemas` in the Point Cloud extension. ### Changes since 0.8.0rc1 -- [Label extension](extensions/label/README.md): +- [Label extension](https://github.com/stac-extensions/label/blob/main/README.md): - moved label:classes to be a list of Class Objects from a single Class Object in spec markdown and json schema (matching previous example JSON). - moved label:overview to be a list of Overview Objects from a single Overview Object in spec markdown and json schema (matching previous example JSON). - Renamed fields to use plural forms (`label:property` -> `label:properties`, `label:task` -> `label:tasks`, `label:method` -> `label:methods` and `label:overview` -> `label:overviews`) @@ -338,9 +390,9 @@ fields. No change is required for STAC Items. - **description**: Description fields now allow formatting with CommonMark. - **assets**: Fields changed names: `name` to `title` and `mime_type` to `type`. -### Removed: -* **provider**: Provider field in Items got removed. Use Collections or the Single Item extension instead. -* **license**: License field in Items got removed. Use Collections or the Single Item extension instead. +### Removed +- **provider**: Provider field in Items got removed. Use Collections or the Single Item extension instead. +- **license**: License field in Items got removed. Use Collections or the Single Item extension instead. ## [v0.5.2] - 2018-07-12 @@ -350,21 +402,21 @@ Minor bug fixes on 0.5.1 for the schema files. Thanks @francbartoli Minor bug fixes from 0.5.1 release -* [Update openapi / swagger specs for new 'links'](https://github.com/radiantearth/stac-spec/commit/480d4fb02b4a7e880c7ca01320fe2773260ba595) -* [minor fixes on collection extension](https://github.com/radiantearth/stac-spec/pull/124) - thanks @m-mohr -* [minor cbers example updates](https://github.com/radiantearth/stac-spec/pull/123) - thanks @fredliporace +- [Update openapi / swagger specs for new 'links'](https://github.com/radiantearth/stac-spec/commit/480d4fb02b4a7e880c7ca01320fe2773260ba595) +- [minor fixes on collection extension](https://github.com/radiantearth/stac-spec/pull/124) - thanks @m-mohr +- [minor cbers example updates](https://github.com/radiantearth/stac-spec/pull/123) - thanks @fredliporace ## [v0.5.0] - 2018-07-01 The 0.5.0 release of the STAC spec is an iteration forward on the spec, with a number of core improvements. Highlights include: -* **Links is now a dictionary** - This is the most core change done. It aligns the structure with the 'asset' change in 0.5.0, making it easier for clients to look up the link that they want more easily. The schema is updated to this (and actually checks assets better now, thanks @mojodna ) +- **Links is now a dictionary** - This is the most core change done. It aligns the structure with the 'asset' change in 0.5.0, making it easier for clients to look up the link that they want more easily. The schema is updated to this (and actually checks assets better now, thanks @mojodna ) -* **Transactions Extension** - There is now a transaction extension for the STAC API, thanks to @hgs-msmith and @hgs-trutherford +- **Transactions Extension** - There is now a transaction extension for the STAC API, thanks to @hgs-msmith and @hgs-trutherford -* **Collections iterations** @matthewhanson has evolved the collections extension, adding in some namespace type hints on it, and explaining it more clearly. +- **Collections iterations** @matthewhanson has evolved the collections extension, adding in some namespace type hints on it, and explaining it more clearly. -* **eo:crs to eo:epsg** In the EO profile @matthewhanson brought in a change to use EPSG code, instead of full Well Known Text, to make it easy to reference. +- **eo:crs to eo:epsg** In the EO profile @matthewhanson brought in a change to use EPSG code, instead of full Well Known Text, to make it easy to reference. Full list of issues and pull requests at @@ -372,10 +424,10 @@ Full list of issues and pull requests at +[v1.0.0]: +[v1.0.0-rc.4]: +[v1.0.0-rc.3]: [v1.0.0-rc.2]: [v1.0.0-rc.1]: [v1.0.0-beta.2]: diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index b3776240..984c77e6 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -14,21 +14,21 @@ appearance, race, religion, or sexual identity and orientation. Examples of behavior that contributes to creating a positive environment include: -* Using welcoming and inclusive language -* Being respectful of differing viewpoints and experiences -* Gracefully accepting constructive criticism -* Focusing on what is best for the community -* Showing empathy towards other community members +- Using welcoming and inclusive language +- Being respectful of differing viewpoints and experiences +- Gracefully accepting constructive criticism +- Focusing on what is best for the community +- Showing empathy towards other community members Examples of unacceptable behavior by participants include: -* The use of sexualized language or imagery and unwelcome sexual attention or +- The use of sexualized language or imagery and unwelcome sexual attention or advances -* Trolling, insulting/derogatory comments, and personal or political attacks -* Public or private harassment -* Publishing others' private information, such as a physical or electronic +- Trolling, insulting/derogatory comments, and personal or political attacks +- Public or private harassment +- Publishing others' private information, such as a physical or electronic address, without explicit permission -* Other conduct which could reasonably be considered inappropriate in a +- Other conduct which could reasonably be considered inappropriate in a professional setting ## Our Responsibilities diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6fd9042d..5b9b2d7a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -24,12 +24,12 @@ require you to switch from the default of 'master', which we keep so it displays Creating a Pull Request will show our PR template, which includes checkbox reminders for a number of things. -* Adding an entry the [CHANGELOG](CHANGELOG.md). If the change is more editorial and minor then this +- Adding an entry the [CHANGELOG](CHANGELOG.md). If the change is more editorial and minor then this is not required, but any change to the actual specification should definitely have one. -* Base the PR against dev, as mentioned above - even if the branch was made off of dev this reminds +- Base the PR against dev, as mentioned above - even if the branch was made off of dev this reminds you to change the base in GitHub's PR creation page. -* Make a ticket in the STAC API repo if anything here affects there. -* Highlight if the PR makes breaking changes to the specification (in beta there can still be +- Make a ticket in the STAC API repo if anything here affects there. +- Highlight if the PR makes breaking changes to the specification (in beta there can still be select breaking changes, but after 1.0 this will change) All pull requests should submit clean markdown, which is checked by the continuous integration @@ -37,7 +37,8 @@ system. Please use `npm run check` locally, as described in the [next section](# to ensure that the checks on the pull request succeed. If it does not then you can look at the mistakes online, which are the same as running `npm run check` locally would surface. -All pull requests that modify or create JSON schema files or examples should use [JSON formatter](https://jsonformatter.org/) to keep files consistent across the repo. +All pull requests that modify or create JSON schema files or examples should use +[JSON formatter](https://jsonformatter.org/) to keep files consistent across the repo. All pull requests additionally require a review of two STAC core team members. Releases are cut from dev to master (and require 3 approvals), see the [process](process.md) document for more details. @@ -45,7 +46,8 @@ from dev to master (and require 3 approvals), see the [process](process.md) docu ### Check files The same check-markdown and check-examples programs that runs as a check on PR's is part of the repo and can be run locally. -To install you'll need npm, which is a standard part of any [node.js installation](https://nodejs.org/en/download/). Alternatively, you can also use [yarn](https://yarnpkg.com/) instead of npm. In this case replace all occurrences of `npm` with `yarn` below. +To install you'll need npm, which is a standard part of any [node.js installation](https://nodejs.org/en/download/). +Alternatively, you can also use [yarn](https://yarnpkg.com/) instead of npm. In this case replace all occurrences of `npm` with `yarn` below. First you'll need to install everything with npm once. Just navigate to the root of the stac-spec repo and on your command line run: diff --git a/README.md b/README.md index cbe1c3e3..70ea3246 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,4 @@ + stac-logo [![CircleCI](https://circleci.com/gh/radiantearth/stac-spec.svg?style=svg)](https://circleci.com/gh/radiantearth/stac-spec) @@ -13,7 +14,9 @@ including sources such as aircraft and drone and data such as hyperspectral opti synthetic aperture radar (SAR), video, point clouds, lidar, digital elevation models (DEM), vector, machine learning labels, and composites like NDVI and mosaics. STAC is intentionally designed with a minimal core and flexible -extension mechanism to support a broad set of use cases. +extension mechanism to support a broad set of use cases. This specification +has matured over the past several years, and is used in [numerous production +deployments](https://stacindex.org/catalogs). This is advantageous to providers of geospatial data, as they can simply use a well-designed, standard format and API without needing to design their own proprietary one. @@ -42,22 +45,15 @@ with a well-defined set of additional attributes ("foreign members"). The **STAC extends the **[OGC API - Features - Part 1: Core](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html)** with additional web service endpoints and object attributes. -## Stability Note - -This specification has matured over the past several years, and is used in -[numerous production deployments](https://stacindex.org/catalogs). -With the 1.0.0 release, implementors should expect that most definitions will remain -stable. Our goal -is to maintain backwards-compatiblity within the core for a long time. -The STAC specification follows [Semantic Versioning](https://semver.org/), so once -1.0.0 is reached, any breaking change will require the spec to go to 2.0.0. - ## 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 **1.0.0** 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 +version of the spec. It is currently version **1.0.0** of the specification. The STAC specification +follows [Semantic Versioning](https://semver.org/), so any breaking change will require the spec to +go to 2.0.0. + +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. More information on how the STAC development process works can be found in [process.md](process.md). @@ -83,23 +79,24 @@ that enable clients to search for Item objects that match their filtering criter The **Item**, **Catalog**, **Collection**, and **STAC API** specifications are intended to be used together, but are designed so each piece is small, self-contained, and reusable in other contexts. -* **[Overview](overview.md)** describes the three core object type specifications and how they relate to one another. -* **[Item Specification](item-spec/)** defines a STAC **Item**, which is a [GeoJSON](http://geojson.org) **Feature** -with additional fields ("foreign members") for attributes like time and links to related entities and assets -(including thumbnails). This is the core entity that describes the data to be discovered. -* **[Catalog Specification](catalog-spec/)** specifies a structure to link various STAC Items together to be crawled or browsed. It is a -simple, flexible JSON file of links to Items, Catalogs or Collections that can be used in a variety of ways. -* **[Collection Specification](collection-spec/)** provides additional information about a spatio-temporal collection of data. -In the context of STAC it is most likely a related group of STAC Items that is made available by a data provider. -It includes things like the spatial and temporal extent of the data, the license, keywords, etc. -It enables discovery at a higher level than individual Item objects, providing a simple way to describe sets of data. -* **[Examples](examples/):** The *[examples/](examples/)* folder contains examples for all three specifications, linked together to form two -complete examples. Each spec and extension links in to highlight particular files that demonstrate key concepts. -* **[Extensions](extensions/README.md)** describe how STAC can use extensions that extend the functionality of the core spec or -add fields for specific domains. Extensions can be published anywhere, although the preferred location for public extensions is in the [GitHub `stac-extensions` organization](https://github.com/stac-extensions). -* **Additional documents:** The supporting documents include a complementary [best practices](best-practices.md) -document, and information on contributing (links in the next section). We also maintain a [changelog](CHANGELOG.md) of -what was modified in each version. +- **[Overview](overview.md)** describes the three core object type specifications and how they relate to one another. +- **[Item Specification](item-spec/)** defines a STAC **Item**, which is a [GeoJSON](http://geojson.org) **Feature** + with additional fields ("foreign members") for attributes like time and links to related entities and assets + (including thumbnails). This is the core entity that describes the data to be discovered. +- **[Catalog Specification](catalog-spec/)** specifies a structure to link various STAC Items together to be crawled or browsed. It is a + simple, flexible JSON file of links to Items, Catalogs or Collections that can be used in a variety of ways. +- **[Collection Specification](collection-spec/)** provides additional information about a spatio-temporal collection of data. + In the context of STAC it is most likely a related group of STAC Items that is made available by a data provider. + It includes things like the spatial and temporal extent of the data, the license, keywords, etc. + It enables discovery at a higher level than individual Item objects, providing a simple way to describe sets of data. +- **[Examples](examples/):** The *[examples/](examples/)* folder contains examples for all three specifications, linked together to form two + complete examples. Each spec and extension links in to highlight particular files that demonstrate key concepts. +- **[Extensions](extensions/README.md)** describe how STAC can use extensions that extend the functionality of the core spec or + add fields for specific domains. Extensions can be published anywhere, + although the preferred location for public extensions is in the [GitHub `stac-extensions` organization](https://github.com/stac-extensions). +- **Additional documents:** The supporting documents include a complementary [best practices](best-practices.md) + document, and information on contributing (links in the next section). We also maintain a [changelog](CHANGELOG.md) of + what was modified in each version. ## Contributing diff --git a/STAC-UML.drawio b/STAC-UML.drawio index fca34d35..1fcde668 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 c3e02556..37e7dff2 100644 Binary files a/STAC-UML.pdf and b/STAC-UML.pdf differ diff --git a/best-practices.md b/best-practices.md index 87baf0c8..6eed1e18 100644 --- a/best-practices.md +++ b/best-practices.md @@ -9,7 +9,8 @@ - [Deploying STAC Browser](#deploying-stac-browser) - [Requester Pays](#requester-pays) - **[Item Best Practices](#item-practices)** - - [Field and ID formatting](#field-and-id-formatting) + - [Field and ID formatting](#item-ids) + - [Searchable Identifiers](#searchable-identifiers) - [Field selection and Metadata Linking](#field-selection-and-metadata-linking) - [Datetime selection](#datetime-selection) - [Unlocated Items](#unlocated-items) @@ -45,6 +46,7 @@ - [Keep catalogs in sync with cloud notification and queue services](#keep-catalogs-in-sync-with-cloud-notification-and-queue-services) - [How to Differentiate STAC Files](#how-to-differentiate-stac-files) + This document makes a number of recommendations for creating real world SpatioTemporal Asset Catalogs. None of them are required to meet the core specification, but following these practices will make life easier for client tooling and for users. They come about from practical experience of implementors and introduce a bit more 'constraint' for @@ -61,7 +63,8 @@ STAC strives to make geospatial information more accessible, by putting it on th different tools will be able to load and display public-facing STAC data. But the web runs on a [Same origin policy](https://en.wikipedia.org/wiki/Same-origin_policy), preventing web pages from loading information from other web locations to prevent malicious scripts from accessing sensitive data. This means that by default a web page would only be able to load STAC -[Item](item-spec/item-spec.md) objects from the same server the page is on. [Cross-origin resource sharing](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing), +[Item](item-spec/item-spec.md) objects from the same server the page is on. +[Cross-origin resource sharing](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing), also known as 'CORS' is a protocol to enable safe communication across origins. But most web services turn it off by default. This is generally a good thing, but unfortunately if CORS is not enabled then any browser-based STAC tool will not work. @@ -70,8 +73,8 @@ So to enable all the great web tools (like [stacindex.org](http://stacindex.org) [Google Cloud Storage](https://cloud.google.com/storage/docs/cross-origin), or [Apache Server](https://enable-cors.org/server_apache.html). Many more are listed on [enable-cors.org](https://enable-cors.org/server.html). We recommend enabling CORS for all requests ('\*'), so that diverse online tools can access your data. If you aren't sure if your server has CORS enabled you can use -[test-cors.org](https://www.test-cors.org/). Enter the URL of your STAC root [Catalog](catalog-spec/catalog-spec.md) JSON -and make sure it gets a response. +[test-cors.org](https://www.test-cors.org/). Enter the URL of your STAC root [Catalog](catalog-spec/catalog-spec.md) or +[Collection](collection-spec/collection-spec.md) JSON and make sure it gets a response. ### STAC on the Web @@ -80,7 +83,7 @@ surprised that there is nothing about HTML in the entire specification. This is should be on web pages without ending up with very bad looking pages. But the importance of having web-accessible versions of every STAC Item is paramount. -The main recommendation is to have an HTML page for every single STAC Item and Catalog. They should be visually pleasing, +The main recommendation is to have an HTML page for every single STAC Item, Catalog and Collection. They should be visually pleasing, crawlable by search engines and ideally interactive. The current best practice is to use a tool in the STAC ecosystem called [STAC Browser](https://github.com/radiantearth/stac-browser/). It can crawl most any valid STAC implementation and generate unique web pages for each Item and Catalog (or Collection). While it has a default look and feel, the design can easily be @@ -122,36 +125,45 @@ should have its own location and just be part of the wider web. It is very common that large, freely available datasets are set up with a 'requester pays' configuration. This is an option [on AWS](https://docs.aws.amazon.com/AmazonS3/latest/userguide/RequesterPaysBuckets.html) and [on Google Cloud](https://cloud.google.com/storage/docs/requester-pays), that enables data providers to make their data -available to everyone, while the cloud platform charges access costs (such as per-request and data '[egress](https://www.hostdime.com/blog/data-egress-fees-cloud/)') to the user accessing the data. +available to everyone, while the cloud platform charges access costs +(such as per-request and data '[egress](https://www.hostdime.com/blog/data-egress-fees-cloud/)') to the user accessing the data. For popular datasets that are large in size the egress costs can be substantial, to the point where much less data would be available if the cost of distribution was always on the data provider. For data providers using STAC with requester pays buckets, there are two main recommendations: -1) Put the STAC JSON in a separate bucket that is public for everyone and **not** requestor pays. This enables the STAC metadata -to be far more crawlable and searchable, but the cost of the egress of STAC files should be miniscule compared to that of -the actual data. The STAC community can help you work with cloud providers for potential free hosting if you are doing open -data as requestor pays and aren't able to pay the costs of a completely open STAC bucket, as they are most all supportive of -STAC (but no guarantees and it may be on an alternate cloud). -2) For Asset href values to resources in a requestor pays bucket, use the cloud provider-specific protocol (e.g., `s3://` on AWS and `gs://` on Google Cloud) instead of an `https://` url. Most clients do not have special handling for `https://` links to cloud provider resources that require a requestor pays flag and authentication, so they simply fail. Many clients have special handling for `s3://` or `gs://` URLs that will add a requestor pays parameter and will apply appropriate authentication to the request. -Using cloud-specific protocols will at least give users an option to register a paid account and allow the data provider to properly charge for access. -STAC-specific tools in turn can look for the cloud-specific protocols and know to use the requestor pays feature for that specific cloud platform. +1. Put the STAC JSON in a separate bucket that is public for everyone and **not** requestor pays. This enables the STAC metadata + to be far more crawlable and searchable, but the cost of the egress of STAC files should be miniscule compared to that of + the actual data. The STAC community can help you work with cloud providers for potential free hosting if you are doing open + data as requestor pays and aren't able to pay the costs of a completely open STAC bucket, as they are most all supportive of + STAC (but no guarantees and it may be on an alternate cloud). +2. For Asset href values to resources in a requestor pays bucket, use the cloud provider-specific protocol + (e.g., `s3://` on AWS and `gs://` on Google Cloud) instead of an `https://` url. + Most clients do not have special handling for `https://` links to cloud provider resources that require a requestor pays flag and authentication, + so they simply fail. Many clients have special handling for `s3://` or `gs://` URLs + that will add a requestor pays parameter and will apply appropriate authentication to the request. + Using cloud-specific protocols will at least give users an option to register a paid account and + allow the data provider to properly charge for access. + STAC-specific tools in turn can look for the cloud-specific protocols and know to use the requestor pays feature for that specific cloud platform. ## Item Practices -### Field and ID formatting +### Item IDs When defining one's STAC properties and fields there are many choices to make on how to name various aspects of one's data. One of the key properties is the ID. The specification is quite flexible on ID's, primarily so that existing providers can easily use their same ID when they translate their data into STAC - they just need to be sure it is globally -unique, so may need a prefix. But the use of URI reserved characters such as `:` or `/` is discouraged since this will +unique, so may need a prefix. But the use of URI or file path reserved characters such as `:` or `/` is discouraged since this will result in [percented encoded](https://tools.ietf.org/html/rfc3986#section-2) [STAC API](https://github.com/radiantearth/stac-api-spec) -endpoints. This isn't a blocker, it just makes the ID's served through API's a bit less parsable. +endpoints and it prevents the use of IDs as file names as recommended in the [catalog layout](#catalog-layout) best practices. + +### Searchable Identifiers -When defining unique fields for search, like constellation or platform, it is recommended that -the value consist of only lowercase characters, numbers, `_`, and `-`. Examples include `sentinel-1a` (Sentinel-1), -`landsat-8` (Landsat-8) and `envisat` (Envisat). This is to provide consistency for search across Collections, so that -people can just search for 'landsat-8', instead of thinking through all the ways providers might have chosen to name it. +When coming up with values for fields that contain searchable identifiers of some sort, like `constellation` or `platform`, +it is recommended that the identifiers consist of only lowercase characters, numbers, `_`, and `-`. +Examples include `sentinel-1a` (Sentinel-1), `landsat-8` (Landsat-8) and `envisat` (Envisat). +This is to provide consistency for search across Collections, so that people can just search for `landsat-8`, +instead of thinking through all the ways providers might have chosen to name it. ### Field selection and Metadata Linking @@ -161,8 +173,9 @@ flexible enough that providers can fill it with tens or even hundreds of fields providers have lots of metadata then that can be linked to in the [Asset Object](item-spec/item-spec.md#asset-object) (recommended) or in a [Link Object](item-spec/item-spec.md#link-object). There is a lot of metadata that is only of relevance to loading and processing data, and while STAC does not prohibit providers from putting those type of fields in their items, -it is not recommended. For very large catalogs (hundreds of millions of records), every additional field that is indexed will cost substantial money, so data providers are advised to just put the fields to be searched in STAC, so [STAC API](https://github.com/radiantearth/stac-api-spec) -providers don't have bloated indices that no one actually uses. +it is not recommended. For very large catalogs (hundreds of millions of records), +every additional field that is indexed will cost substantial money, so data providers are advised to just put the fields to be searched in STAC and +[STAC API](https://github.com/radiantearth/stac-api-spec) providers don't have bloated indices that no one actually uses. ### Datetime selection @@ -244,17 +257,26 @@ found in Item properties at the asset level. This mechanism of overriding or pro makes discovery more difficult and should generally be avoided. However, there are some core and extension fields for which providing them at at the Asset level can prove to be very useful for using the data. -- `datetime`: Provide individual timestamp on an Item, in case the Item has a `start_datetime` and `end_datetime`, but an Asset is for one specific time. -- `gsd` ([Common Metadata](item-spec/common-metadata.md#instrument)): Specify some assets with different spatial resolution -than the overall best resolution. -- `eo:bands` ([EO extension](https://github.com/stac-extensions/eo/)): Provide spectral band information, and order of bands, within an individual asset. -- `proj:epsg`/`proj:wkt2`/`proj:projjson` ([projection extension](https://github.com/stac-extensions/projection/)): Specify different projection for some assets. If the projection is different - for all assets it should probably not be provided as an Item property. If most assets are one projection, and there is - a single reprojected version (such as a Web Mercator preview image), it is sensible to specify the main projection in the - Item and the alternate projection for the affected asset(s). -- `proj:shape`/`proj:transform` ([projection extension](https://github.com/stac-extensions/projection/)): If assets have different spatial resolutions and slightly different exact bounding boxes, specify these per asset to indicate the size of the asset in pixels and its exact GeoTransform in the native projection. -- `sar:polarizations` ([sar extension](https://github.com/stac-extensions/sar)): Provide the polarization content and ordering of a specific asset, similar to `eo:bands`. -- `sar:product_type` ([sar extension](https://github.com/stac-extensions/sar)): If mixing multiple product types within a single Item, this can be used to specify the product_type for each asset. +- `datetime`: Provide individual timestamp on an Item, in case the Item has a `start_datetime` and `end_datetime`, + but an Asset is for one specific time. +- `gsd` ([Common Metadata](item-spec/common-metadata.md#instrument)): Specify some assets that represent instruments + with different spatial resolution than the overall best resolution. Note this should not be used for different + spatial resolutions due to specific processing of assets - look into the [raster + extension](https://github.com/stac-extensions/raster) for that use case. +- `eo:bands` ([EO extension](https://github.com/stac-extensions/eo/)): + Provide spectral band information, and order of bands, within an individual asset. +- `proj:epsg`/`proj:wkt2`/`proj:projjson` ([projection extension](https://github.com/stac-extensions/projection/)): + Specify different projection for some assets. If the projection is different + for all assets it should probably not be provided as an Item property. If most assets are one projection, and there is + a single reprojected version (such as a Web Mercator preview image), it is sensible to specify the main projection in the + Item and the alternate projection for the affected asset(s). +- `proj:shape`/`proj:transform` ([projection extension](https://github.com/stac-extensions/projection/)): + If assets have different spatial resolutions and slightly different exact bounding boxes, + specify these per asset to indicate the size of the asset in pixels and its exact GeoTransform in the native projection. +- `sar:polarizations` ([sar extension](https://github.com/stac-extensions/sar)): + Provide the polarization content and ordering of a specific asset, similar to `eo:bands`. +- `sar:product_type` ([sar extension](https://github.com/stac-extensions/sar)): + If mixing multiple product types within a single Item, this can be used to specify the product_type for each asset. ### Working with Media Types @@ -278,7 +300,7 @@ following table lists some of the most common ones you may encounter or use. | `image/png` | Visual PNGs (e.g. thumbnails) | | `image/jpeg` | Visual JPEGs (e.g. thumbnails, oblique) | | `text/xml` or `application/xml` | XML metadata [RFC 7303](https://www.ietf.org/rfc/rfc7303.txt) | -| `application/json` | A JSON file (often metadata, or [labels](https://github.com/radiantearth/stac-spec/tree/master/extensions/label#labels-required)) | +| `application/json` | A JSON file (often metadata, or [labels](https://github.com/radiantearth/stac-spec/tree/master/extensions/label#labels-required)) | | `text/plain` | Plain text (often metadata) | | `application/geo+json` | [GeoJSON](https://geojson.org/) | | `application/geopackage+sqlite3` | [GeoPackage](https://www.geopackage.org/) | @@ -378,6 +400,10 @@ file that just has the bands needed for display ## Catalog & Collection Practices +*Note: This section uses the term 'Catalog' (with an uppercase C) to refer to the JSON entity specified in the +[Catalog spec](catalog-spec/catalog-spec.md), and 'catalog' (with a lowercase c) to refer to any full STAC implementation, +which can be any mix of Catalogs Collections and Items.* + ### Static and Dynamic Catalogs As mentioned in the main [overview](overview.md), there are two main types of catalogs - static @@ -431,7 +457,7 @@ providers, and users could browse down to both. The leaf Items should just be li ### Catalog Layout -Creating a catalog involves a number of decisions as to what folder structure to use to represent sub-catalogs, items +Creating a catalog involves a number of decisions as to what folder structure to use to represent sub-catalogs, Items and assets, and how to name them. The specification leaves this totally open, and you can link things as you want. But it is recommended to be thoughtful about the organization of sub-catalogs, putting them into a structure that a person might reasonably browse (since they likely will with [STAC on the Web](#stac-on-the-web) recommendations). For example @@ -448,12 +474,19 @@ if you follow these recommendations. 1. Root documents (Catalogs / Collections) should be at the root of a directory tree containing the static catalog. 2. Catalogs should be named `catalog.json` and Collections should be named `collection.json`. 3. Items should be named `.json`. -4. Sub-Catalogs should be stored in subdirectories of their parent (and only 1 subdirectory deeper than a document's parent) (e.g. `.../sample/sub1/catalog.json`). -5. Items should be stored in subdirectories of their parent Catalog. -This means that each Item and its assets are contained in a unique subdirectory. -6. Limit the number of Items in a Catalog or sub-Catalog, grouping / partitioning as relevant to the dataset. -7. Use structural elements (Catalog and Collection) consistently across each 'level' of your hierarchy. For example, if levels 2 and 4 of the hierarchy only contain Collections, -don't add a Catalog at levels 2 and 4. +4. Sub-Catalogs or sub-Collections should be stored in subdirectories of their parent + (and only 1 subdirectory deeper than a document's parent, e.g. `.../sample/sub1/catalog.json`). +5. Items should be stored in subdirectories of their parent Catalog or Collection. + This means that each Item and its assets are contained in a unique subdirectory. +6. Limit the number of Items in a Catalog or Collection, grouping / partitioning as relevant to the dataset. +7. Use structural elements (Catalog and Collection) consistently across each 'level' of your hierarchy. + For example, if levels 2 and 4 of the hierarchy only contain Collections, + don't add a Catalog at levels 2 and 4. + +One further recommendation to help tools is to always include the 'title' field when including a link, especially in the +`item`, `child`, `parent` and `root` links, even if it repeats several times. This should be the same as the 'title' in the +link destination. Having this enables clients to display a nice human readable name of the link without having to open the +link destination. #### Dynamic Catalog Layout @@ -466,7 +499,7 @@ different sub-catalog organization structures. For example one catalog could div by providers, and users could browse down to both. The leaf Items should just be linked to in a single canonical location (or at least use a rel link that indicates the location of the canonical one). It is recommended that dynamic catalogs provide multiple 'views' to allow users to navigate in a way that makes sense to them, providing multiple 'sub-catalogs' -from the root Catalog that enable different paths to browse (country/state, date/time, constellation/satellite, etc). But the +from the root that enable different paths to browse (country/state, date/time, constellation/satellite, etc). But the canonical 'rel' link should be used to designate the primary location of the Item to search engine crawlers. #### Mixing STAC Versions @@ -487,31 +520,34 @@ a bit of a 'curated' view. Some general thinking on what to summarize is as follows: -* Any field that is a range of data (like numbers or dates) is a great candidate to summarize, to give people a sense what values +- Any field that is a range of data (like numbers or dates) is a great candidate to summarize, to give people a sense what values the data might be. For example in overhead imagery, a -[`view:off_nadir`](https://github.com/stac-extensions/view/blob/main/README.md#item-properties-and-item-asset-fields) with a range of 0 to 3 would tell people this -imagery is all pretty much straight down, while a value of 15 to 40 would tell them that it's oblique imagery, or 0 to 60 that it's +[`view:off_nadir`](https://github.com/stac-extensions/view/blob/main/README.md#item-properties-and-item-asset-fields) +with a range of 0 to 3 would tell people this imagery is all pretty much straight down, +while a value of 15 to 40 would tell them that it's oblique imagery, or 0 to 60 that it's a Collection with lots of different look angles. -* Fields that have only one or a handful of values are also great to summarize. Collections with a single satellite may +- Fields that have only one or a handful of values are also great to summarize. Collections with a single satellite may use a single [`gsd`](item-spec/common-metadata.md#instrument) field in the summary, and it's quite useful for users to know that all data is going to be the same resolution. Similarly it's useful to know the names of all the [`platform` values](item-spec/common-metadata.md#instrument) that are used in the Collection. -* It is less useful to summarize fields that have numerous different discrete values that can't easily be represented +- It is less useful to summarize fields that have numerous different discrete values that can't easily be represented in a range. These will mostly be string values, when there aren't just a handful of options. For example if you had a 'location' field that gave 3 levels of administrative region (like 'San Francisco, California, United States') to help people understand more intuitively where a shot was taken. If your Collection has millions of Items, or even hundreds, you don't want to include all the different location string values in a summary. -* Fields that consist of arrays are more of a judgement call. For example [`instruments`](item-spec/common-metadata.md#instrument) +- Fields that consist of arrays are more of a judgement call. For example [`instruments`](item-spec/common-metadata.md#instrument) is straightforward and recommended, as the elements of the array are a discrete set of options. On the other hand -[`proj:transform`](https://github.com/stac-extensions/projection/blob/main/README.md#projtransform) makes no sense to summarize, as the union of all the values +[`proj:transform`](https://github.com/stac-extensions/projection/blob/main/README.md#projtransform) +makes no sense to summarize, as the union of all the values in the array are meaningless, as each Item is describing its transform, so combining them would just be a bunch of random numbers. So if the values contained in the array are independently meaningful (not interconnected) and there aren't hundreds of potential values then it is likely a good candidate to summarize. -We do highly recommend including an [`eo:bands`](https://github.com/stac-extensions/eo/blob/main/README.md#eobands) summary if your Items implement `eo:bands`, +We do highly recommend including an [`eo:bands`](https://github.com/stac-extensions/eo/blob/main/README.md#eobands) +summary if your Items implement `eo:bands`, especially if it represents just one satellite or constellation. This should be a union of all the potential bands that you have in assets. It is ok to only add the summary at the Collection level without putting an explicit `eo:bands` summary at the `properties` level of an Item, since that is optional. This gives users of the Collection a sense of the sensor capabilities without @@ -537,7 +573,7 @@ able to use it on their local computer, so all links need to be relative. Or a t without knowing the final location that it will live at online, so it isn't possible to set absolute 'self' URL's. These use cases should utilize a catalog that follows the listed principles: -* **Only relative href's in structural `links`**: The full catalog structure of links down to sub-catalogs and Items, and their +- **Only relative href's in structural `links`**: The full catalog structure of links down to sub-catalogs and Items, and their links back to their parents and roots, should be done with relative URL's. The structural rel types include `root`, `parent`, `child`, `item`, and `collection`. Other links can be absolute, especially if they describe a resource that makes less sense in the catalog, like [sci:doi](https://github.com/stac-extensions/scientific/blob/main/README.md#item-and-collection-fields), @@ -545,7 +581,7 @@ the catalog, like [sci:doi](https://github.com/stac-extensions/scientific/blob/m online location which makes more sense to refer to directly). This enables the full catalog to be downloaded or copied to another location and to still be valid. This also implies no `self` link, as that link must be absolute. -* **Use Asset `href` links consistently**: The links to the actual assets are allowed to be either relative or absolute. There +- **Use Asset `href` links consistently**: The links to the actual assets are allowed to be either relative or absolute. There are two types of 'self-contained catalogs'. #### Self-contained Metadata Only @@ -564,7 +600,9 @@ and used in other contexts. That catalog could be used offline, or even publishe Self-contained catalogs are not just for offline use, however - they are designed to be able to be published online and to live on the cloud in object storage. They just aim to ease the burden of publishing, by not requiring lots of updating of links. -Adding a single `self` link at the root is recommended for online catalogs, turning it into a 'relative published catalog', as detailed below. This anchors it in an online location and enables provenance tracking. +Adding a single `self` link at the root is recommended for online catalogs, +turning it into a 'relative published catalog', as detailed below. +This anchors it in an online location and enables provenance tracking. #### Published Catalogs @@ -586,9 +624,9 @@ implement it. #### Relative Published Catalog This is a self-contained catalog as described above, except it includes an absolute `self` link at -the root catalog, to identify its online location. This is designed so that a self-contained catalog (of either type, with its +the root to identify its online location. This is designed so that a self-contained catalog (of either type, with its assets or just metadata) can be 'published' online -by just adding one field (the self link) to its root catalog. All the other links should remain the same. The resulting catalog +by just adding one field (the self link) to its root (Catalog or Collection). All the other links should remain the same. The resulting catalog is no longer compliant with the self-contained catalog recommendations, but instead transforms into a 'relative published catalog'. With this, a client may resolve Item and sub-catalog self links by traversing parent and root links, but requires reading multiple sources to achieve this. @@ -605,17 +643,23 @@ with the `type` field) to communicate the structure and content of related entit Types](https://www.iana.org/assignments/link-relations/link-relations.xhtml) as much as possible. The following table describes a number of the common official relations that are used in production STAC implementations. -| Type | Description | -| ------------ | ------------------------------------------------------------ | +| Type | Description | +| --------- | ------------------------------------------------------------ | | alternate | It is recommended that STAC Items are also available as HTML, and should use this rel with `"type" : "text/html"` to tell clients where they can get a version of the Item or Collection to view in a browser. See [STAC on the Web in Best Practices](#stac-on-the-web) for more information. | | canonical | The URL of the [canonical](https://en.wikipedia.org/wiki/Canonical_link_element) version of the Item or Collection. API responses and copies of catalogs should use this to inform users that they are direct copy of another STAC Item, using the canonical rel to refer back to the primary location. | | via | The URL of the source metadata that this STAC Item or Collection is created from. Used similarly to canonical, but refers back to a non-STAC record (Landsat MTL, Sentinel tileInfo.json, etc) | -| prev | Indicates that the link's context is a part of a series, and that the previous in the series is the link target. Typically used in STAC by API's, to return smaller groups of Items or Catalogs. | -| next | Indicates that the link's context is a part of a series, and that the next in the series is the link target. Typically used in STAC by API's, to return smaller groups of Items or Catalogs. | +| prev | Indicates that the link's context is a part of a series, and that the previous in the series is the link target. Typically used in STAC by API's, to return smaller groups of Items or Catalogs/Collections. | +| next | Indicates that the link's context is a part of a series, and that the next in the series is the link target. Typically used in STAC by API's, to return smaller groups of Items or Catalogs/Collections. | +| preview | Refers to a resource that serves as a preview (see [RFC 6903, sec. 3](https://tools.ietf.org/html/rfc6903#section-3)), usually a lower resolution thumbnail. In STAC this would usually be the same URL as the [thumbnail](#thumbnail) asset, but adding it as a link in addition enables OGC API clients that can't read assets to make use of it. It also adds support for thumbnails to STAC Catalogs as they can't list assets. | + +Being liberal with the `links` also means that it's ok to have repeated links with the same `href`. For example the +`parent` and `root` relation types will point at the same file when the child is directly below the root, and it is +recommended to include both. ### Versioning for Catalogs -In the Item and Collection STAC JSON, versions and deprecation can be indicated with the [Versioning Indicators Extension](https://github.com/stac-extensions/version). +In the Item and Collection STAC JSON, versions and deprecation can be indicated with the +[Versioning Indicators Extension](https://github.com/stac-extensions/version). The [Items and Collections API Version Extension](https://github.com/stac-extensions/version/) provides endpoints and semantics for keeping and accessing previous versions of Collections and Items. The same semantics can be used in static @@ -634,12 +678,14 @@ cycle is repeated: #### Example -When the record `my_item.json` is created, a copy of it is also created. `my_item.json` includes `permalink` to `my_item_01.json`. The version suffix of the file name is taken from the version field of the record when it is available. +When the record `my_item.json` is created, a copy of it is also created. `my_item.json` includes `permalink` to `my_item_01.json`. +The version suffix of the file name is taken from the version field of the record when it is available. - `root / collections / example_collection / items / my_item / my_item.json` - `root / collections / example_collection / items / my_item / my_item_01.json` -When `my_item.json` is updated, the new `my_item.json` includes a link to `my_item_01.json` and is also copied to `my_item_02.json`. This ensures that `my_item_02.json` includes a link to `my_item_01.json` +When `my_item.json` is updated, the new `my_item.json` includes a link to `my_item_01.json` and is also copied to `my_item_02.json`. +This ensures that `my_item_02.json` includes a link to `my_item_01.json` - `root / collections / example_collection / items / my_item / my_item.json` - `root / collections / example_collection / items / my_item / my_item_01.json` @@ -667,9 +713,11 @@ as everything but the links should be the same. #### Keep catalogs in sync with cloud notification and queue services -There is a set of emerging practices to use services like Amazon's Simple Queue Service (SQS) and Simple Notification Service -(SNS) to keep catalogs in sync. There is a great [blog post on the CBERS STAC implementation on AWS](https://aws.amazon.com/blogs/publicsector/keeping-a-spatiotemporal-asset-catalog-stac-up-to-date-with-sns-sqs/). The core -idea is that a static catalog should emit a notification whenever it changes. The recommendation for SNS is to use the STAC +There is a set of emerging practices to use services like Amazon's Simple Queue Service (SQS) +and Simple Notification Service (SNS) to keep catalogs in sync. +There is a great [blog post](https://aws.amazon.com/blogs/publicsector/keeping-a-spatiotemporal-asset-catalog-stac-up-to-date-with-sns-sqs/) +on the CBERS STAC implementation on AWS. +The core idea is that a static catalog should emit a notification whenever it changes. The recommendation for SNS is to use the STAC Item JSON as the message body, with some fields such as a scene’s datetime and geographic bounding box that allows basic geographic filtering from listeners. @@ -680,8 +728,7 @@ database, but it could just as easily be a server-based process. ## How to Differentiate STAC Files Any tool that crawls a STAC implementation or encounters a STAC file in the wild needs a clear way to determine if it is an Item, -Collection, Catalog or [ItemCollection](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-beta.1/fragments/itemcollection) -(part of the [STAC API spec](https://github.com/radiantearth/stac-api-spec/tree/v1.0.0-beta.1)). As of 1.0.0 this is done primarily +Collection or Catalog. As of 1.0.0 this is done primarily with the `type` field, and secondarily in Items with `stac_version`, or optionally the `rel` of the link to it. ```shell @@ -691,8 +738,6 @@ else if type is 'Catalog' => Catalog else if type is 'Feature' and stac_version is defined => Item -else if type is 'FeatureCollection' and stac_version is defined - => ItemCollection else => Invalid (JSON) ``` diff --git a/catalog-spec/README.md b/catalog-spec/README.md index a2626d22..d70881b6 100644 --- a/catalog-spec/README.md +++ b/catalog-spec/README.md @@ -7,12 +7,20 @@ in the [STAC Catalog Specification](catalog-spec.md). For more information on how the parts of STAC fit together see the [overview](../overview.md) document. -A Catalog is typically the "entry point" into a STAC object hierarchy. For example, the root endpoint ("landing page") of a STAC API implementation is a Catalog. For many static STAC catalogs (e.g., those defined only by a set of files on disk or in a cloud object store), the root URL points to a Catalog that acts as the starting point to traverse the entire catalog of Catalog, Collection, and Item objects. +A Catalog is typically the "entry point" into a STAC object hierarchy. +For example, the root endpoint ("landing page") of a STAC API implementation is a Catalog. +For many static STAC catalogs (e.g., those defined only by a set of files on disk or in a cloud object store), +the root URL points to a Catalog that acts as the starting point to traverse the entire catalog of Catalog, Collection, and Item objects. -While STAC Catalogs mostly describe a structure of links and Items, a key related specification is the [STAC Collection Specification](../collection-spec/collection-spec.md), +While STAC Catalogs mostly describe a structure of links and Items, +a key related specification is the [STAC Collection Specification](../collection-spec/collection-spec.md), which contains fields that further describe the group of Items in a Catalog. -A STAC Catalog requires a subset of the fields required by a Collection. These are distinguished from one another by the `type` field, which will have the value `Catalog` or `Collection`. This means that a Collection can be changed to a Catalog simply by changing this `type` field. The parent-child relationships among Catalogs and Collections are for objects of these types, as there is no subtyping relationship between the Collection and Catalog types, even through they share field names. +A STAC Catalog requires a subset of the fields required by a Collection. +These are distinguished from one another by the `type` field, which will have the value `Catalog` or `Collection`. +This means that a Collection can be changed to a Catalog simply by changing this `type` field. +The parent-child relationships among Catalogs and Collections are for objects of these types, +as there is no subtyping relationship between the Collection and Catalog types, even through they share field names. Catalogs are designed so that a simple file server on the web or object store like Amazon S3 can store JSON that defines a full Catalog. More dynamic services can also return a Catalog structure, and the [STAC API](https://github.com/radiantearth/stac-api-spec) diff --git a/catalog-spec/catalog-spec.md b/catalog-spec/catalog-spec.md index 032d85a3..8b26dce0 100644 --- a/catalog-spec/catalog-spec.md +++ b/catalog-spec/catalog-spec.md @@ -36,8 +36,9 @@ and fields to be compliant. This Catalog specification primarily defines a structure for information to be discoverable. Any use that is publishing a set of related spatiotemporal assets is strongly recommended to also use the STAC Collection specification to provide additional information about the set of Items -contained in a Catalog, in order to give contextual information to aid in discovery. Every STAC Collection is -also a valid STAC Catalog. +contained in a Catalog, in order to give contextual information to aid in discovery. +STAC Collections all have the same fields as STAC Catalogs, but with different allowed +values for `type` and `stac_extensions`. ## Catalog fields @@ -49,7 +50,6 @@ also a valid STAC Catalog. | id | string | **REQUIRED.** Identifier for the Catalog. | | title | string | A short descriptive one-line title for the Catalog. | | description | string | **REQUIRED.** Detailed multi-line description to fully explain the Catalog. [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for rich text representation. | -| summaries | Map | A map of property summaries, either a set of values or statistics such as a range. More info in the [Collection spec](../collection-spec/collection-spec.md#summaries). | | links | [[Link Object](#link-object)] | **REQUIRED.** A list of references to other documents. | ### Additional Field Information @@ -61,9 +61,10 @@ In general, STAC versions can be mixed, but please keep the [recommended best pr #### stac_extensions A list of extensions the Catalog implements. -This list must only contain extensions that extend the Catalog itself, see the the 'Scope' column in the list of -extensions. This does NOT declare the extensions of child Catalog, Collection, or Item -objects. The list contains URLs to the JSON Schema files it can be validated against. +The list consists of URLs to JSON Schema files that can be used for validation. +This list must only contain extensions that extend the Catalog specification itself, +see the 'Scope' for each of the extensions. +This must **not** declare the extensions that are only implemented in child Collection objects or child Item objects. ### Link Object @@ -88,11 +89,12 @@ The following types are commonly used as `rel` types in the Link Object of a STA | ------- | ----------- | | self | STRONGLY RECOMMENDED. *Absolute* URL to the location that the Catalog file can be found online, if available. This is particularly useful when in a download package that includes metadata, so that the downstream user can know where the data has come from. | | root | STRONGLY RECOMMENDED. URL to the root STAC Catalog or [Collection](../collection-spec/README.md). Catalogs should include a link to their root, even if it's the root and points to itself. | -| parent | URL to the parent STAC Catalog or Collection. Non-root Catalogs should include a link to their parent. | -| child | URL to a child STAC Catalog or Collection. | +| parent | URL to the parent STAC entity (Catalog or Collection). Non-root Catalogs should include a link to their parent. | +| child | URL to a child STAC entity (Catalog or Collection). | | item | URL to a STAC Item. | -**Note:** A link to at least one `item` or `child` Catalog is **REQUIRED**. +**Note:** A link to at least one `item` or `child` (Catalog or Collection) is **RECOMMENDED**, but empty catalogs are +allowed if there is an intent to populate it or its children were removed. There are additional `rel` types in the [Using Relation Types](../best-practices.md#using-relation-types) best practice, but as they are more typically used in Collections, as Catalogs tend to just be used to structure STAC organization, so tend to just use diff --git a/catalog-spec/json-schema/catalog-core.json b/catalog-spec/json-schema/catalog-core.json deleted file mode 100644 index 503d7a66..00000000 --- a/catalog-spec/json-schema/catalog-core.json +++ /dev/null @@ -1,139 +0,0 @@ -{ - "$schema": "http://json-schema.org/draft-07/schema#", - "$id": "https://schemas.stacspec.org/v1.0.0-rc.2/catalog-spec/json-schema/catalog-core.json#", - "title": "Common STAC Catalog + Collection Fields", - "description": "This object represents the common fields shared by Catalogs and Collections", - "allOf": [ - { - "$ref": "#/definitions/catalogCore" - } - ], - "definitions": { - "catalogCore": { - "title": "Catalog Core Fields", - "type": "object", - "required": [ - "stac_version", - "id", - "description", - "links" - ], - "properties": { - "stac_version": { - "title": "STAC version", - "type": "string", - "const": "1.0.0-rc.2" - }, - "stac_extensions": { - "title": "STAC extensions", - "type": "array", - "uniqueItems": true, - "items": { - "anyOf": [ - { - "title": "Reference to a JSON Schema", - "type": "string", - "format": "iri" - }, - { - "title": "Reference to a core extension", - "type": "string" - } - ] - } - }, - "id": { - "title": "Identifier", - "type": "string", - "minLength": 1 - }, - "title": { - "title": "Title", - "type": "string" - }, - "description": { - "title": "Description", - "type": "string", - "minLength": 1 - }, - "links": { - "title": "Links", - "type": "array", - "items": { - "$ref": "#/definitions/link" - } - }, - "summaries": { - "$ref": "#/definitions/summaries" - } - } - }, - "link": { - "type": "object", - "required": [ - "rel", - "href" - ], - "properties": { - "href": { - "title": "Link reference", - "type": "string", - "format": "iri-reference", - "minLength": 1 - }, - "rel": { - "title": "Link relation type", - "type": "string", - "minLength": 1 - }, - "type": { - "title": "Link type", - "type": "string" - }, - "title": { - "title": "Link title", - "type": "string" - } - } - }, - "summaries": { - "type": "object", - "additionalProperties": { - "oneOf": [ - { - "title": "Stats", - "type": "object", - "required": [ - "minimum", - "maximum" - ], - "properties": { - "minimum": { - "title": "Minimum value", - "type": [ - "number", - "string" - ] - }, - "maximum": { - "title": "Maximum value", - "type": [ - "number", - "string" - ] - } - } - }, - { - "title": "Set of values", - "type": "array", - "minItems": 1, - "items": { - "description": "Any data type could occur." - } - } - ] - } - } - } -} \ No newline at end of file diff --git a/catalog-spec/json-schema/catalog.json b/catalog-spec/json-schema/catalog.json index 0f2c110f..31b2c8f8 100644 --- a/catalog-spec/json-schema/catalog.json +++ b/catalog-spec/json-schema/catalog.json @@ -1,27 +1,92 @@ { "$schema": "http://json-schema.org/draft-07/schema#", - "$id": "https://schemas.stacspec.org/v1.0.0-rc.2/catalog-spec/json-schema/catalog.json#", + "$id": "https://schemas.stacspec.org/v1.0.0/catalog-spec/json-schema/catalog.json#", "title": "STAC Catalog Specification", "description": "This object represents Catalogs in a SpatioTemporal Asset Catalog.", "allOf": [ - { - "$ref": "catalog-core.json" - }, { "$ref": "#/definitions/catalog" } ], "definitions": { "catalog": { - "title": "Catalog", + "title": "STAC Catalog", "type": "object", "required": [ - "type" + "stac_version", + "type", + "id", + "description", + "links" ], "properties": { + "stac_version": { + "title": "STAC version", + "type": "string", + "const": "1.0.0" + }, + "stac_extensions": { + "title": "STAC extensions", + "type": "array", + "uniqueItems": true, + "items": { + "title": "Reference to a JSON Schema", + "type": "string", + "format": "iri" + } + }, "type": { "title": "Type of STAC entity", "const": "Catalog" + }, + "id": { + "title": "Identifier", + "type": "string", + "minLength": 1 + }, + "title": { + "title": "Title", + "type": "string" + }, + "description": { + "title": "Description", + "type": "string", + "minLength": 1 + }, + "links": { + "title": "Links", + "type": "array", + "items": { + "$ref": "#/definitions/link" + } + } + } + }, + "link": { + "type": "object", + "required": [ + "rel", + "href" + ], + "properties": { + "href": { + "title": "Link reference", + "type": "string", + "format": "iri-reference", + "minLength": 1 + }, + "rel": { + "title": "Link relation type", + "type": "string", + "minLength": 1 + }, + "type": { + "title": "Link type", + "type": "string" + }, + "title": { + "title": "Link title", + "type": "string" } } } diff --git a/collection-spec/README.md b/collection-spec/README.md index 6b5a0233..c94bfc31 100644 --- a/collection-spec/README.md +++ b/collection-spec/README.md @@ -28,7 +28,8 @@ document. ## In this directory -**Specification:** The main STAC Collection specification is in *[collection-spec.md](collection-spec.md)*. It includes an overview and in depth explanation of the +**Specification:** The main STAC Collection specification is in *[collection-spec.md](collection-spec.md)*. +It includes an overview and in depth explanation of the structures and fields. **Schemas:** The schemas to validate the STAC Collection definition are found in the @@ -37,7 +38,9 @@ structures and fields. ## Collection Flexibility STAC Collections are defined for flexibility. They only require a handful of fields, and -implementors are free to add most any JSON field or object that they want via extensions. This flexibility and extensibility is a design goal, so that it is quite easy to implement a collection and be able to adapt it to most any data model. +implementors are free to add most any JSON field or object that they want via extensions. +This flexibility and extensibility is a design goal, so that it is quite easy to implement +a collection and be able to adapt it to most any data model. Implementors are encouraged to do what makes sense for them, and to check out the [examples](../examples/) and [other implementations](https://stacindex.org/catalogs) for current best practices. diff --git a/collection-spec/collection-spec.md b/collection-spec/collection-spec.md index f781bb91..8b6f4f15 100644 --- a/collection-spec/collection-spec.md +++ b/collection-spec/collection-spec.md @@ -16,7 +16,8 @@ - [Link Object](#link-object) - [Relation types](#relation-types) - [Asset Object](#asset-object) - - [Stats Object](#stats-object) + - [Range Object](#range-object) + - [JSON Schema Object](#json-schema-object) - [Media Type for STAC Collections](#media-type-for-stac-collections) - [Standalone Collections](#standalone-collections) @@ -27,17 +28,18 @@ Collection Specification shares all fields with the STAC [Catalog Specification] values for `type` and `stac_extensions`) and adds fields to describe the whole dataset and the included set of Items. Collections can have both parent Catalogs and Collections and child Items, Catalogs and Collections. -A STAC Collection is represented in JSON format. Any JSON object that contains all the required fields is a valid STAC Collection and also a valid STAC Catalog. +A STAC Collection is represented in JSON format. +Any JSON object that contains all the required fields is a valid STAC Collection and also a valid STAC Catalog. STAC Collections are compatible with the [Collection](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#example_4) JSON specified in [*OGC API - Features*](https://ogcapi.ogc.org/features/), but they are extended with additional fields. -* [Examples](../examples/): - * Sentinel 2: A basic standalone example of a [Collection](../examples/collection-only/collection.json) without Items. - * Simple Example: A [Collection](../examples/collection.json) that links to 3 example Items. - * Extension Collection: An additional [Collection](../examples/extensions-collection/collection.json), which is used to highlight +- [Examples](../examples/): + - Sentinel 2: A basic standalone example of a [Collection](../examples/collection-only/collection.json) without Items. + - Simple Example: A [Collection](../examples/collection.json) that links to 3 example Items. + - Extension Collection: An additional [Collection](../examples/extensions-collection/collection.json), which is used to highlight various [extension](../extensions) functionality, but serves as another example. -* [JSON Schema](json-schema/collection.json) +- [JSON Schema](json-schema/collection.json) ## Collection fields @@ -53,7 +55,7 @@ specified in [*OGC API - Features*](https://ogcapi.ogc.org/features/), but they | license | string | **REQUIRED.** Collection's license(s), either a SPDX [License identifier](https://spdx.org/licenses/), `various` if multiple licenses apply or `proprietary` for all other cases. | | providers | \[[Provider Object](#provider-object)] | A list of providers, which may include all organizations capturing or processing the data or the hosting provider. Providers should be listed in chronological order with the most recent provider being the last element of the list. | | extent | [Extent Object](#extent-object) | **REQUIRED.** Spatial and temporal extents. | -| summaries | Map | STRONGLY RECOMMENDED. A map of property summaries, either a set of values or statistics such as a range. | +| summaries | Map | STRONGLY RECOMMENDED. A map of property summaries, either a set of values, a range of values or a [JSON Schema](https://json-schema.org). | | links | \[[Link Object](#link-object)] | **REQUIRED.** A list of references to other documents. | | assets | Map | Dictionary of asset objects that can be downloaded, each with a unique key. | @@ -65,16 +67,11 @@ In general, STAC versions can be mixed, but please keep the [recommended best pr #### stac_extensions -A list of extensions the Collection implements. -This list must only contain extensions that extend the Collection itself, see the the 'Scope' column in the list of -extensions. This does NOT declare the extensions of child Collection or Item -objects. The list contains URLs to the JSON Schema files it can be validated against. - -If an extension has influence on multiple parts -of the whole STAC structure, it must be listed in all affected parts (e.g. Collection and Item for the `datacube` extension). -If a structure, such as the summaries extension, provides fields in their JSON structure, these extensions must not be listed -here as they don't extend the Collection itself. For example, if a Collection includes the field `sat:platform` in the -summaries, the Collection should not list the `sat` extension in the `stac_extensions` field. +A list of extensions the Collection implements. +The list consists of URLs to JSON Schema files that can be used for validation. +This list must only contain extensions that extend the Collection specification itself, +see the the 'Scope' for each of the extensions. +This must **not** declare the extensions that are only implemented in child Collection objects or child Item objects. #### id @@ -84,24 +81,45 @@ it is a fairly unique name, or their name combined with the domain they operate #### license -Collection's license(s) as a SPDX [License identifier](https://spdx.org/licenses/). Alternatively, use `proprietary` (see below) if the license is not on the SPDX license list or `various` if multiple licenses apply. In all cases links to the license texts SHOULD be added, see the `license` link relation type. If no link to a license is included and the `license` field is set to `proprietary`, the Collection is private, and consumers have not been granted any explicit right to use the data. +Collection's license(s) as a SPDX [License identifier](https://spdx.org/licenses/). +Alternatively, use `proprietary` (see below) if the license is not on the SPDX license list or `various` if multiple licenses apply. +In all cases links to the license texts SHOULD be added, see the `license` link relation type. +If no link to a license is included and the `license` field is set to `proprietary`, the Collection is private, +and consumers have not been granted any explicit right to use the data. #### summaries Collections are *strongly recommended* to provide summaries of the values of fields that they can expect from the `properties` of STAC Items contained in this Collection. This enables users to get a good sense of what the ranges and potential values of -different fields in the Collection are, without to inspect a number of Items (or crawl them exhaustively to get a definitive answer). -Summaries help to fully define Collections, especially if they don't link to any Items. They also give clients enough information to -build tailored user interfaces for querying the data, by presenting the potential values that are available. Summaries should summarize all values in every Item underneath the collection, including in any nested sub-Catalogs. - -A summary for a field can be specified in two ways: - -1. A set of all distinct values in an array: The set of values must contain at least one element and it is strongly recommended to list all values. If the field summarizes an array (e.g. [`instruments`](../item-spec/common-metadata.md#instrument)), the field's array elements of each Item must be merged to a single array with unique elements. -2. Statistics in a [Stats Object](#stats-object): Statistics by default only specify the range (minimum and maximum values), but can optionally be accompanied by additional statistical values. The range specified by the `minimum` and `maximum` properties can specify the potential range of values, but it is recommended to be as precise as possible. - -All values must follow the schema of the property they summarize. So the values in the array or the values given for `minimum` and `maxmimum` must comply to the original data type and any further restrictions that apply for the property they summarize. For example, the `minimum` for `gsd` can't be lower than zero and the summaries for `platform` and `instruments` must each be an array of strings (or alternatively minimum and maximum values, but that's not very meaningful). - -It is recommended to list as many properties as reasonable so that consumers get a full overview about the properties included in the Items. Nevertheless, it is not very useful to list all potential `title` values of the Items. Also, a range for the `datetime` property may be better suited to be included in the STAC Collection's `extent` field. In general, properties that are covered by the Collection specification should not be repeated in the summaries. +different fields in the Collection are, without having to inspect a number of Items (or crawl them exhaustively to get a definitive answer). +Summaries are often used to give users a sense of the data in [Standalone Collections](#standalone-collections), +describing the potential values even when it can't be accessed as Items. They also give clients enough information to +build tailored user interfaces for querying the data, by presenting the potential values that are available. + Fields selected to be included in summaries should capture all the potential values of the + field that appear in every Item underneath the collection, including in any nested sub-Catalogs. + +A summary for a field can be specified in three ways: + +1. A set of all distinct values in an array: The set of values must contain at least one element and it is strongly recommended to list all values. + If the field summarizes an array (e.g. [`instruments`](../item-spec/common-metadata.md#instrument)), + the field's array elements of each Item must be merged to a single array with unique elements. +2. A Range in a [Range Object](#range-object): Statistics by default only specify the range (minimum and maximum values), + but can optionally be accompanied by additional statistical values. + The range specified by the `minimum` and `maximum` properties can specify the potential range of values, + but it is recommended to be as precise as possible. +3. Extensible JSON Schema definitions for fine-grained information, see the [JSON Schema Object](#json-schema-object) + section for more. + +All values must follow the schema of the property field they summarize, unless the field is an array as described in (1) above. +So the values in the array or the values given for `minimum` and `maximum` must comply to the original data type +and any further restrictions that apply for the property they summarize. +For example, the `minimum` for `gsd` can't be lower than zero and the summaries for `platform` and `instruments` +must each be an array of strings (or alternatively minimum and maximum values, but that's not very meaningful). + +It is recommended to list as many properties as reasonable so that consumers get a full overview about the properties included in the Items. +Nevertheless, it is not very useful to list all potential `title` values of the Items. +Also, a range for the `datetime` property may be better suited to be included in the STAC Collection's `extent` field. +In general, properties that are covered by the Collection specification should not be repeated in the summaries. See the [examples folder](../examples) for Collections with summaries to get a sense of how to use them. @@ -118,13 +136,16 @@ The definition provided here, at the Collection level, is the same as the There are a few guidelines for using the asset construct at the Collection level: -* Collection-level assets SHOULD NOT list any files also available in Items. -* If possible, item-level assets are always the preferable way to expose assets. +- Collection-level assets SHOULD NOT list any files also available in Items. +- If possible, item-level assets are always the preferable way to expose assets. Collection-level assets can be useful in some scenarios, for example: -1. Exposing additional data that applies Collection-wide and you don't want to expose it in each Item. This can be Collection-level metadata or a thumbnail for visualization purposes. -2. Individual Items can't properly be distinguished for some data structures, e.g. [Zarr](https://zarr.readthedocs.io/) as it's a data structure not contained in single files. -3. Exposing assets for "[Standalone Collections](https://github.com/radiantearth/stac-spec/blob/master/collection-spec/collection-spec.md#standalone-collections)". +1. Exposing additional data that applies Collection-wide and you don't want to expose it in each Item. + This can be Collection-level metadata or a thumbnail for visualization purposes. +2. Individual Items can't properly be distinguished for some data structures, + e.g. [Zarr](https://zarr.readthedocs.io/) as it's a data structure not contained in single files. +3. Exposing assets for + "[Standalone Collections](https://github.com/radiantearth/stac-spec/blob/master/collection-spec/collection-spec.md#standalone-collections)". Oftentimes it is possible to model data and assets with either a Collection or an Item. In those scenarios we *recommend* to use Items as much as is feasible, as they designed for assets. Using Collection-level assets should only be used if there is not another @@ -147,11 +168,24 @@ The object describes the spatial extents of the Collection. | ------- | ------------ | -------------------------------------------------------------------- | | bbox | \[\[number]] | **REQUIRED.** Potential *spatial extents* covered by the Collection. | -**bbox**: Bounding Boxes of the assets represented by this Collection using either 2D or 3D geometries. Each outer array element can be a separate bounding box, but it is recommended to only use multiple bounding boxes if a union of them would then include a large uncovered area (e.g. the union of Germany and Chile). +**bbox**: Each outer array element can be a separate spatial extent describing the bounding boxes +of the assets represented by this Collection using either 2D or 3D geometries. + +The first bounding box always describes the overall spatial extent of the data. All subsequent bounding boxes can be +used to provide a more precise description of the extent and identify clusters of data. +Clients only interested in the overall spatial extent will only need to access the first item in each array. +It is recommended to only use multiple bounding boxes if a union of them would then include +a large uncovered area (e.g. the union of Germany and Chile). -The length of the inner array must be 2*n where n is the number of dimensions. The array contains all axes of the southwesterly most extent followed by all axes of the northeasterly most extent specified in Longitude/Latitude or Longitude/Latitude/Elevation based on [WGS 84](http://www.opengis.net/def/crs/OGC/1.3/CRS84). When using 3D geometries, the elevation of the southwesterly most extent is the minimum depth/height in meters and the elevation of the northeasterly most extent is the maximum. +The length of the inner array must be 2*n where n is the number of dimensions. +The array contains all axes of the southwesterly most extent followed by all axes of the northeasterly most extent specified in +Longitude/Latitude or Longitude/Latitude/Elevation based on [WGS 84](http://www.opengis.net/def/crs/OGC/1.3/CRS84). +When using 3D geometries, the elevation of the southwesterly most extent is the minimum depth/height in meters +and the elevation of the northeasterly most extent is the maximum. -The coordinate reference system of the values is WGS 84 longitude/latitude. Example that covers the whole Earth: `[[-180.0, -90.0, 180.0, 90.0]]`. Example that covers the whole earth with a depth of 100 meters to a height of 150 meters: `[[-180.0, -90.0, -100.0, 180.0, 90.0, 150.0]]`. +The coordinate reference system of the values is WGS 84 longitude/latitude. +Example that covers the whole Earth: `[[-180.0, -90.0, 180.0, 90.0]]`. +Example that covers the whole earth with a depth of 100 meters to a height of 150 meters: `[[-180.0, -90.0, -100.0, 180.0, 90.0, 150.0]]`. #### Temporal Extent Object @@ -161,15 +195,31 @@ The object describes the temporal extents of the Collection. | -------- | ------------------ | --------------------------------------------------------------------- | | interval | \[\[string\|null]] | **REQUIRED.** Potential *temporal extents* covered by the Collection. | -**interval**: Each outer array element can be a separate temporal extent, but it is recommended to only use multiple temporal extents if a union of them would then include a large uncovered time span (e.g. only having data for the years 2000, 2010 and 2020). +**interval**: Each outer array element can be a separate temporal extent. +The first time interval always describes the overall temporal extent of the data. All subsequent time intervals +can be used to provide a more precise description of the extent and identify clusters of data. +Clients only interested in the overall extent will only need to access the first item in each array. +It is recommended to only use multiple temporal extents if a union of them would then include a large +uncovered time span (e.g. only having data for the years 2000, 2010 and 2020). -Each inner array consists of exactly two dates and times. Each date and time MUST be formatted according to [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6). The temporal reference system is the Gregorian calendar. +Each inner array consists of exactly two elements, either a timestamp or `null`. -Open date ranges are supported by setting either the start or the end time to `null`. Example for data from the beginning of 2019 until now: `[["2009-01-01T00:00:00Z", null]]`. +Timestamps consist of a date and time in UTC and MUST be formatted according to +[RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6). +The temporal reference system is the Gregorian calendar. + +Open date ranges are supported by setting the start and/or the end time to `null`. +Example for data from the beginning of 2019 until now: `[["2019-01-01T00:00:00Z", null]]`. +It is recommended to provide at least a rough guideline on the temporal extent and thus +it's not recommended to set both start and end time to `null`. Nevertheless, this is possible +if there's a strong use case for an open date range to both sides. ### Provider Object -The object provides information about a provider. A provider is any of the organizations that captures or processes the content of the Collection and therefore influences the data offered by this Collection. May also include information about the final storage provider hosting the data. +The object provides information about a provider. +A provider is any of the organizations that captures or processes the content of the Collection +and therefore influences the data offered by this Collection. +May also include information about the final storage provider hosting the data. | Field Name | Type | Description | | ----------- | --------- | ------------------------------------------------------------ | @@ -180,10 +230,11 @@ The object provides information about a provider. A provider is any of the organ **roles**: The provider's role(s) can be one or more of the following elements: -* *licensor*: The organization that is licensing the dataset under the license specified in the Collection's `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. -* *processor*: A processor is any provider who processed data to a derived product. -* *host*: The host is the actual provider offering the data on their storage. There should be no more than one host, specified as last element of the list. +- *licensor*: The organization that is licensing the dataset under 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. +- *processor*: A processor is any provider who processed data to a derived product. +- *host*: The host is the actual provider offering the data on their storage. + There should be no more than one host, specified as last element of the list. ### Link Object @@ -201,24 +252,30 @@ For a full discussion of the situations where relative and absolute links are re #### Relation types -STAC Collections use a variety of `rel` types in the link object, to describe the exact nature of the link between this Collection and the entity it is linking to. -It is recommended to use the official [IANA Link Relation Types](https://www.iana.org/assignments/link-relations/link-relations.xhtml) where possible. +STAC Collections use a variety of `rel` types in the link object, +to describe the exact nature of the link between this Collection and the entity it is linking to. +It is recommended to use the official +[IANA Link Relation Types](https://www.iana.org/assignments/link-relations/link-relations.xhtml) where possible. The following table explains places where custom STAC `rel` types are used for ollections. This is done where there is not a clear official option, or where STAC uses an official type but adds additional meaning for the STAC context. | Type | Description | | ------- | ------------------------------------------------------------ | | self | STRONGLY RECOMMENDED. *Absolute* URL to the location that the Collection file can be found online, if available. This is particularly useful when in a download package that includes metadata, so that the downstream user can know where the data has come from. | -| root | URL to the root STAC Catalog or Collection. Collections should include a link to their root, even if it's the root and points to itself. | -| parent | URL to the parent STAC Catalog or Collection. Non-root Collections should include a link to their parent. | -| child | URL to a child STAC Catalog or Collection. | +| root | URL to the root STAC entity (Catalog or Collection). Collections should include a link to their root, even if it's the root and points to itself. | +| parent | URL to the parent STAC entity (Catalog or Collection). Non-root Collections should include a link to their parent. | +| child | URL to a child STAC entity (Catalog or Collection). | | item | URL to a STAC Item. All Items linked from a Collection MUST refer back to its Collection with the [`collection` relation type](../item-spec/item-spec.md#relation-types). | | license | The license URL(s) for the Collection SHOULD be specified if the `license` field is set to `proprietary` or `various`. If there is no public license URL available, it is RECOMMENDED to put the license text in a separate file and link to this file. | | derived_from | URL to a STAC Collection that was used as input data in the creation of this Collection. See the note in [STAC Item](../item-spec/item-spec.md#derived_from) for more info. | -A more complete list of possible `rel` types and their meaning in STAC can be found in the [Using Relation Types](../best-practices.md#using-relation-types) best practice. +A more complete list of possible `rel` types and their meaning in STAC can be found in the +[Using Relation Types](../best-practices.md#using-relation-types) best practice. -**Note:** The STAC Catalog specification requires a link to at least one `item` or `child` Catalog. This is *not* a requirement for Collections, but *recommended*. In contrast to Catalogs, it is **REQUIRED** that Items linked from a Collection MUST refer back to its Collection with the [`collection` relation type](../item-spec/item-spec.md#relation-types). +**Note:** The STAC Catalog specification requires a link to at least one `item` or `child` Catalog. +This is *not* a requirement for Collections, but *recommended*. In contrast to Catalogs, +it is **REQUIRED** that Items linked from a Collection MUST refer back to its Collection +with the [`collection` relation type](../item-spec/item-spec.md#relation-types). ### Asset Object @@ -234,10 +291,12 @@ or streamed. The definition provided here, at the Collection level, is the same | type | string | [Media type](../item-spec/item-spec.md#asset-media-type) of the asset. See the [common media types](../best-practices.md#common-media-types-in-stac) in the best practice doc for commonly used asset types. | | roles | \[string] | The [semantic roles](../item-spec/item-spec.md#asset-role-types) of the asset, similar to the use of `rel` in links. | -### Stats Object +### Range Object -For a good understanding of the summarized field, statistics can be added. By default, only ranges with a minimum and a maximum value can be specified. -Ranges can be specified for [ordinal](https://en.wikipedia.org/wiki/Level_of_measurement#Ordinal_scale) values only, which means they need to have a rank order. +For summaries that would normally consist of a lot of continuous values, statistics can be added instead. +By default, only ranges with a minimum and a maximum value can be specified. +Ranges can be specified for [ordinal](https://en.wikipedia.org/wiki/Level_of_measurement#Ordinal_scale) 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`. @@ -246,6 +305,17 @@ Implementors are free to add other derived statistical values to the object, for | minimum | number\|string | **REQUIRED.** Minimum value. | | maximum | number\|string | **REQUIRED.** Maximum value. | +### JSON Schema Object + +For a full understanding of the summarized field, a JSON Schema can be added for each summarized field. +This allows very fine-grained information for each field and each value as JSON Schema is also extensible. +Each schema must be valid against all corresponding values available for the property in the sub-Items. + +It is recommended to use [JSON Schema draft-07](https://json-schema.org/specification-links.html#draft-7) +to align with the JSON Schemas provided by STAC. Empty schemas are not allowed. + +For an introduction to JSON Schema, see "[Learn JSON Schema](https://json-schema.org/learn/)". + ## Media Type for STAC Collections A STAC Collection is a JSON file ([RFC 8259](https://tools.ietf.org/html/rfc8259)), and thus should use the @@ -255,6 +325,8 @@ A STAC Collection is a JSON file ([RFC 8259](https://tools.ietf.org/html/rfc8259 ## Standalone Collections STAC Collections which don't link to any Item are called **standalone Collections**. -To describe them with more fields than the Collection fields has to offer, it is allowed to re-use the metadata fields defined by extensions for Items in the `summaries` field. -This makes much sense for fields such as `platform` or `proj:epsg`, which are often the same for a whole Collection, but doesn't make much sense for `eo:cloud_cover`, which usually varies heavily across a Collection. +To describe them with more fields than the Collection fields has to offer, +it is allowed to re-use the metadata fields defined by extensions for Items in the `summaries` field. +This makes much sense for fields such as `platform` or `proj:epsg`, which are often the same for a whole Collection, +but doesn't make much sense for `eo:cloud_cover`, which usually varies heavily across a Collection. The data provider is free to decide, which fields are reasonable to be used. diff --git a/collection-spec/json-schema/collection.json b/collection-spec/json-schema/collection.json index 422385f2..2ad20902 100644 --- a/collection-spec/json-schema/collection.json +++ b/collection-spec/json-schema/collection.json @@ -1,12 +1,9 @@ { "$schema": "http://json-schema.org/draft-07/schema#", - "$id": "https://schemas.stacspec.org/v1.0.0-rc.2/collection-spec/json-schema/collection.json#", + "$id": "https://schemas.stacspec.org/v1.0.0/collection-spec/json-schema/collection.json#", "title": "STAC Collection Specification", "description": "This object represents Collections in a SpatioTemporal Asset Catalog.", "allOf": [ - { - "$ref": "../../catalog-spec/json-schema/catalog-core.json" - }, { "$ref": "#/definitions/collection" } @@ -17,33 +14,48 @@ "description": "These are the fields specific to a STAC Collection. All other fields are inherited from STAC Catalog.", "type": "object", "required": [ + "stac_version", "type", + "id", + "description", "license", - "extent" + "extent", + "links" ], "properties": { - "type": { - "title": "Type of STAC entity", - "const": "Collection" + "stac_version": { + "title": "STAC version", + "type": "string", + "const": "1.0.0" }, "stac_extensions": { "title": "STAC extensions", "type": "array", "uniqueItems": true, "items": { - "anyOf": [ - { - "title": "Reference to a JSON Schema", - "type": "string", - "format": "iri" - }, - { - "title": "Reference to a core extension", - "type": "string" - } - ] + "title": "Reference to a JSON Schema", + "type": "string", + "format": "iri" } }, + "type": { + "title": "Type of STAC entity", + "const": "Collection" + }, + "id": { + "title": "Identifier", + "type": "string", + "minLength": 1 + }, + "title": { + "title": "Title", + "type": "string" + }, + "description": { + "title": "Description", + "type": "string", + "minLength": 1 + }, "keywords": { "title": "Keywords", "type": "array", @@ -153,7 +165,8 @@ "string", "null" ], - "format": "date-time" + "format": "date-time", + "pattern": "(\\+00:00|Z)$" } } } @@ -163,8 +176,95 @@ }, "assets": { "$ref": "../../item-spec/json-schema/item.json#/definitions/assets" + }, + "links": { + "title": "Links", + "type": "array", + "items": { + "$ref": "#/definitions/link" + } + }, + "summaries": { + "$ref": "#/definitions/summaries" } } + }, + "link": { + "type": "object", + "required": [ + "rel", + "href" + ], + "properties": { + "href": { + "title": "Link reference", + "type": "string", + "format": "iri-reference", + "minLength": 1 + }, + "rel": { + "title": "Link relation type", + "type": "string", + "minLength": 1 + }, + "type": { + "title": "Link type", + "type": "string" + }, + "title": { + "title": "Link title", + "type": "string" + } + } + }, + "summaries": { + "type": "object", + "additionalProperties": { + "anyOf": [ + { + "title": "JSON Schema", + "type": "object", + "minProperties": 1, + "allOf": [ + { + "$ref": "http://json-schema.org/draft-07/schema" + } + ] + }, + { + "title": "Range", + "type": "object", + "required": [ + "minimum", + "maximum" + ], + "properties": { + "minimum": { + "title": "Minimum value", + "type": [ + "number", + "string" + ] + }, + "maximum": { + "title": "Maximum value", + "type": [ + "number", + "string" + ] + } + } + }, + { + "title": "Set of values", + "type": "array", + "minItems": 1, + "items": { + "description": "For each field only the original data type of the property can occur (except for arrays), but we can't validate that in JSON Schema yet. See the sumamry description in the STAC specification for details." + } + } + ] + } } } } \ No newline at end of file diff --git a/examples/README.md b/examples/README.md index 85b5f5a1..a4d046a9 100644 --- a/examples/README.md +++ b/examples/README.md @@ -1,6 +1,8 @@ # STAC Examples -This directory contains various examples for all parts of the STAC specification. It is structured to be two valid STACs, meaning both [catalog.json](catalog.json) and [collection.json](collection.json) should successfully load in various tools. They do not follow *all* the [best practices](../best-practices.md) for STAC, mostly +This directory contains various examples for all parts of the STAC specification. +It is structured to be two valid STACs, meaning both [catalog.json](catalog.json) and [collection.json](collection.json) +should successfully load in various tools. They do not follow *all* the [best practices](../best-practices.md) for STAC, mostly due to the fact that they contrive examples to show the spec and we are hosting in GitHub. But we note below where they differ from an ideal catalog. The various fields are mostly fictional, to be able to demonstrate the various aspects of the spec as tersely as possible. To get a sense diff --git a/examples/catalog.json b/examples/catalog.json index 1bac09f9..b5910be3 100644 --- a/examples/catalog.json +++ b/examples/catalog.json @@ -1,7 +1,8 @@ { "id": "examples", "type": "Catalog", - "stac_version": "1.0.0-rc.2", + "title": "Example Catalog", + "stac_version": "1.0.0", "description": "This catalog is a simple demonstration of an example catalog that is used to organize a hierarchy of collections and their items.", "links": [ { @@ -21,9 +22,21 @@ "type": "application/json", "title": "Collection with no items (standalone)" }, + { + "rel": "child", + "href": "./collection-only/collection-with-schemas.json", + "type": "application/json", + "title": "Collection with no items (standalone with JSON Schemas)" + }, + { + "rel": "item", + "href": "./collectionless-item.json", + "type": "application/json", + "title": "Collection with no items (standalone)" + }, { "rel": "self", - "href": "https://raw.githubusercontent.com/radiantearth/stac-spec/v1.0.0-rc.2/examples/catalog.json", + "href": "https://raw.githubusercontent.com/radiantearth/stac-spec/v1.0.0/examples/catalog.json", "type": "application/json" } ] diff --git a/examples/collection-only/collection-with-schemas.json b/examples/collection-only/collection-with-schemas.json new file mode 100644 index 00000000..e0023e23 --- /dev/null +++ b/examples/collection-only/collection-with-schemas.json @@ -0,0 +1,277 @@ +{ + "stac_version": "1.0.0", + "stac_extensions": [ + "https://stac-extensions.github.io/eo/v1.0.0/schema.json", + "https://stac-extensions.github.io/sat/v1.0.0/schema.json", + "https://stac-extensions.github.io/view/v1.0.0/schema.json" + ], + "id": "sentinel-2", + "type": "Collection", + "title": "Sentinel-2 MSI: MultiSpectral Instrument, Level-2A", + "description": "The SENTINEL-2 mission is a land monitoring constellation of two satellites each equipped with a MSI (Multispectral Imager) instrument covering 13 spectral bands providing high resolution optical imagery (i.e., 10m, 20m, 60 m) every 10 days with one satellite and 5 days with two satellites", + "license": "proprietary", + "extent": { + "spatial": { + "bbox": [ + [ + -180, + -82.852377834669, + 180, + 82.819463367711 + ] + ] + }, + "temporal": { + "interval": [ + [ + "2017-04-12T02:57:21.459000Z", + "2021-04-22T11:30:12.767000Z" + ] + ] + } + }, + "links": [ + { + "rel": "parent", + "href": "../catalog.json", + "type": "application/json", + "title": "Example Catalog" + }, + { + "rel": "root", + "href": "../catalog.json", + "type": "application/json", + "title": "Example Catalog" + }, + { + "rel": "license", + "href": "https://scihub.copernicus.eu/twiki/pub/SciHubWebPortal/TermsConditions/Sentinel_Data_Terms_and_Conditions.pdf", + "title": "Legal notice on the use of Copernicus Sentinel Data and Service Information" + } + ], + "providers": [ + { + "name": "European Union/ESA/Copernicus", + "roles": [ + "producer", + "licensor" + ], + "url": "https://sentinel.esa.int/web/sentinel/user-guides/sentinel-2-msi" + }, + { + "name": "AWS", + "roles": [ + "host" + ], + "url": "https://registry.opendata.aws/sentinel-2/" + }, + { + "name": "jeobrowser", + "roles": [ + "processor" + ], + "url": "https://github.com/jjrom/resto" + } + ], + "summaries": { + "datetime": { + "minimum": "2017-04-12T02:57:21Z", + "maximum": "2021-04-22T11:30:12Z" + }, + "instruments": { + "type": "string", + "const": "msi", + "title": "Multispectral Intrument", + "count": 6613431 + }, + "resto:landcover": { + "type": "string", + "oneOf": [ + { + "const": "cultivated", + "title": "Cultivated", + "count": 490750 + }, + { + "const": "desert", + "title": "Desert", + "count": 543120 + }, + { + "const": "flooded", + "title": "Flooded", + "count": 5187 + }, + { + "const": "forest", + "title": "Forest", + "count": 767807 + }, + { + "const": "herbaceous", + "title": "Herbaceous", + "count": 674281 + }, + { + "const": "ice", + "title": "Ice", + "count": 231285 + }, + { + "const": "urban", + "title": "Urban", + "count": 1219 + }, + { + "const": "water", + "title": "Water", + "count": 2303314 + } + ] + }, + "resto:location": { + "type": "string", + "oneOf": [ + { + "const": "tropical", + "title": "Tropical", + "count": 1807474 + }, + { + "const": "southern", + "title": "Southern", + "count": 1671685 + }, + { + "const": "northern", + "title": "Northern", + "count": 4876669 + }, + { + "const": "equatorial", + "title": "Equatorial", + "count": 27302 + }, + { + "const": "coastal", + "title": "Coastal", + "count": 1495516 + } + ] + }, + "platform": { + "type": "string", + "oneOf": [ + { + "const": "sentinel-2b", + "title": "Sentinel 2B", + "count": 3495597 + }, + { + "const": "sentinel-2a", + "title": "Sentinel 2A", + "count": 3117831 + } + ] + }, + "resto:season": { + "type": "integer", + "oneOf": [ + { + "const": 0, + "title": "Winter", + "count": 1621108 + }, + { + "const": 2, + "title": "Summer", + "count": 2279472 + }, + { + "const": 1, + "title": "Spring", + "count": 1577067 + }, + { + "const": 3, + "title": "Autumn", + "count": 1098015 + } + ] + }, + "eo:bands": [ + { + "title": "B1", + "common_name": "coastal", + "center_wavelength": 4.439, + "gsd": 60 + }, + { + "title": "B2", + "common_name": "blue", + "center_wavelength": 4.966, + "gsd": 10 + }, + { + "title": "B3", + "common_name": "green", + "center_wavelength": 5.6, + "gsd": 10 + }, + { + "title": "B4", + "common_name": "red", + "center_wavelength": 6.645, + "gsd": 10 + }, + { + "title": "B5", + "center_wavelength": 7.039, + "gsd": 20 + }, + { + "title": "B6", + "center_wavelength": 7.402, + "gsd": 20 + }, + { + "title": "B7", + "center_wavelength": 7.825, + "gsd": 20 + }, + { + "title": "B8", + "common_name": "nir", + "center_wavelength": 8.351, + "gsd": 10 + }, + { + "title": "B8A", + "center_wavelength": 8.648, + "gsd": 20 + }, + { + "title": "B9", + "center_wavelength": 9.45, + "gsd": 60 + }, + { + "title": "B10", + "center_wavelength": 1.3735, + "gsd": 60 + }, + { + "title": "B11", + "common_name": "swir16", + "center_wavelength": 1.6137, + "gsd": 20 + }, + { + "title": "B12", + "common_name": "swir22", + "center_wavelength": 2.2024, + "gsd": 20 + } + ] + } +} \ No newline at end of file diff --git a/examples/collection-only/collection.json b/examples/collection-only/collection.json index 9a8da7c3..cc631b48 100644 --- a/examples/collection-only/collection.json +++ b/examples/collection-only/collection.json @@ -1,7 +1,11 @@ { "type": "Collection", - "stac_version": "1.0.0-rc.2", - "stac_extensions": [], + "stac_version": "1.0.0", + "stac_extensions": [ + "https://stac-extensions.github.io/eo/v1.0.0/schema.json", + "https://stac-extensions.github.io/projection/v1.0.0/schema.json", + "https://stac-extensions.github.io/view/v1.0.0/schema.json" + ], "id": "sentinel-2", "title": "Sentinel-2 MSI: MultiSpectral Instrument, Level-1C", "description": "Sentinel-2 is a wide-swath, high-resolution, multi-spectral\nimaging mission supporting Copernicus Land Monitoring studies,\nincluding the monitoring of vegetation, soil and water cover,\nas well as observation of inland waterways and coastal areas.\n\nThe Sentinel-2 data contain 13 UINT16 spectral bands representing\nTOA reflectance scaled by 10000. See the [Sentinel-2 User Handbook](https://sentinel.esa.int/documents/247904/685211/Sentinel-2_User_Handbook)\nfor details. In addition, three QA bands are present where one\n(QA60) is a bitmask band with cloud mask information. For more\ndetails, [see the full explanation of how cloud masks are computed.](https://sentinel.esa.int/web/sentinel/technical-guides/sentinel-2-msi/level-1c/cloud-masks)\n\nEach Sentinel-2 product (zip archive) may contain multiple\ngranules. Each granule becomes a separate Earth Engine asset.\nEE asset ids for Sentinel-2 assets have the following format:\nCOPERNICUS/S2/20151128T002653_20151128T102149_T56MNN. Here the\nfirst numeric part represents the sensing date and time, the\nsecond numeric part represents the product generation date and\ntime, and the final 6-character string is a unique granule identifier\nindicating its UTM grid reference (see [MGRS](https://en.wikipedia.org/wiki/Military_Grid_Reference_System)).\n\nFor more details on Sentinel-2 radiometric resoltuon, [see this page](https://earth.esa.int/web/sentinel/user-guides/sentinel-2-msi/resolutions/radiometric).\n", @@ -78,9 +82,6 @@ "minimum": 6.78, "maximum": 89.9 }, - "sci:citation": [ - "Copernicus Sentinel data [Year]" - ], "gsd": [ 10, 30, @@ -213,11 +214,15 @@ "links": [ { "rel": "parent", - "href": "../catalog.json" + "href": "../catalog.json", + "type": "application/json", + "title": "Example Catalog" }, { "rel": "root", - "href": "../catalog.json" + "href": "../catalog.json", + "type": "application/json", + "title": "Example Catalog" }, { "rel": "license", diff --git a/examples/collection.json b/examples/collection.json index 4fadb641..07643b60 100644 --- a/examples/collection.json +++ b/examples/collection.json @@ -1,7 +1,12 @@ { "id": "simple-collection", "type": "Collection", - "stac_version": "1.0.0-rc.2", + "stac_extensions": [ + "https://stac-extensions.github.io/eo/v1.0.0/schema.json", + "https://stac-extensions.github.io/projection/v1.0.0/schema.json", + "https://stac-extensions.github.io/view/v1.0.0/schema.json" + ], + "stac_version": "1.0.0", "description": "A simple collection demonstrating core catalog fields with links to a couple of items", "title": "Simple Example Collection", "providers": [ @@ -19,18 +24,18 @@ "spatial": { "bbox": [ [ - 172.911, - 1.343, - 172.955, - 1.3691 + 172.91173669923782, + 1.3438851951615003, + 172.95469614953714, + 1.3690476620161975 ] ] }, "temporal": { "interval": [ [ - "2020-12-11T09:06:43.312000Z", - "2020-12-14T18:02:31.437000Z" + "2020-12-11T22:38:32.125Z", + "2020-12-14T18:02:31.437Z" ] ] } @@ -38,33 +43,47 @@ "license": "CC-BY-4.0", "summaries": { "platform": [ - "cool_sat2", - "cool_sat1" + "cool_sat1", + "cool_sat2" ], "constellation": [ "ion" ], "instruments": [ - "cool_sensor_v1" + "cool_sensor_v1", + "cool_sensor_v2" ], "gsd": { "minimum": 0.512, - "maximum": 0.7 + "maximum": 0.66 }, - "view:off_nadir": { - "minimum": 0, - "maximum": 15 + "eo:cloud_cover": { + "minimum": 1.2, + "maximum": 1.2 + }, + "proj:epsg": { + "minimum": 32659, + "maximum": 32659 }, "view:sun_elevation": { - "minimum": 6.78, - "maximum": 40 + "minimum": 54.9, + "maximum": 54.9 + }, + "view:off_nadir": { + "minimum": 3.8, + "maximum": 3.8 + }, + "view:sun_azimuth": { + "minimum": 135.7, + "maximum": 135.7 } }, "links": [ { "rel": "root", "href": "./collection.json", - "type": "application/json" + "type": "application/json", + "title": "Simple Example Collection" }, { "rel": "item", @@ -86,7 +105,7 @@ }, { "rel": "self", - "href": "https://raw.githubusercontent.com/radiantearth/stac-spec/v1.0.0-rc.2/examples/collection.json", + "href": "https://raw.githubusercontent.com/radiantearth/stac-spec/v1.0.0/examples/collection.json", "type": "application/json" } ] diff --git a/examples/collectionless-item.json b/examples/collectionless-item.json index 250bb704..6e7beab9 100644 --- a/examples/collectionless-item.json +++ b/examples/collectionless-item.json @@ -1,5 +1,5 @@ { - "stac_version": "1.0.0-rc.2", + "stac_version": "1.0.0", "stac_extensions": [ "https://stac-extensions.github.io/eo/v1.0.0/schema.json", "https://stac-extensions.github.io/view/v1.0.0/schema.json" @@ -71,33 +71,30 @@ "cs:sat_id": "CS3", "cs:product_level": "LV1B" }, - "collection": "CS3", "links": [ - { - "rel": "collection", - "href": "./collection.json", - "type": "application/json", - "title": "Simple Example Collection" - }, { "rel": "root", - "href": "./collection.json", - "type": "application/json" + "href": "./catalog.json", + "type": "application/json", + "title": "Example Catalog" }, { - "rel": "root", - "href": "./collection.json", - "type": "application/json" + "rel": "parent", + "href": "./catalog.json", + "type": "application/json", + "title": "Example Catalog" }, { "rel": "alternate", "type": "text/html", - "href": "http://cool-sat.com/catalog/CS3-20160503_132130_04/CS3-20160503_132130_04.html" + "href": "http://cool-sat.com/catalog/CS3-20160503_132130_04/CS3-20160503_132130_04.html", + "title": "HTML representation of this STAC Item" }, { "rel": "license", "type": "text/html", - "href": "http://remotedata.io/license.html" + "href": "http://remotedata.io/license.html", + "title": "Data License for Remote Data, Inc." } ], "assets": { diff --git a/examples/core-item.json b/examples/core-item.json index 0b453dd4..d07cc8df 100644 --- a/examples/core-item.json +++ b/examples/core-item.json @@ -1,5 +1,5 @@ { - "stac_version": "1.0.0-rc.2", + "stac_version": "1.0.0", "stac_extensions": [], "type": "Feature", "id": "20201211_223832_CS2", @@ -44,7 +44,7 @@ "end_datetime": "2020-12-11T22:38:32.327Z", "created": "2020-12-12T01:48:13.725Z", "updated": "2020-12-12T01:48:13.725Z", - "platform": "cool_sat2", + "platform": "cool_sat1", "instruments": [ "cool_sensor_v1" ], @@ -63,12 +63,20 @@ { "rel": "root", "href": "./collection.json", - "type": "application/json" + "type": "application/json", + "title": "Simple Example Collection" + }, + { + "rel": "parent", + "href": "./collection.json", + "type": "application/json", + "title": "Simple Example Collection" }, { "rel": "alternate", "type": "text/html", - "href": "http://remotedata.io/catalog/20201211_223832_CS2/index.html" + "href": "http://remotedata.io/catalog/20201211_223832_CS2/index.html", + "title": "HTML version of this STAC Item" } ], "assets": { diff --git a/examples/extended-item.json b/examples/extended-item.json index 4012cb4a..59f2de1f 100644 --- a/examples/extended-item.json +++ b/examples/extended-item.json @@ -1,5 +1,5 @@ { - "stac_version": "1.0.0-rc.2", + "stac_version": "1.0.0", "stac_extensions": [ "https://stac-extensions.github.io/eo/v1.0.0/schema.json", "https://stac-extensions.github.io/projection/v1.0.0/schema.json", @@ -45,12 +45,12 @@ "properties": { "title": "Extended Item", "description": "A sample STAC Item that includes a variety of examples from the stable extensions", - "datetime": "2020-12-11T22:38:32.125Z", - "created": "2020-12-12T01:48:13.725Z", - "updated": "2020-12-12T01:48:13.725Z", + "datetime": "2020-12-14T18:02:31.437000Z", + "created": "2020-12-15T01:48:13.725Z", + "updated": "2020-12-15T01:48:13.725Z", "platform": "cool_sat2", "instruments": [ - "cool_sensor_v1" + "cool_sensor_v2" ], "gsd": 0.66, "eo:cloud_cover": 1.2, @@ -91,12 +91,20 @@ { "rel": "root", "href": "./collection.json", - "type": "application/json" + "type": "application/json", + "title": "Simple Example Collection" + }, + { + "rel": "parent", + "href": "./collection.json", + "type": "application/json", + "title": "Simple Example Collection" }, { "rel": "alternate", "type": "text/html", - "href": "http://remotedata.io/catalog/20201211_223832_CS2/index.html" + "href": "http://remotedata.io/catalog/20201211_223832_CS2/index.html", + "title": "HTML version of this STAC Item" } ], "assets": { diff --git a/examples/extensions-collection/collection.json b/examples/extensions-collection/collection.json index a79fabe3..bfbc3c1e 100644 --- a/examples/extensions-collection/collection.json +++ b/examples/extensions-collection/collection.json @@ -1,13 +1,20 @@ { "id": "extensions-collection", "type": "Collection", - "stac_version": "1.0.0-rc.2", + "stac_version": "1.0.0", "description": "A heterogenous collection containing deeper examples of various extensions", "links": [ + { + "rel": "parent", + "href": "../catalog.json", + "type": "application/json", + "title": "Example Catalog" + }, { "rel": "root", "href": "../catalog.json", - "type": "application/json" + "type": "application/json", + "title": "Example Catalog" }, { "rel": "item", @@ -18,11 +25,6 @@ "rel": "license", "href": "https://remotedata.io/license.html", "title": "Remote Data License Terms" - }, - { - "rel": "parent", - "href": "../catalog.json", - "type": "application/json" } ], "stac_extensions": [], diff --git a/examples/extensions-collection/proj-example/proj-example.json b/examples/extensions-collection/proj-example/proj-example.json index 91fa8130..09b7986d 100644 --- a/examples/extensions-collection/proj-example/proj-example.json +++ b/examples/extensions-collection/proj-example/proj-example.json @@ -1,6 +1,6 @@ { "type": "Feature", - "stac_version": "1.0.0-rc.2", + "stac_version": "1.0.0", "id": "proj-example", "properties": { "datetime": "2018-10-01T01:08:32.033000Z", @@ -213,12 +213,20 @@ { "rel": "root", "href": "../../catalog.json", - "type": "application/json" + "type": "application/json", + "title": "Example Catalog" }, { "rel": "parent", "href": "../collection.json", - "type": "application/json" + "type": "application/json", + "title": "Collection of Extension Items" + }, + { + "rel": "collection", + "href": "../collection.json", + "type": "application/json", + "title": "Collection of Extension Items" } ], "assets": { @@ -242,7 +250,6 @@ "eo:bands": [ { "name": "B8", - "common_name": "panchromatic", "center_wavelength": 0.59, "full_width_half_max": 0.18 } diff --git a/examples/simple-item.json b/examples/simple-item.json index ad4d526d..1e413c43 100644 --- a/examples/simple-item.json +++ b/examples/simple-item.json @@ -1,5 +1,5 @@ { - "stac_version": "1.0.0-rc.2", + "stac_version": "1.0.0", "stac_extensions": [], "type": "Feature", "id": "20201211_223832_CS2", @@ -50,7 +50,14 @@ { "rel": "root", "href": "./collection.json", - "type": "application/json" + "type": "application/json", + "title": "Simple Example Collection" + }, + { + "rel": "parent", + "href": "./collection.json", + "type": "application/json", + "title": "Simple Example Collection" } ], "assets": { diff --git a/extensions/README.md b/extensions/README.md index e864f3ce..151983d0 100644 --- a/extensions/README.md +++ b/extensions/README.md @@ -1,13 +1,15 @@ # Extensions - [Overview](#overview) -- [General Conventions](#general-conventions) +- [Using Extensions](#using-extensions) + - [Extension IDs in `stac_extensions`](#extension-ids-in-stac_extensions) - [Stable STAC Extensions](#stable-stac-extensions) - [Community Extensions](#community-extensions) - - [Extension Maturity](#extension-maturity) - [Proposed extensions](#proposed-extensions) - [Extending STAC](#extending-stac) + - [General Conventions](#general-conventions) - [Proposing new extensions](#proposing-new-extensions) + - [Extension Maturity](#extension-maturity) - [Prefixes](#prefixes) - [Use of arrays and objects](#use-of-arrays-and-objects) @@ -33,13 +35,38 @@ can be aware of it. Each extension has at least one *owner*. You can find extension owners in each extension's README. -## General Conventions - -1. Additional attributes relating to an [Item](../item-spec/item-spec.md) should be added into the Item Properties object, rather than directly in the Item object. -2. In general, additional attributes that apply to an Item Asset should also be allowed in Item Properties and vice-versa. -For example, the `eo:bands` attribute may be used in Item Properties to describe the aggregation of all bands available in -the Item Asset objects contained in the Item, but may also be used in an individual Item Asset to describe only the bands available in that asset. -3. Additional attributes relating to a [Catalog](../catalog-spec/catalog-spec.md) or [Collection](../collection-spec/collection-spec.md) should be added to the root of the object. +## Using Extensions + +When deciding how to model data in STAC it is highly recommended to first look at the [list of +extensions](https://stac-extensions.github.io/) and re-use fields there instead of creating your own version. This +increases interoperability, as users know that the meaning of your fields is the same as in other STAC +implementations. Many clients will also understand more mature extensions for better display and querying. + +To incorporate an extension in STAC the 'extension ID' of the extension must be added to the `stac_extensions` +array of the STAC [Catalog](../catalog-spec/catalog-spec.md#stac_extensions), +[Collection](../collection-spec/collection-spec.md#stac_extensions) or [Item](../item-spec/item-spec.md#stac_extensions) +object. This identifier is a link to the JSON Schema URL that validates the fields in the extension, so STAC validators +can fetch the Schema to validate that the STAC object properly follows the extension. These JSON Schema URLs also act as +identifiers for specific version of the extension that the STAC object implements. The extension ID can be +found listed as the 'identifier' in the second line of the README of any extension made with the [extension +template](https://github.com/stac-extensions/template), and new ones get published automatically with any release made +with the template. + +### Extension IDs in `stac_extensions` + +The logic for when an object should list an extension ID in its `stac_extension` array is as follows: + +- If the object directly implements the extension (by following the specified requirements - usually by including +fields, but occasionally implementing alternate behaviors), the `stac_extensions` of that object should contain the extension ID. +- If an Asset implements fields of the extension, then `stac_extensions` of the Item or Collection which holds that + Asset should contain the extension ID. +- If a Collection [summary](../collection-spec/collection-spec.md#summaries) contains Item fields that implement an extension, then + the `stac_extensions` array of that Collection should list the extension ID. For example, if a Collection `summaries` field + contains a summary of `eo:bands`, then that Collection should have the EO extension JSON Schema URL in the `stac_extensions` array. +- If an object implements an extension that results in fields from a separate extension to be referenced, then the latter extension + ID should be included in the `stac_extensions` array for that object. For example, if a Collection implements the + [item_assets](https://github.com/stac-extensions/item-assets) extension, and in the `item_assets` field there is an Asset Definition + which includes `eo:bands`, then the EO extension ID should be listed in that Collection's `stac_extensions`. ## Stable STAC Extensions @@ -77,9 +104,25 @@ with existing extensions as well as possible and may even re-use fields and thei into a new extension that combines commonly used fields across multiple extensions. Best practices for extension proposals are still emerging in this section. +### General Conventions + +Creating a new extension usually involves defining a set of logically grouped fields, and specifying what the allowed values +for those fields are. This should be done in the extension text and in JSON Schema, to provide validation. While one +can theoretically add fields anywhere in JSON there are some conventions as to where to add them in STAC objects. + +1. Additional attributes relating to an [Item](../item-spec/item-spec.md) should be added into the Item Properties object, + rather than directly in the Item object. +2. In general, additional attributes that apply to an Item Asset should also be allowed in Item Properties and vice-versa. + For example, the `eo:bands` attribute may be used in Item Properties to describe the aggregation of all bands available in + the Item Asset objects contained in the Item, but may also be used in an individual Item Asset to describe only the bands available in that asset. +3. Additional attributes relating to a [Catalog](../catalog-spec/catalog-spec.md) or + [Collection](../collection-spec/collection-spec.md) should be added to the root of the object. +4. Extensions may also extend other extensions, declaring that dependency in the text and JSON Schema. + ### Proposing new extensions -Extensions can be hosted anywhere, but should use the [extension template](https://github.com/stac-extensions/stac-extensions.github.io#using-the-stac-extensions-template) +Extensions can be hosted anywhere, but should use the +[extension template](https://github.com/stac-extensions/stac-extensions.github.io#using-the-stac-extensions-template) as a starting point. If you'd like to add a repository to the [stac-extensions](https://github.com/stac-extensions) GitHub organization, just ask on [Gitter](https://gitter.im/SpatioTemporal-Asset-Catalog/Lobby)! This is fine for work-in-progress extensions. You can also host the extension repository in your own GitHub account, and optionally @@ -163,10 +206,20 @@ For extensions, it is recommended to 1. Use arrays only as enumerations/lists (possibly sorted), without implying additional meaning (such as order) 2. To avoid using nested objects, in favor of multiple attributes with a similar naming scheme. -For example, if one would like to define an extension to contain a start and a end date, there are multiple options (tl;dr: option **3** is recommended): - -1. Define an object, for example: `"date_range": {"start": "2018-01-01", "end": "2018-01-31"}`. This is **discouraged** as it is more complex to search in objects. -2. Define an two-element array where the first element is the start date and the second element is the end date, for example `"date_range": ["2018-01-01", "2018-01-31"]`. This is **discouraged** as it would conflict with Collection `summaries`, which always considers arrays as true (potentially sorted) enumeration without any additional meaning. -3. Define two separate fields, e.g. `"date_range_start": "2018-01-01", "date_range_end": "2018-01-31"`. This is **recommended** as it avoids the conflicts above and is usually better displayed in software that only understands GeoJSON but has no clue about STAC. This is due to the fact that most legacy software can not display arrays or objects GeoJSON `properties` properly. - -This rules only applies to the fields defined directly for the Item's `properties`. For fields and structures defined on other levels (e.g. in the root of an Item or in an array), extension authors can freely define the structure. So an array of objects such as the `eo:bands` are fine to use, but keep in mind that the drawbacks mentioned above usually still apply. +For example, if one would like to define an extension to contain a start and a end date, +there are multiple options (tl;dr: option **3** is recommended): + +1. Define an object, for example: `"date_range": {"start": "2018-01-01", "end": "2018-01-31"}`. + This is **discouraged** as it is more complex to search in objects. +2. Define an two-element array where the first element is the start date and the second element is the end date, + for example `"date_range": ["2018-01-01", "2018-01-31"]`. + This is **discouraged** as it would conflict with Collection `summaries`, + which always considers arrays as true (potentially sorted) enumeration without any additional meaning. +3. Define two separate fields, e.g. `"date_range_start": "2018-01-01", "date_range_end": "2018-01-31"`. + This is **recommended** as it avoids the conflicts above and is usually better displayed in software that only understands GeoJSON + but has no clue about STAC. + This is due to the fact that most legacy software can not display arrays or objects GeoJSON `properties` properly. + +This rules only applies to the fields defined directly for the Item's `properties`. +For fields and structures defined on other levels (e.g. in the root of an Item or in an array), extension authors can freely define the structure. +So an array of objects such as the `eo:bands` are fine to use, but keep in mind that the drawbacks mentioned above usually still apply. diff --git a/item-spec/common-metadata.md b/item-spec/common-metadata.md index 2a0506ca..b9596c46 100644 --- a/item-spec/common-metadata.md +++ b/item-spec/common-metadata.md @@ -19,8 +19,8 @@ Various *examples* are available in the folder [`examples`](../examples/). *JSON Schemas* can be found in the folder [`json-schema`](json-schema/). By default, these fields are only included and validated against in the core [Item schema](json-schema/item.json). -Implementation of any of the fields is not required, -if the specifications allowing these fields to be used don't say differently. + +Implementation of any of the fields is not required, unless explicitly required by a specification using the field. For example, `datetime` is required in STAC Items. ## Basics @@ -43,13 +43,13 @@ Fields to provide additional temporal information such as ranges with a start an | Field Name | Type | Description | | ---------- | ------------ | ----------- | | datetime | string\|null | See the [Item Spec Fields](item-spec.md#properties-object) for more information. | -| created | string | Creation date and time of the corresponding data (see below). | -| updated | string | Date and time the corresponding data (see below) was updated last. | +| created | string | Creation date and time of the corresponding data (see below), in UTC. | +| updated | string | Date and time the corresponding data (see below) was updated last, in UTC. | All timestamps MUST be formatted according to [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6). **created** and **updated** have different meaning depending on where they are used. -If those fields are available in the Item `properties`, it's referencing to the creation and update times of the metadata. +If those fields are available in the Item `properties`, they identify the creation and update times of the metadata. Having those fields in the Item `assets` refers to the creation and update times of the actual data linked to in the Asset Object. *NOTE: There are more date and time related fields available in the [Timestamps @@ -58,10 +58,12 @@ extension](https://github.com/stac-extensions/timestamps), which is not an offic ### Date and Time Range While a STAC Item can have a nominal datetime describing the capture, these properties allow an Item to have a range -of capture dates and times. 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. +of capture dates and times. An example of this is the [MODIS 16 day vegetation index product](https://lpdaac.usgs.gov/products/mod13q1v006/). -**Important:** Using one of the fields REQUIRES to include the other field as well to enable a user to search STAC records by the provided times. So if you use `start_datetime` you need to add `end_datetime` and vice-versa. Both fields are also REQUIRED if the `datetime` field is set to `null`. +**Important:** Using one of the fields REQUIRES inclusion of the other field as well to enable a user to search STAC records by the provided times. +So if you use `start_datetime` you need to add `end_datetime` and vice-versa. +Both fields are also REQUIRED if the `datetime` field is set to `null`. +The datetime property in a STAC Item and these fields are not mutually exclusive. | Field Name | Type | Description | | -------------- | ------ | ------------------------------------------------------------ | @@ -104,7 +106,10 @@ Information about the organizations capturing, producing, processing, hosting or ### Provider Object -The object provides information about a provider. A provider is any of the organizations that captures or processes the content of the assets and therefore influences the data offered by the STAC implementation. May also include information about the final storage provider hosting the data. +The object provides information about a provider. +A provider is any of the organizations that captures or processes the content of the assets and +therefore influences the data offered by the STAC implementation. +May also include information about the final storage provider hosting the data. | Field Name | Type | Description | | ----------- | --------- | ------------------------------------------------------------ | @@ -117,14 +122,15 @@ The object provides information about a provider. A provider is any of the organ 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. -* *producer*: The producer of the data is the provider that initially captured and processed the source data, e.g. ESA for Sentinel-2 data. -* *processor*: A processor is any provider who processed data to a derived product. -* *host*: The host is the actual provider offering the data on their storage. There should be no more than one host, specified as last element of the list. +- *licensor*: The organization that is licensing the dataset under 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. +- *processor*: A processor is any provider who processed data to a derived product. +- *host*: The host is the actual provider offering the data on their storage. + There should be no more than one host, specified as the last element of the provider list. ## Instrument -Adds metadata specifying a platform and instrument used in a data collection mission. These fields will often be combined +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) @@ -141,10 +147,10 @@ with domain-specific extensions that describe the actual data, such as the `eo` #### platform -The unique name of the specific platform the instrument is attached to. For satellites this would -be the name of the satellite, whereas for drones this would be a unique name for the drone. Examples include -`landsat-8` (Landsat-8), `sentinel-2a` and `sentinel-2b` (Sentinel-2), `terra` and `aqua` (part of NASA EOS, -carrying the MODIS instruments), `mycorp-uav-034` (hypothetical drone name), and `worldview02` +The unique name of the specific platform the instrument is attached to. For satellites this would +be the name of the satellite, whereas for drones this would be a unique name for the drone. Examples include +`landsat-8` (Landsat-8), `sentinel-2a` and `sentinel-2b` (Sentinel-2), `terra` and `aqua` (part of NASA EOS, +carrying the MODIS instruments), `mycorp-uav-034` (hypothetical drone name), and `worldview02` (Maxar/DigitalGlobe WorldView-2). #### instruments @@ -156,15 +162,15 @@ specified as `['oli', 'tirs']`. Other instrument examples include `msi` (Sentine #### constellation -The name of a logical collection of one or more platforms that have similar payloads and have -their orbits arranged in a way to increase the temporal resolution of acquisitions of data with similar geometric and -radiometric characteristics. This field allows users to search for related data sets without the need to specify which -specific platform the data came from, for example, from either of the Sentinel-2 satellites. Examples include `landsat-8` +The name of a logical collection of one or more platforms that have similar payloads and have +their orbits arranged in a way to increase the temporal resolution of acquisitions of data with similar geometric and +radiometric characteristics. This field allows users to search for related data sets without the need to specify which +specific platform the data came from, for example, from either of the Sentinel-2 satellites. Examples include `landsat-8` (Landsat-8, a constellation consisting of a single platform), `sentinel-2` -([Sentinel-2](https://www.esa.int/Our_Activities/Observing_the_Earth/Copernicus/Sentinel-2/Satellite_constellation)), +([Sentinel-2](https://www.esa.int/Our_Activities/Observing_the_Earth/Copernicus/Sentinel-2/Satellite_constellation)), `rapideye` (operated by Planet Labs), and `modis` (NASA EOS satellites Aqua and Terra). In the case of `modis`, this -is technically referring to a pair of sensors on two different satellites, whose data is combined into a series of -related products. Additionally, the Aqua satellite is technically part of the A-Train constellation and Terra is not +is technically referring to a pair of sensors on two different satellites, whose data is combined into a series of +related products. Additionally, the Aqua satellite is technically part of the A-Train constellation and Terra is not part of a constellation, but these are combined to form the logical collection referred to as MODIS. #### mission @@ -178,9 +184,10 @@ data collection. 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 field should be related to the spatial resolution at the sensor, rather than the pixel size of images after orthorectification, pansharpening, or scaling. -The GSD of a sensor can vary depending on off-nadir and wavelength, so it is at the discretion of the implementer -to decide which value most accurately represents the GSD. For example, Landsat8 optical and short-wave IR bands -are all 30 meters, but the panchromatic band is 15 meters. The -`gsd` should be 30 meters in this case because that is nominal spatial resolution at the sensor. The Planet -PlanetScope Ortho Tile Product has an `gsd` of 3.7 (or 4 if rounding), even though the pixel size of the images is 3.125. For example, one might choose for WorldView-2 the -Multispectral 20° off-nadir value of 2.07 and for WorldView-3 the Multispectral 20° off-nadir value of 1.38. +The GSD of a sensor can vary depending on geometry (off-nadir / grazing angle) and wavelength, so it is at the +discretion of the implementer to decide which value most accurately represents the GSD. For example, Landsat8 +optical and short-wave IR bands are all 30 meters, but the panchromatic band is 15 meters. The +`gsd` should be 30 meters in this case because that is the nominal spatial resolution at the sensor. The Planet +PlanetScope Ortho Tile Product has an `gsd` of 3.7 (or 4 if rounding), even though the pixel size of the images is 3.125. +For example, one might choose for WorldView-2 the Multispectral 20° off-nadir value of 2.07 +and for WorldView-3 the Multispectral 20° off-nadir value of 1.38. diff --git a/item-spec/item-spec.md b/item-spec/item-spec.md index 84209294..48358145 100644 --- a/item-spec/item-spec.md +++ b/item-spec/item-spec.md @@ -42,8 +42,8 @@ Items are represented in JSON format and are very flexible. Any JSON object that required fields is a valid STAC Item. - Examples: - - See the [minimal example](../examples/simple-item.json), as well as a [more fleshed example](../examples/core-item.json) that contains a number of - current best practices. + - See the [minimal example](../examples/simple-item.json), + as well as a [more fleshed example](../examples/core-item.json) that contains a number of current best practices. - Real world [implementations](https://stacindex.org/catalogs) are also available. - [JSON Schema](json-schema/item.json) @@ -63,7 +63,7 @@ inherited from GeoJSON. | properties | [Properties Object](#properties-object) | **REQUIRED.** A dictionary of additional metadata for the Item. | | links | \[[Link Object](#link-object)] | **REQUIRED.** List of link objects to resources and related URLs. A link with the `rel` set to `self` is strongly recommended. | | assets | Map | **REQUIRED.** Dictionary of asset objects that can be downloaded, each with a unique key. | -| collection | string | The `id` of the STAC Collection this Item references to (see [`collection` relation type](#relation-types)). This field is *required* if such a relation type is present. This field provides an easy way for a user to search for any Items that belong in a specified Collection. Must be a non-empty string. | +| collection | string | The `id` of the STAC Collection this Item references to (see [`collection` relation type](#relation-types)). This field is *required* if such a relation type is present and is *not allowed* otherwise. This field provides an easy way for a user to search for any Items that belong in a specified Collection. Must be a non-empty string. | ### Additional Field Information @@ -73,23 +73,24 @@ In general, STAC versions can be mixed, but please keep the [recommended best pr #### stac_extensions -A list of extensions the Item implements. -This list must only contain extensions that extend the Item itself, see the the 'Scope' column in the list of -extensions. The list contains URLs to the JSON Schema files it can be validated against. -If an extension such as the `tiled-assets` extension has influence on multiple parts of the whole catalog -structure, it must be listed in all affected parts (e.g. Catalog, Collection and Item for the `tiled-assets` extension). +A list of extensions the Item implements. +The list consists of URLs to JSON Schema files that can be used for validation. +This list must only contain extensions that extend the Item specification itself, +see the the 'Scope' for each of the extensions. #### id It is important that an Item identifier is unique within a Collection, and that the [Collection identifier](../collection-spec/collection-spec.md#id) in turn is unique globally. Then the two can be combined to give a globally unique identifier. Items are *[strongly recommended](#collections)* to have Collections, and not having one makes -it more difficult to be used in the wider STAC ecosystem. If an Item does not have a Collection, then the Item identifier should be unique within its root Catalog. +it more difficult to be used in the wider STAC ecosystem. +If an Item does not have a Collection, then the Item identifier should be unique within its root Catalog or root Collection. As most geospatial assets are already uniquely defined by some -identification scheme from the data provider it is recommended to simply use that ID. Data providers are advised to include sufficient information to make their -IDs globally unique, including things like unique satellite IDs. See the [id section of best practices](../best-practices.md#field-and-id-formatting) for -additional recommendations. +identification scheme from the data provider it is recommended to simply use that ID. +Data providers are advised to include sufficient information to make their IDs globally unique, +including things like unique satellite IDs. +See the [id section of best practices](../best-practices.md#item-ids) for additional recommendations. #### assets @@ -108,7 +109,15 @@ Items that are linked to, but the best practices around this are still emerging. #### bbox -Bounding Box of the asset represented by this Item using either 2D or 3D geometries, formatted according to [RFC 7946, section 5](https://tools.ietf.org/html/rfc7946#section-5). The length of the array must be 2\*n where n is the number of dimensions. The array contains all axes of the southwesterly most extent followed by all axes of the northeasterly most extent specified in Longitude/Latitude or Longitude/Latitude/Elevation based on [WGS 84](http://www.opengis.net/def/crs/OGC/1.3/CRS84). When using 3D geometries, the elevation of the southwesterly most extent is the minimum depth/height in meters and the elevation of the northeasterly most extent is the maximum. This field enables more naive clients to easily index and search geospatially. STAC compliant APIs are required to compute intersection operations with the Item's geometry field, not its bbox. +Bounding Box of the asset represented by this Item using either 2D or 3D geometries, +formatted according to [RFC 7946, section 5](https://tools.ietf.org/html/rfc7946#section-5). +The length of the array must be 2\*n where n is the number of dimensions. +The array contains all axes of the southwesterly most extent followed by all axes of the northeasterly most extent specified in +Longitude/Latitude or Longitude/Latitude/Elevation based on [WGS 84](http://www.opengis.net/def/crs/OGC/1.3/CRS84). +When using 3D geometries, the elevation of the southwesterly most extent is the minimum depth/height in meters +and the elevation of the northeasterly most extent is the maximum. +This field enables more naive clients to easily index and search geospatially. +STAC compliant APIs are required to compute intersection operations with the Item's geometry field, not its bbox. ### Properties Object @@ -118,7 +127,7 @@ resources below. | Field Name | Type | Description | | ---------- | ------------ | ------------------------------------------------------------ | -| datetime | string\|null | **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). `null` is allowed, but requires `start_datetime` and `end_datetime` from [common metadata](common-metadata.md#date-and-time-range) to be set. | +| datetime | string\|null | **REQUIRED.** The searchable date and time of the assets, which must be in UTC. It is formatted according to [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6). `null` is allowed, but requires `start_datetime` and `end_datetime` from [common metadata](common-metadata.md#date-and-time-range) to be set. | #### datetime @@ -127,7 +136,8 @@ or representative time in the case of assets that are combined together. Though complex thing to capture, for this purpose keep in mind the STAC spec is primarily searching for data, so use whatever single date and time is most useful for a user to search for. STAC content extensions may further specify the meaning of the main `datetime` field, and many will also add more -datetime fields. +datetime fields. **All times in STAC metadata should be in [Coordinated Universal +Time](https://en.wikipedia.org/wiki/Coordinated_Universal_Time) (UTC).** If there's clearly no meaningful single 'nominal' time, it is allowed to use `null` instead. In this case it is **required** to specify a temporal interval with the fields `start_datetime` and `end_datetime` from [common metadata](common-metadata.md#date-and-time-range). For example, if @@ -143,11 +153,11 @@ to [select only those necessary for search](../best-practices.md#field-selection Where possible metadata fields should be mapped to the STAC Common Metadata and widely used extensions, to enable cross-catalog search on known fields. -* [STAC Common Metadata](common-metadata.md#stac-common-metadata) - A list of fields commonly used +- [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. -* [Extensions](../extensions/README.md) - Additional fields that are more specific, +- [Extensions](../extensions/README.md) - Additional fields that are more specific, such as [EO](https://github.com/stac-extensions/eo), [View](https://github.com/stac-extensions/view). -* [Custom Extensions](../extensions/README.md#extending-stac) - It is generally allowed to add custom +- [Custom Extensions](../extensions/README.md#extending-stac) - It is generally allowed to add custom fields but it is recommended to add multiple fields for related values instead of a nested object, e.g., two fields `view:azimuth` and `view:off_nadir` instead of a field `view` with an object value containing the two fields. The convention (as used within Extensions) is for related fields @@ -173,17 +183,19 @@ For a full discussion of the situations where relative and absolute links are re #### Relation types -STAC Items use a variety of `rel` types in the link object, to describe the exact nature of the link between this Item and the entity it is linking to. -It is recommended to use the official [IANA Link Relation Types](https://www.iana.org/assignments/link-relations/link-relations.xhtml) where possible. +STAC Items use a variety of `rel` types in the link object, +to describe the exact nature of the link between this Item and the entity it is linking to. +It is recommended to use the official +[IANA Link Relation Types](https://www.iana.org/assignments/link-relations/link-relations.xhtml) where possible. The following table explains places where STAC use custom `rel` types are used with Items. This happens where there is not a clear official option, or where STAC uses an official type but adds additional meaning for the STAC context. | Type | Description | | ------------ | ------------------------------------------------------------ | | self | STRONGLY RECOMMENDED. *Absolute* URL to the Item if it is available at a public URL. This is particularly useful when in a download package that includes metadata, so that the downstream user can know where the data has come from. | -| root | URL to the root STAC Catalog or Collection. | -| parent | URL to the parent STAC Catalog or Collection. | -| collection | STRONGLY RECOMMENDED. URL to a Collection. *Absolute* URLs should be used whenever possible. The referenced Collection is STRONGLY RECOMMENDED to implement the same STAC version as the Item. | +| root | URL to the root STAC entity (Catalog or Collection). | +| parent | URL to the parent STAC entity (Catalog or Collection). | +| collection | STRONGLY RECOMMENDED. URL to a Collection. *Absolute* URLs should be used whenever possible. The referenced Collection is STRONGLY RECOMMENDED to implement the same STAC version as the Item. A link with this `rel` type is *required* if the `collection` field in properties is present. | | derived_from | URL to a STAC Item that was used as input data in the creation of this Item. | A more complete list of potential `rel` types and their meaning in STAC can be found in the [Using Relation @@ -191,16 +203,20 @@ Types](../best-practices.md#using-relation-types) best practice. ##### derived_from -*Note regarding the type `derived_from`: A full provenance model is far beyond the scope of STAC, and the goal is to align with any good independent spec -that comes along for that. But the derived_from field is seen as a way to encourage fuller specs and at least start a linking +*Note regarding the type `derived_from`: A full provenance model is far beyond the scope of STAC, +and the goal is to align with any good independent spec that comes along for that. +But the derived_from field is seen as a way to encourage fuller specs and at least start a linking structure that can be used as a jumping off point for more experiments in provenance tracking* #### Collections -Items are *strongly recommended* to provide a link to a STAC Collection definition. It is important as Collections provide additional information about a set of items, for example the license, provider and other information +Items are *strongly recommended* to provide a link to a STAC Collection definition. +It is important as Collections provide additional information about a set of items, +for example the license, provider and other information giving context on the overall set of data that an individual Item is a part of. -If Items are part of a STAC Collection, the [STAC Collection spec *requires* Items to link back to the Collection](../collection-spec/collection-spec.md#relation-types). +If Items are part of a STAC Collection, the +[STAC Collection spec *requires* Items to link back to the Collection](../collection-spec/collection-spec.md#relation-types). Linking back must happen in two places: 1. The field `collection` in an Item must be filled (see section 'Item fields'). It is the `id` of a STAC Collection. @@ -255,8 +271,8 @@ Like the Link `rel` field, the `roles` field can be given any value, however her | 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` +- 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` Note that multiple roles per asset are encouraged: pick all the ones that apply. So many should have the 'data' role, and then another role to describe how the data is used. For more information on how to use roles see the [Asset @@ -279,7 +295,8 @@ For example, `gsd` defined for an Item represents the best Ground Sample Distanc However, some assets may be lower resolution and thus have a higher `gsd`. The `eo:bands` field from the EO extension defines an array of spectral bands. However, it may be useful instead to specify the bands that are used in a particular asset. -For an example see the [sentinel2-sample](https://github.com/stac-utils/stac-examples/blob/main/sentinel2/sentinel2-sample.json). The Sentinel-2 overall `gsd` is 10m, because this is +For an example see the [sentinel2-sample](https://github.com/stac-utils/stac-examples/blob/main/sentinel2/sentinel2-sample.json). +The Sentinel-2 overall `gsd` is 10m, because this is the best spatial resolution among all the bands and is defined in Item properties so it can be searched on. In the example Band 5 and others have a `gsd` of 20m, so that asset specifies the `gsd` as well, which overrides the Item `gsd` for this one asset. The example also includes reduced resolution versions of files included as assets, using `gsd` to represent @@ -289,7 +306,8 @@ For `eo:bands`, it could be put in Item properties as an array of all the bands, the assets each define an array containing the spectral band information for that asset (in the order the bands appear in the file). -For examples of fields that this construct is recommended for, see the [section of STAC Best Practices](../best-practices.md#common-use-cases-of-additional-fields-for-assets) +For examples of fields that this construct is recommended for, +see the [section of STAC Best Practices](../best-practices.md#common-use-cases-of-additional-fields-for-assets) that talks about common use cases of additional fields for assets. ## Media Type for STAC Item diff --git a/item-spec/json-schema/basics.json b/item-spec/json-schema/basics.json index a5b26a3d..68e8f37a 100644 --- a/item-spec/json-schema/basics.json +++ b/item-spec/json-schema/basics.json @@ -1,6 +1,6 @@ { "$schema": "http://json-schema.org/draft-07/schema#", - "$id": "https://schemas.stacspec.org/v1.0.0-rc.2/item-spec/json-schema/basics.json#", + "$id": "https://schemas.stacspec.org/v1.0.0/item-spec/json-schema/basics.json#", "title": "Basic Descriptive Fields", "type": "object", "properties": { diff --git a/item-spec/json-schema/datetime.json b/item-spec/json-schema/datetime.json index 3a1480db..4c7a3a14 100644 --- a/item-spec/json-schema/datetime.json +++ b/item-spec/json-schema/datetime.json @@ -1,6 +1,6 @@ { "$schema": "http://json-schema.org/draft-07/schema#", - "$id": "https://schemas.stacspec.org/v1.0.0-rc.2/item-spec/json-schema/datetime.json#", + "$id": "https://schemas.stacspec.org/v1.0.0/item-spec/json-schema/datetime.json#", "title": "Date and Time Fields", "type": "object", "dependencies": { @@ -20,29 +20,34 @@ "title": "Date and Time", "description": "The searchable date/time of the assets, in UTC (Formatted in RFC 3339) ", "type": ["string", "null"], - "format": "date-time" + "format": "date-time", + "pattern": "(\\+00:00|Z)$" }, "start_datetime": { "title": "Start Date and Time", "description": "The searchable start date/time of the assets, in UTC (Formatted in RFC 3339) ", "type": "string", - "format": "date-time" + "format": "date-time", + "pattern": "(\\+00:00|Z)$" }, "end_datetime": { "title": "End Date and Time", "description": "The searchable end date/time of the assets, in UTC (Formatted in RFC 3339) ", "type": "string", - "format": "date-time" + "format": "date-time", + "pattern": "(\\+00:00|Z)$" }, "created": { "title": "Creation Time", "type": "string", - "format": "date-time" + "format": "date-time", + "pattern": "(\\+00:00|Z)$" }, "updated": { "title": "Last Update Time", "type": "string", - "format": "date-time" + "format": "date-time", + "pattern": "(\\+00:00|Z)$" } } } \ No newline at end of file diff --git a/item-spec/json-schema/instrument.json b/item-spec/json-schema/instrument.json index 78d836ba..688c4a49 100644 --- a/item-spec/json-schema/instrument.json +++ b/item-spec/json-schema/instrument.json @@ -1,6 +1,6 @@ { "$schema": "http://json-schema.org/draft-07/schema#", - "$id": "https://schemas.stacspec.org/v1.0.0-rc.2/item-spec/json-schema/instrument.json#", + "$id": "https://schemas.stacspec.org/v1.0.0/item-spec/json-schema/instrument.json#", "title": "Instrument Fields", "type": "object", "properties": { diff --git a/item-spec/json-schema/item.json b/item-spec/json-schema/item.json index 34d351f3..8d428678 100644 --- a/item-spec/json-schema/item.json +++ b/item-spec/json-schema/item.json @@ -1,6 +1,6 @@ { "$schema": "http://json-schema.org/draft-07/schema#", - "$id": "https://schemas.stacspec.org/v1.0.0-rc.2/item-spec/json-schema/item.json#", + "$id": "https://schemas.stacspec.org/v1.0.0/item-spec/json-schema/item.json#", "title": "STAC Item", "type": "object", "description": "This object represents the metadata for an item in a SpatioTemporal Asset Catalog.", @@ -93,24 +93,16 @@ "stac_version": { "title": "STAC version", "type": "string", - "const": "1.0.0-rc.2" + "const": "1.0.0" }, "stac_extensions": { "title": "STAC extensions", "type": "array", "uniqueItems": true, "items": { - "anyOf": [ - { - "title": "Reference to a JSON Schema", - "type": "string", - "format": "iri" - }, - { - "title": "Reference to a core extension", - "type": "string" - } - ] + "title": "Reference to a JSON Schema", + "type": "string", + "format": "iri" } }, "id": { @@ -159,12 +151,42 @@ ] } ] - }, - "collection": { - "title": "Collection ID", - "description": "The ID of the STAC Collection this Item references to.", - "type": "string", - "minLength": 1 + } + }, + "if": { + "properties": { + "links": { + "contains": { + "required": [ + "rel" + ], + "properties": { + "rel": { + "const": "collection" + } + } + } + } + } + }, + "then": { + "required": [ + "collection" + ], + "properties": { + "collection": { + "title": "Collection ID", + "description": "The ID of the STAC Collection this Item references to.", + "type": "string", + "minLength": 1 + } + } + }, + "else": { + "properties": { + "collection": { + "not": {} + } } } } diff --git a/item-spec/json-schema/licensing.json b/item-spec/json-schema/licensing.json index a20dde60..ca0eed8b 100644 --- a/item-spec/json-schema/licensing.json +++ b/item-spec/json-schema/licensing.json @@ -1,6 +1,6 @@ { "$schema": "http://json-schema.org/draft-07/schema#", - "$id": "https://schemas.stacspec.org/v1.0.0-rc.2/item-spec/json-schema/licensing.json#", + "$id": "https://schemas.stacspec.org/v1.0.0/item-spec/json-schema/licensing.json#", "title": "Licensing Fields", "type": "object", "properties": { diff --git a/item-spec/json-schema/provider.json b/item-spec/json-schema/provider.json index b80c734e..01cfadce 100644 --- a/item-spec/json-schema/provider.json +++ b/item-spec/json-schema/provider.json @@ -1,6 +1,6 @@ { "$schema": "http://json-schema.org/draft-07/schema#", - "$id": "https://schemas.stacspec.org/v1.0.0-rc.2/item-spec/json-schema/provider.json#", + "$id": "https://schemas.stacspec.org/v1.0.0/item-spec/json-schema/provider.json#", "title": "Provider Fields", "type": "object", "properties": { diff --git a/overview.md b/overview.md index 3d752aae..e87d43ec 100644 --- a/overview.md +++ b/overview.md @@ -3,7 +3,7 @@ There are three component specifications that together make up the core SpatioTemporal Asset Catalog specification. Each can be used alone, but they work best in concert with one another. The [STAC API specification](https://github.com/radiantearth/stac-api-spec) builds on top of that core, but is out of scope for this overview. An [Item](item-spec/item-spec.md) represents a -single [spatiotemporal asset](#what-is-a-spatiotemporal-asset) as GeoJSON so it can be searched. +single [spatiotemporal asset](#what-is-a-spatiotemporal-asset) as [GeoJSON](https://geojson.org/) so it can be searched. The [Catalog](catalog-spec/catalog-spec.md) specification provides structural elements, to group Items and [Collections](collection-spec/collection-spec.md). Collections *are* catalogs, that add more required metadata and describe a group of related Items. For more on the differences see the [section below](#catalogs-vs-collections). @@ -11,6 +11,29 @@ describe a group of related Items. For more on the differences see the [section A [UML diagram](https://en.wikipedia.org/wiki/Unified_Modeling_Language) of the [STAC model](STAC-UML.pdf) is also provided to help with navigating the specification. +## Foundations + +STAC is built on top of many great standards and practices. Every part of STAC is +[JSON](https://www.json.org/json-en.html), and [GeoJSON](https://geojson.org/) provides the core geometry fields +and [features](https://en.wikipedia.org/wiki/Simple_Features) definition. All fields are described in the +specifications, and the acceptable values are defined with [JSON Schema](https://json-schema.org/). The released +JSON Schemas provide the core testing definitions, and are used in an array of validation tools. We also rely +on [RFC 8288 (Web Linking)](https://tools.ietf.org/rfc/rfc8288.txt) to express relationships between resources, +and IANA [Media Types](https://en.wikipedia.org/wiki/Media_type) to describe file formats and format contents. +The [OGC API - Features](https://ogcapi.ogc.org/features/) standard is a final core building block. The STAC +Collection extends the [Collection](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#_collection_) +JSON defined in OGC API - Features (and the full API definition is the foundation for the STAC API specification). + +The STAC specifications are written to be understandable without needing a full background in these. But if you +want to get deep into STAC tool implementation and are not familiar with any of the standards mentioned above it is +recommended to read up on them. STAC development is guided by set of core philosophical tenets, like +building small reusable parts that are loosely coupled, focusing on developers, and more - see our the +[principles](principles.md) document to learn more. + +*Note: Setting a field in JSON to `null` is not equivalent to a field not appearing in STAC, as JSON Schema tools treat +them differently. STAC defines `null` explicitly for some fields, where it has a particular meaning. So `null` should +not be used unless the STAC spec defines its use - instead the field should be left out entirely.* + ## Item Overview Fundamental to any SpatioTemporal Asset Catalog, an [Item](item-spec/item-spec.md) object represents a unit of @@ -21,10 +44,10 @@ and can be easily read by any modern GIS or geospatial library, and it describes The STAC Item JSON specification uses the GeoJSON geometry to describe the location of the asset, and then includes additional information: -* the time the asset represents; -* a thumbnail for quick browsing; -* asset links, to enable direct download or streaming access of the asset; -* relationship links, allowing users to traverse other related resources and STAC Items. +- the time the asset represents; +- a thumbnail for quick browsing; +- asset links, to enable direct download or streaming access of the asset; +- relationship links, allowing users to traverse other related resources and STAC Items. A STAC Item can contain additional fields and JSON structures to communicate more information about the asset, so it can be easily searched. STAC provides a core set of @@ -53,10 +76,11 @@ A Catalog is a very simple construct - it just provides links to Items or to oth The closest analog is a folder in a file structure, it is the container for Items, but it can also hold other containers (folders / catalogs). -The Collection specification shares some fields with the catalog spec but has a number of additional fields: +The Collection entity shares most fields with the Catalog entity but has a number of additional fields: license, extent (spatial and temporal), providers, keywords and summaries. Every Item in a Collection links back to their Collection, so clients can easily find fields like the license. Thus every Item implicitly -shares the fields described in their parent Collection. +shares the fields described in their parent Collection. Collection entities can be used just like Catalog +entities to provide structure, as they provide all the same options for linking and organizing. But what *should* go in a Collection, versus just in a Catalog? A Collection will generally consist of a set of assets that are defined with the same properties and share higher level metadata. In the @@ -68,8 +92,8 @@ to break the recommendation. Catalogs in turn are used for two main things: -* Split overly large collections into groups -* Group collections into a catalog of Collections (e.g. as entry point for navigation to several Collections). +- Split overly large collections into groups +- Group collections into a catalog of Collections (e.g. as entry point for navigation to several Collections). The first case allows users to browse down into the Items of large collections. A collection like Landsat usually would start with path and row Catalogs to group by geography, and then year, @@ -78,27 +102,30 @@ provide multiple grouping paths, serving as a sort of faceted search. The second case is used when one wants to represent diverse data in a single place. If an organization has an internal catalog with Landsat 8, Sentinel 2, NAIP data and several commercial imagery providers -then they'd have a root catalog that would link to a number of different Collections. +then they'd have a root Catalog that would link to a number of different Collections. So in conclusion it's best to use Collections for what you want user to find as starting point, and then -catalogs are just for structuring and grouping the data. Future work includes a mechanism to actually +Catalogs are just for structuring and grouping the data. Future work includes a mechanism to actually search Collection-level data, hopefully in concert with other specifications. ## Catalog Overview +*NOTE: The below examples all say Catalog, but those can all be Collections as well, as it has all the fields necessary to +serve as a Catalog* + There are two required element types of a Catalog: Catalog and Item. A STAC Catalog points to [STAC Items](item-spec/README.md), or to other STAC catalogs. It provides a simple linking structure that can be used recursively so that many Items can be included in a single Catalog, organized however the implementor desires. -STAC makes no formal distinction between a "root" catalog and the "child" catalogs. A root catalog -is simply the top-most catalog -- it has no parent. A nested catalog structure is useful (and +STAC makes no formal distinction between a "root" Catalog and the "child" Catalogs. A root Catalog +is simply the top-most Catalog or Collection -- it has no parent. A nested catalog structure is useful (and recommended) for breaking up massive numbers of catalog Items into logical groupings. For example, it might make sense to organize a catalog by date (year, month, day), or geography (continent, country, state/prov). See the [Catalog Layout](best-practices.md#catalog-layout) best practices section for more. -A simple Catalog structure might look like this: +A simple STAC structure might look like this: - catalog (root) - catalog @@ -164,8 +191,8 @@ each Item and Catalog, as well as ways to achieve that. ## Collection Overview -A STAC Collection extends the core fields of the Catalog construct to provide additional metadata to describe the set of Items it -contains. The required fields are fairly +A STAC Collection includes the core fields of the Catalog entity and also provides additional metadata to describe +the set of Items it contains. The required fields are fairly minimal - it includes the 4 required Catalog fields (id, description, stac_version and links), and adds license and extents. But there are a number of other common fields defined in the spec, and more common fields are also defined in [STAC extensions](extensions/). These serve as basic metadata, and ideally Collections also link to diff --git a/package.json b/package.json index 3fb2aeee..0012c9c4 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "stac-spec", - "version": "1.0.0-rc.2", + "version": "1.0.0", "description": "STAC spec helpers to check the spec.", "repository": "https://github.com/radiantearth/stac-spec", "license": "Apache-2.0", @@ -21,6 +21,6 @@ "remark-preset-lint-markdown-style-guide": "^3.0.0", "remark-preset-lint-recommended": "^4.0.0", "remark-validate-links": "^10.0.0", - "stac-node-validator": "^0.4.6" + "stac-node-validator": "^1.1.0" } } diff --git a/principles.md b/principles.md index 03306596..72ef53be 100644 --- a/principles.md +++ b/principles.md @@ -4,42 +4,42 @@ reviewed in pull requests, approved by consensus. The goal of the principles is [bikeshedding](http://bikeshed.org/) - lay down some meta-rules so we can focus on creating useful core geospatial standards. -* **Creation and evolution of specs in Github**, using Open Source principles +- **Creation and evolution of specs in Github**, using Open Source principles (please read [Producing OSS](http://producingoss.com/) if that phrase doesn't immediately make sense to you). The collaboration facilities of Github should be used to their full extent. All proposed improvements and changes should come in the form of pull requests, using code review functionality to discuss changes. -* **JSON + REST + HTTP at the core.** JSON has won over XML, and REST over SOAP. We embrace them and +- **JSON + REST + HTTP at the core.** JSON has won over XML, and REST over SOAP. We embrace them and are not considering legacy options. Forward looking protocols can be considered as extensions, but the default specifications should be in JSON, following best REST practices. HTTP caching and error codes should be leveraged at the core. GeoJSON has already defined the core geospatial JSON response, so it should also be core. [JSON API](http://jsonapi.org/) should be used as basis of decisions where possible. -* **Small Reusable Pieces Loosely Coupled** - Each specification should be as focused as possible, +- **Small Reusable Pieces Loosely Coupled** - Each specification should be as focused as possible, defining one core concept and refraining from describing lots of options. Additional options can be made as separate specifications that build on the core. But the core specs should be small and easily understandble, with clear defaults for any choice. Handling complex cases should be possible by combining discrete pieces. Implementors should not be forced to implement lots of options just for basic compliance - they should be able to pick and choose which pieces are relevant to the problems they are trying to solve. -* **Focus on the developer**. Specifications should aim for implementability - any explanation or design choice +- **Focus on the developer**. Specifications should aim for implementability - any explanation or design choice should be considered with a developer audience. And specifications should be accessible to developers who do not have geospatial background. A developer should not need to understand 'projections' to implement a simple feature access service. But we should think through the spec extensions they could use in the future when their client asks for data in a different projection. -* **Working code required.** Proposed changes should be accompanied by working code +- **Working code required.** Proposed changes should be accompanied by working code (ideally with a link to an online service running the code). A reference implementation should be available online to power the interactive documentation. Fully accepted specifications should have at least 3 implementations that cover the entire specification. Extensions have their own [Extension Maturity](./extensions/README.md#extension-maturity) model. -* **Design for scale.** The design should work great with more data than can be imagined right now. +- **Design for scale.** The design should work great with more data than can be imagined right now. Ideally implementations are built with large test data sets to validate that they will work. Everything should be compatible with content distribution network (CDN) caching. ## Resources -* Open Source Principles - [Producing Open Source Software](http://producingoss.org) by Karl Fogel. -* Best Practices JSON API Design - [JSON API](http://jsonapi.org/) best practices for making API's with JSON -* Pragmatic REST - [Web API Design: Crafting interfaces that developers love](https://pages.apigee.com/rs/apigee/images/api-design-ebook-2012-03.pdf) -* Open API Initiative - [OpenAPIs.org](https://openapis.org/) +- Open Source Principles - [Producing Open Source Software](http://producingoss.org) by Karl Fogel. +- Best Practices JSON API Design - [JSON API](http://jsonapi.org/) best practices for making API's with JSON +- Pragmatic REST - [Web API Design: Crafting interfaces that developers love](https://pages.apigee.com/rs/apigee/images/api-design-ebook-2012-03.pdf) +- Open API Initiative - [OpenAPIs.org](https://openapis.org/) diff --git a/process.md b/process.md index 2250e844..92fbb7b6 100644 --- a/process.md +++ b/process.md @@ -24,18 +24,18 @@ and there is also information on how to [run the CI checks locally](CONTRIBUTING The current list of people who are part of the 'core STAC team', and can approve pull requests. -* [Alex Kaminsky](https://github.com/alkamin) -* [Alexandra Kirk](https://github.com/anayeaye) -* [Chris Holmes](http://github.com/cholmes) -* [Emmanuel Mathot](https://github.com/emmanuelmathot) -* [Michael Smith](https://github.com/hgs-msmith) -* [James Banting](https://github.com/jbants) -* [James Santucci](https://github.com/jisantuc) -* [Josh Fix](https://github.com/joshfix) -* [Rob Emanuele](https://github.com/lossyrob) -* [Matthias Mohr](https://github.com/m-mohr) -* [Matt Hanson](https://github.com/matthewhanson) -* [Phil Varner](https://github.com/philvarner) +- [Alex Kaminsky](https://github.com/alkamin) +- [Alexandra Kirk](https://github.com/anayeaye) +- [Chris Holmes](http://github.com/cholmes) +- [Emmanuel Mathot](https://github.com/emmanuelmathot) +- [Michael Smith](https://github.com/hgs-msmith) +- [James Banting](https://github.com/jbants) +- [James Santucci](https://github.com/jisantuc) +- [Josh Fix](https://github.com/joshfix) +- [Rob Emanuele](https://github.com/lossyrob) +- [Matthias Mohr](https://github.com/m-mohr) +- [Matt Hanson](https://github.com/matthewhanson) +- [Phil Varner](https://github.com/philvarner) Anyone can be nominated to the core STAC team, and that generally happens after contributing a few pull requests and/or helping review other PR's. Nominations are reviewed by the [PSC](#project-steering-committee), and must recieve @@ -45,31 +45,31 @@ and/or helping review other PR's. Nominations are reviewed by the [PSC](#project To release a new version of the STAC spec the following list of tasks must be done. -* **Update Issue Tracker**: Each release has a [milestone](https://github.com/radiantearth/stac-spec/milestones) in the github +- **Update Issue Tracker**: Each release has a [milestone](https://github.com/radiantearth/stac-spec/milestones) in the github issue tracker, and before a release is done all open issues that are filed against it should be reviewed. All issues do not need to be completed, but the core release team should all review the issues to make sure that the critical ones for the release have been addressed. Issues that aren't seen as essential should be moved to future releases, so that there are no open issues against the milestone. -* **Agreement from the Project Steering Committee**: The PSC should meet (on phone or on gitter) and decided that the release is ready. +- **Agreement from the Project Steering Committee**: The PSC should meet (on phone or on gitter) and decided that the release is ready. This should include review of the issues, as well as looking at the spec holistically, to make sure the new changes keep with a coherent whole. -* **Final Spec Read Through**: There should be a final read through of the core specification to make sure it makes sense +- **Final Spec Read Through**: There should be a final read through of the core specification to make sure it makes sense and there are no typos, errors, etc. -* **Update the version numbers**: There are several places in the spec that use the version number or a branch name in text +- **Update the version numbers**: There are several places in the spec that use the version number or a branch name in text or a link. These include the markdown files and the JSON schemas. Right now the best thing to do is just a search & replace for the last version number and `https://schemas.stacspec.org/dev/` with `https://schemas.stacspec.org//` (in JSON Schemas, don't replace it here). `` must correspond with the tag on GitHub, usually including a leading `v`. Hopefully in the future there will be scripts to do this. -* **Update the Changelog**: The [changelog](CHANGELOG.md) should be reviewed to make sure it includes all major improvements +- **Update the Changelog**: The [changelog](CHANGELOG.md) should be reviewed to make sure it includes all major improvements in the release. And anything in 'unreleased' section should move to the version of the spec to be released. -* **Merge dev to master**: As there is no 'build' process, since the specification *is* the markdown files in the github +- **Merge dev to master**: As there is no 'build' process, since the specification *is* the markdown files in the github repository, the key step in a release is to merge the `dev` branch into `master`, as `master` is the current stable state of the spec. -* **Release on Github**: The final step to create the release is to add a new 'release' on +- **Release on Github**: The final step to create the release is to add a new 'release' on . This should use a tag like the others, with a 'v' prefix and then the release number, like v0.5.2. The changelog should be copied over to be the release notes, and then also include a link to the full milestone of everything closed in the issue tracker. -* **Promote the release**: A blog post and tweet should be composed and sent out, and then inform those in the gitter channel +- **Promote the release**: A blog post and tweet should be composed and sent out, and then inform those in the gitter channel to post / promote it. #### Release Candidates @@ -98,15 +98,16 @@ decision making authority. This consists of individuals who are intended to repr stake in the specification and surrounding ecosystem. An odd number is chosen to facilitate the voting process and help prevent ties. This committee also handles the allocation of any funds that are raised for the project. -Turnover is allowed and expected to accommodate people only able to become active on the project in intervals. A PSC member may step down at any time. +Turnover is allowed and expected to accommodate people only able to become active on the project in intervals. +A PSC member may step down at any time. #### Current Project Steering Committee -* [Matthias Mohr](https://github.com/m-mohr) - University of Muenster, [OpenEO](https://openeo.org/) and [Radiant Earth](https://www.radiant.earth/) -* [Matt Hanson](https://github.com/matthewhanson) - [Element 84](https://www.element84.com/) -* [James Banting](https://github.com/jbants) - [SparkGeo](https://sparkgeo.com/) -* [Rob Emanuele](https://github.com/lossyrob) - [Microsoft](https://microsoft.com/) -* [Chris Holmes](https://github.com/cholmes) - [Planet](https://planet.com) and [Radiant Earth](https://www.radiant.earth/) +- [Matthias Mohr](https://github.com/m-mohr) - University of Muenster, [OpenEO](https://openeo.org/) and [Radiant Earth](https://www.radiant.earth/) +- [Matt Hanson](https://github.com/matthewhanson) - [Element 84](https://www.element84.com/) +- [James Banting](https://github.com/jbants) - [SparkGeo](https://sparkgeo.com/) +- [Rob Emanuele](https://github.com/lossyrob) - [Microsoft](https://microsoft.com/) +- [Chris Holmes](https://github.com/cholmes) - [Planet](https://planet.com) and [Radiant Earth](https://www.radiant.earth/) #### PSC Membership diff --git a/schema.json b/schema.json deleted file mode 100644 index e69de29b..00000000