From 38862153e6e88521f61be6585d2d4362fef68775 Mon Sep 17 00:00:00 2001 From: Phil Varner Date: Fri, 4 Jun 2021 09:36:51 -0400 Subject: [PATCH] Squashed 'stac-spec/' changes from ebd16753..789e90fb 789e90fb Merge pull request #1139 from radiantearth/dev 76d1560d Merge pull request #1140 from radiantearth/stability-note-update 19959672 removed stability note and moved key info for 1.0.0 e5ec6047 Merge pull request #1135 from radiantearth/versions-to-1_0_0 ca90fa47 Merge branch 'dev' into versions-to-1_0_0 5d017a4b Merge pull request #1138 from radiantearth/itemcollection-heuristic c40ced1b Merge pull request #1137 from radiantearth/python_ci_validation 036f2918 CHANGELOG entry added 2e60c61e Remove ci job from workflow 1b2fefb8 Removed ItemCollection from STAC detection heuristic, may get invalid soon. https://github.com/radiantearth/stac-api-spec/issues/141 9badaa78 Comment out python ci validation d584c282 updated versions and changelog to 1.0.0 517c5fb2 Merge pull request #1134 from radiantearth/updated_uml 59434f32 updated UML allowing collection children in catalogs ef679f4f update UML to remove summaries from catalogs c197acb3 Merge pull request #1133 from radiantearth/title-rec 45d0789f Merge pull request #1131 from jbants/dev 24ec4a28 added best practice to include title, updated examples 8b14d60d Added clarity around CI tests d811ae24 Ci validation (#2) 4ecbabcc Merge pull request #1128 from radiantearth/dev 73638442 Merge pull request #1129 from radiantearth/changelog-fixes 8f35589c minor changelog fixes 09f00194 Merge pull request #1119 from radiantearth/version-rc4 21e12d53 Updated CHANGELOG e7d008f2 Merge remote-tracking branch 'origin/dev' into version-rc4 00243b3e Update date in changelog f45da2c0 Merge remote-tracking branch 'origin/dev' into version-rc4 a553f116 Merge pull request #1127 from radiantearth/issue-1125 ba9df2eb Update collection-spec.md b43d16b5 Merge pull request #1123 from lossyrob/clarification/rde/collection-extension 90a2cbd6 line break for linting bf02447c updates from PR review 0a6da1ac Collection: Open intervals for temporal extents #1125 c9323e41 line break for linting b24066e1 update from PR review ea3ee26b reorg and edits 59a8cf4a Update CHANGELOG cd08d4a5 Fix TOC ordering in extensions d87813dd Clarify when to include extensions in stac_extensions 507a813c update version numbers bb7cb80c merged dev 7be086cb Merge pull request #1122 from radiantearth/catalog-summaries-removal 9fa29ce5 Update catalog-spec/json-schema/catalog.json 9fb18e73 Merge pull request #1121 from radiantearth/remove-core-ext-schema 42753fc5 Catalogs don't support summaries any more 7406ed7e Merge remote-tracking branch 'origin/dev' into remove-core-ext-schema 50d12f6c JSON Schemas don't allow "shortcuts" for core extensions any longer 56205ea4 updated version numbers / changelog 08fe31dc Merge pull request #1116 from jjrom/dev 4b77ef8b updated changelog 3f9d9acb Merge pull request #1114 from radiantearth/emmanuelmathot-patch-1 34a7c0e4 fixed schema to reflect intent, update language 2f81fcc3 Allow empty catalogs 5c48425e add missing projection declaration f81324f7 Merge pull request #1113 from radiantearth/dev 2f0a35a9 Merge pull request #1112 from radiantearth/version-changes-rc3 094b90d6 fixed linking issue d6103b82 update versions, changelog edits b3985367 Merge pull request #1111 from radiantearth/foundations-overview 06aea1c5 less characters in a line dfeaf64c more fixes from PR feedback 17c14932 updates from PR review 3a3cc099 updated changelog with pr link 20f7e716 new overview section 311a9a3b Merge pull request #1110 from radiantearth/bp-clarification 431e0af5 Update best-practices.md c5d96a8e Merge pull request #1109 from radiantearth/catalog-json-schema c3977670 best practices: some clarifications #1108 9abb6e61 Catalog: Require child / item in JSON Schema #1100 89923bf0 Merge pull request #1107 from fredliporace/summaries 13bec824 Update collection-spec/collection-spec.md 6181a350 Merge branch 'dev' into summaries 31e9f91c Apply suggestions from code review 5b5a8bd5 Merge pull request #1093 from radiantearth/json-schema-summaries a6f838ae Merge pull request #1101 from radiantearth/root-parent 3e3677c6 fix from PR review e5060dc9 Update collection-spec/collection-spec.md 4e4a7f7a Filled out 3rd option for summaries d6062ffd Merge pull request #1105 from radiantearth/gsd-tweaks 91a435e4 Merge pull request #1104 from radiantearth/no-scientific-1093 7762cca3 Fixing .md link 16b4b428 Changelog for issue #1106 457a5d57 Rephrase summaries; exception for summary schema; typo 476e1796 Update CHANGELOG.md ab58068f Update CHANGELOG.md 6fb42d9b update changelog 5890f7ec clarifications on using gsd as an asset field 7d3a94a8 Merge branch 'dev' into json-schema-summaries 0d8916ff remove scientific extension ee2ca2e4 Merge pull request #1102 from bradh/common_metadata_2021-04-25 ea23b295 minor editorial cleanup for common-metadata 314cfa13 include parent and root rel types, even for same file d42e3c15 Merge pull request #1092 from radiantearth/preview-rel-type 59ad837e Merge branch 'dev' into preview-rel-type b8d8b5e2 Merge pull request #1099 from radiantearth/utc 14fec945 More emphasis on UTC requirement 1f3b72b8 All timestamps in UTC #1095 dfb2300b Merge pull request #1091 from radiantearth/clarify-root b74d5b8c Better integrate example e2579282 Couple of changes for better alignment between the specs + list formatting 54d7be49 updates from review comments b388c25f Merge branch 'dev' into clarify-root 091af689 Merge pull request #1097 from bradh/patch-1 59df72d0 Some more details 233b757c Minor change to Collection usage wording eb7b9d29 Attempt to provide the main text ee8022b2 Example (WIP), more details 40ab9549 Update collection-spec/collection-spec.md 6755d41c First try at supporting JSON Schema in summaries #1045 6b24f7c9 put note up top 60bf0bcc more updates 5a994b7d Update overview.md 04664cbe Add preview relation type #1090 2be5e040 got rid of old changes that snuck in d0336de8 updates to make clear root can be catalog or collection bb15ca66 Merge pull request #1080 from radiantearth/fix_examples 16e80e96 Update examples/collection.json 1f9c4b06 Merge pull request #1086 from radiantearth/markdown 2daab18f Fix CI 77577a1b Merge branch 'dev' into fix_examples 2142d4b5 Merge pull request #1078 from radiantearth/rephrase-stac-extensions 6405e0d0 Merge branch 'dev' into fix_examples 9b438b64 Merge branch 'dev' into rephrase-stac-extensions 9f866c03 Merge branch 'dev' into markdown 40dfb8bf Merge pull request #1085 from radiantearth/extent-clarification 6a5a1535 Merge pull request #1087 from radiantearth/validate 93765a55 Made requirement for collection fields / rels clearer 82d3a229 Merge pull request #1089 from radiantearth/fix-collectionless-item 840a4cfc Remove collection field 9c6be4b5 Collectionless item has collection field & link #1081 6c8df300 Item: Validate that collection property is set if link with collection rel type is available #1088 90f8d37b Update STAC Node Validator and fix examples 6f572989 Fix Markdown be40027d Clarification on multiple bounding boxes in an extent. #1064 https://github.com/opengeospatial/ogcapi-features/pull/520 6b1bd4c3 fix complete 8617240e Update catalog-spec/catalog-spec.md 21ecb16d Update collection-spec/collection-spec.md 53686bdc simple item has no title 50d48628 stac_extensions for summarized fields 1ad7d1bc updated changelog a8354e12 datetime extent in collection 0684c3aa align spatio-temporal extents bcb5d962 removed duplicate the d73b43f9 Clarified that stac_extensions should also list extensions that are used in Collection summaries git-subtree-dir: stac-spec git-subtree-split: 789e90fba4c7119bc925d26f75f47bacf44c91e6 --- .circleci/config.yml | 17 +- .circleci/rc.yaml | 21 +- .github/pull_request_template.md | 6 +- .remarkignore | 1 - CHANGELOG.md | 146 ++++++--- CODE_OF_CONDUCT.md | 20 +- CONTRIBUTING.md | 14 +- README.md | 59 ++-- STAC-UML.drawio | 2 +- STAC-UML.pdf | Bin 46890 -> 78979 bytes best-practices.md | 185 +++++++----- catalog-spec/README.md | 14 +- catalog-spec/catalog-spec.md | 20 +- catalog-spec/json-schema/catalog-core.json | 139 --------- catalog-spec/json-schema/catalog.json | 77 ++++- collection-spec/README.md | 7 +- collection-spec/collection-spec.md | 190 ++++++++---- collection-spec/json-schema/collection.json | 140 +++++++-- examples/README.md | 4 +- examples/catalog.json | 17 +- .../collection-with-schemas.json | 277 ++++++++++++++++++ examples/collection-only/collection.json | 19 +- examples/collection.json | 55 ++-- examples/collectionless-item.json | 27 +- examples/core-item.json | 16 +- examples/extended-item.json | 22 +- .../extensions-collection/collection.json | 16 +- .../proj-example/proj-example.json | 15 +- examples/simple-item.json | 11 +- extensions/README.md | 87 ++++-- item-spec/common-metadata.md | 69 +++-- item-spec/item-spec.md | 80 +++-- item-spec/json-schema/basics.json | 2 +- item-spec/json-schema/datetime.json | 17 +- item-spec/json-schema/instrument.json | 2 +- item-spec/json-schema/item.json | 60 ++-- item-spec/json-schema/licensing.json | 2 +- item-spec/json-schema/provider.json | 2 +- overview.md | 59 +++- package.json | 4 +- principles.md | 20 +- process.md | 53 ++-- schema.json | 0 43 files changed, 1346 insertions(+), 648 deletions(-) delete mode 100644 .remarkignore delete mode 100644 catalog-spec/json-schema/catalog-core.json create mode 100644 examples/collection-only/collection-with-schemas.json delete mode 100644 schema.json 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 c3e02556007c08643fd135354dab0dc088fd2f07..37e7dff225f90311ada0c7231935a9da7532cc67 100644 GIT binary patch literal 78979 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.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://github.com/raw/radiantearth/stac-spec/v1.0.0-rc.2/examples/catalog.json", + "href": "https://github.com/raw/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://github.com/raw/radiantearth/stac-spec/v1.0.0-rc.2/examples/collection.json", + "href": "https://github.com/raw/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