From d73b43f98ff3ea29916043aeab43f54ddf88eadb Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Wed, 31 Mar 2021 11:55:56 +0200 Subject: [PATCH 01/61] Clarified that stac_extensions should also list extensions that are used in Collection summaries --- CHANGELOG.md | 4 ++++ catalog-spec/catalog-spec.md | 7 ++++--- collection-spec/collection-spec.md | 15 +++++---------- item-spec/item-spec.md | 9 ++++----- 4 files changed, 17 insertions(+), 18 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9a8027a1..adf212a0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,10 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. ## [Unreleased] +### Changed + +- Clarified that stac_extensions should also list extensions that are used in Collection summaries. ([#1077](https://github.com/radiantearth/stac-spec/issues/1077)) + ## [v1.0.0-rc.2] - 2021-03-30 ### Changed diff --git a/catalog-spec/catalog-spec.md b/catalog-spec/catalog-spec.md index 032d85a3..a0816c0d 100644 --- a/catalog-spec/catalog-spec.md +++ b/catalog-spec/catalog-spec.md @@ -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 the 'Scope' for each of the extensions. +This must **not** declare the extensions that are only implemented in child Collection or Items. ### Link Object diff --git a/collection-spec/collection-spec.md b/collection-spec/collection-spec.md index bd060dbd..15beec13 100644 --- a/collection-spec/collection-spec.md +++ b/collection-spec/collection-spec.md @@ -65,16 +65,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 or Items. #### id diff --git a/item-spec/item-spec.md b/item-spec/item-spec.md index 84209294..f270bc07 100644 --- a/item-spec/item-spec.md +++ b/item-spec/item-spec.md @@ -73,11 +73,10 @@ 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 From bcb5d962e4925c8f1331965bc3b65aa1b7d561fa Mon Sep 17 00:00:00 2001 From: Emmanuel Mathot Date: Wed, 31 Mar 2021 21:21:05 +0200 Subject: [PATCH 02/61] removed duplicate the --- catalog-spec/catalog-spec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/catalog-spec/catalog-spec.md b/catalog-spec/catalog-spec.md index a0816c0d..ee49870d 100644 --- a/catalog-spec/catalog-spec.md +++ b/catalog-spec/catalog-spec.md @@ -63,7 +63,7 @@ In general, STAC versions can be mixed, but please keep the [recommended best pr A list of extensions the Catalog 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 Catalog specification itself, -see the the 'Scope' for each of the extensions. +see the 'Scope' for each of the extensions. This must **not** declare the extensions that are only implemented in child Collection or Items. ### Link Object From 0684c3aa5d86998336db4c6820d6ea8f3e139ade Mon Sep 17 00:00:00 2001 From: Emmanuel Mathot Date: Thu, 1 Apr 2021 11:19:19 +0200 Subject: [PATCH 03/61] align spatio-temporal extents --- examples/collection.json | 8 ++++---- examples/extended-item.json | 6 +++--- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/examples/collection.json b/examples/collection.json index 4fadb641..79558f00 100644 --- a/examples/collection.json +++ b/examples/collection.json @@ -19,10 +19,10 @@ "spatial": { "bbox": [ [ - 172.911, - 1.343, - 172.955, - 1.3691 + 172.91173669923782, + 1.3438851951615003, + 172.95469614953714, + 1.3690476620161975 ] ] }, diff --git a/examples/extended-item.json b/examples/extended-item.json index 4012cb4a..8853f83e 100644 --- a/examples/extended-item.json +++ b/examples/extended-item.json @@ -45,9 +45,9 @@ "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" From a8354e12f04a1b66105d5b62422844cb97e85f7a Mon Sep 17 00:00:00 2001 From: Emmanuel Mathot Date: Thu, 1 Apr 2021 11:29:20 +0200 Subject: [PATCH 04/61] datetime extent in collection --- examples/collection.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/examples/collection.json b/examples/collection.json index 79558f00..6367f2eb 100644 --- a/examples/collection.json +++ b/examples/collection.json @@ -29,8 +29,8 @@ "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" ] ] } From 1ad7d1bcfb0c79cb69d9117498b05e196938a7e2 Mon Sep 17 00:00:00 2001 From: Emmanuel Mathot Date: Thu, 1 Apr 2021 11:31:16 +0200 Subject: [PATCH 05/61] updated changelog --- CHANGELOG.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9a8027a1..8ea394f3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,10 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. ## [Unreleased] +### Changed + +- Updated examples for automatic collection creation from code and validation + ## [v1.0.0-rc.2] - 2021-03-30 ### Changed From 50d4862884884b354546d79f9e22b163ad552b9a Mon Sep 17 00:00:00 2001 From: Emmanuel Mathot Date: Thu, 1 Apr 2021 11:34:07 +0200 Subject: [PATCH 06/61] stac_extensions for summarized fields --- examples/collection.json | 3 +++ 1 file changed, 3 insertions(+) diff --git a/examples/collection.json b/examples/collection.json index 6367f2eb..7be44d0b 100644 --- a/examples/collection.json +++ b/examples/collection.json @@ -1,6 +1,9 @@ { "id": "simple-collection", "type": "Collection", + "stac_extensions": [ + "https://stac-extensions.github.io/view/v1.0.0/schema.json" + ], "stac_version": "1.0.0-rc.2", "description": "A simple collection demonstrating core catalog fields with links to a couple of items", "title": "Simple Example Collection", From 53686bdc6e49419768786cd40a86b6a7540e6c50 Mon Sep 17 00:00:00 2001 From: Emmanuel Mathot Date: Thu, 1 Apr 2021 12:12:46 +0200 Subject: [PATCH 07/61] simple item has no title --- examples/collection.json | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/examples/collection.json b/examples/collection.json index 7be44d0b..26ac11c5 100644 --- a/examples/collection.json +++ b/examples/collection.json @@ -72,8 +72,7 @@ { "rel": "item", "href": "./simple-item.json", - "type": "application/geo+json", - "title": "Simple Item" + "type": "application/geo+json" }, { "rel": "item", From 21ecb16d697d9b1e1d022111ef372ac7b86f9674 Mon Sep 17 00:00:00 2001 From: Matthew Hanson Date: Mon, 5 Apr 2021 17:10:37 -0400 Subject: [PATCH 08/61] Update collection-spec/collection-spec.md Co-authored-by: Phil Varner --- collection-spec/collection-spec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/collection-spec/collection-spec.md b/collection-spec/collection-spec.md index 15beec13..fe3c903f 100644 --- a/collection-spec/collection-spec.md +++ b/collection-spec/collection-spec.md @@ -69,7 +69,7 @@ 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 or Items. +This must **not** declare the extensions that are only implemented in child Collection objects or child Item objects. #### id From 8617240e740e76ffbecb27e7edc0b3ed60474750 Mon Sep 17 00:00:00 2001 From: Matthew Hanson Date: Mon, 5 Apr 2021 17:10:45 -0400 Subject: [PATCH 09/61] Update catalog-spec/catalog-spec.md Co-authored-by: Phil Varner --- catalog-spec/catalog-spec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/catalog-spec/catalog-spec.md b/catalog-spec/catalog-spec.md index ee49870d..573e848a 100644 --- a/catalog-spec/catalog-spec.md +++ b/catalog-spec/catalog-spec.md @@ -64,7 +64,7 @@ A list of extensions the Catalog 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 Catalog specification itself, see the 'Scope' for each of the extensions. -This must **not** declare the extensions that are only implemented in child Collection or Items. +This must **not** declare the extensions that are only implemented in child Collection objects or child Item objects. ### Link Object From 6b1bd4c3524b31371bf564532205ca0ed4a66f24 Mon Sep 17 00:00:00 2001 From: Emmanuel Mathot Date: Sat, 10 Apr 2021 17:58:30 +0200 Subject: [PATCH 10/61] fix complete --- examples/collection.json | 31 ++++++++++++++++++++++--------- examples/core-item.json | 2 +- examples/extended-item.json | 2 +- 3 files changed, 24 insertions(+), 11 deletions(-) diff --git a/examples/collection.json b/examples/collection.json index 26ac11c5..4325aec4 100644 --- a/examples/collection.json +++ b/examples/collection.json @@ -41,26 +41,39 @@ "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": [ diff --git a/examples/core-item.json b/examples/core-item.json index 0b453dd4..a71eb08f 100644 --- a/examples/core-item.json +++ b/examples/core-item.json @@ -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" ], diff --git a/examples/extended-item.json b/examples/extended-item.json index 8853f83e..10db0ce1 100644 --- a/examples/extended-item.json +++ b/examples/extended-item.json @@ -50,7 +50,7 @@ "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, From be40027ddc5c2cc1afcd7b5e51e9f7fe0dc1a224 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Wed, 14 Apr 2021 18:19:01 +0200 Subject: [PATCH 11/61] Clarification on multiple bounding boxes in an extent. #1064 https://github.com/opengeospatial/ogcapi-features/pull/520 --- CHANGELOG.md | 3 +++ collection-spec/collection-spec.md | 14 ++++++++++++-- 2 files changed, 15 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9a8027a1..0d51bcb3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,9 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. ## [Unreleased] +### 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)) + ## [v1.0.0-rc.2] - 2021-03-30 ### Changed diff --git a/collection-spec/collection-spec.md b/collection-spec/collection-spec.md index f781bb91..d3b4c2da 100644 --- a/collection-spec/collection-spec.md +++ b/collection-spec/collection-spec.md @@ -147,7 +147,12 @@ 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. @@ -161,7 +166,12 @@ 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. From 6f57298924b75b0556200c6a3231cdaeb293eab4 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Thu, 15 Apr 2021 14:07:24 +0200 Subject: [PATCH 12/61] Fix Markdown --- .circleci/rc.yaml | 21 +++-- .github/pull_request_template.md | 6 +- .remarkignore | 1 - CHANGELOG.md | 90 ++++++++++----------- CODE_OF_CONDUCT.md | 20 ++--- CONTRIBUTING.md | 14 ++-- README.md | 36 +++++---- best-practices.md | 107 +++++++++++++++---------- catalog-spec/README.md | 14 +++- collection-spec/README.md | 7 +- collection-spec/collection-spec.md | 123 ++++++++++++++++++++--------- examples/README.md | 4 +- extensions/README.md | 37 ++++++--- item-spec/common-metadata.md | 23 ++++-- item-spec/item-spec.md | 58 +++++++++----- overview.md | 12 +-- principles.md | 20 ++--- process.md | 53 +++++++------ 18 files changed, 387 insertions(+), 259 deletions(-) delete mode 100644 .remarkignore 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..716a6dd7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,4 @@ + # Changelog All notable changes to this project will be documented in this file. @@ -81,7 +82,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 +97,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 +120,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 +154,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 +171,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 +214,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 +236,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 +339,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 +351,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 +373,10 @@ Full list of issues and pull requests at [v1.0.0-rc.2]: [v1.0.0-rc.1]: 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..a51643b8 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) @@ -83,23 +84,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/best-practices.md b/best-practices.md index 87baf0c8..77e01e6b 100644 --- a/best-practices.md +++ b/best-practices.md @@ -61,7 +61,8 @@ STAC strives to make geospatial information more accessible, by putting it on th different tools will be able to load and display public-facing STAC data. But the web runs on a [Same origin policy](https://en.wikipedia.org/wiki/Same-origin_policy), preventing web pages from loading information from other web locations to prevent malicious scripts from accessing sensitive data. This means that by default a web page would only be able to load STAC -[Item](item-spec/item-spec.md) objects from the same server the page is on. [Cross-origin resource sharing](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing), +[Item](item-spec/item-spec.md) objects from the same server the page is on. +[Cross-origin resource sharing](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing), also known as 'CORS' is a protocol to enable safe communication across origins. But most web services turn it off by default. This is generally a good thing, but unfortunately if CORS is not enabled then any browser-based STAC tool will not work. @@ -122,20 +123,26 @@ should have its own location and just be part of the wider web. It is very common that large, freely available datasets are set up with a 'requester pays' configuration. This is an option [on AWS](https://docs.aws.amazon.com/AmazonS3/latest/userguide/RequesterPaysBuckets.html) and [on Google Cloud](https://cloud.google.com/storage/docs/requester-pays), that enables data providers to make their data -available to everyone, while the cloud platform charges access costs (such as per-request and data '[egress](https://www.hostdime.com/blog/data-egress-fees-cloud/)') to the user accessing the data. +available to everyone, while the cloud platform charges access costs +(such as per-request and data '[egress](https://www.hostdime.com/blog/data-egress-fees-cloud/)') to the user accessing the data. For popular datasets that are large in size the egress costs can be substantial, to the point where much less data would be available if the cost of distribution was always on the data provider. For data providers using STAC with requester pays buckets, there are two main recommendations: -1) Put the STAC JSON in a separate bucket that is public for everyone and **not** requestor pays. This enables the STAC metadata -to be far more crawlable and searchable, but the cost of the egress of STAC files should be miniscule compared to that of -the actual data. The STAC community can help you work with cloud providers for potential free hosting if you are doing open -data as requestor pays and aren't able to pay the costs of a completely open STAC bucket, as they are most all supportive of -STAC (but no guarantees and it may be on an alternate cloud). -2) For Asset href values to resources in a requestor pays bucket, use the cloud provider-specific protocol (e.g., `s3://` on AWS and `gs://` on Google Cloud) instead of an `https://` url. Most clients do not have special handling for `https://` links to cloud provider resources that require a requestor pays flag and authentication, so they simply fail. Many clients have special handling for `s3://` or `gs://` URLs that will add a requestor pays parameter and will apply appropriate authentication to the request. -Using cloud-specific protocols will at least give users an option to register a paid account and allow the data provider to properly charge for access. -STAC-specific tools in turn can look for the cloud-specific protocols and know to use the requestor pays feature for that specific cloud platform. +1. Put the STAC JSON in a separate bucket that is public for everyone and **not** requestor pays. This enables the STAC metadata + to be far more crawlable and searchable, but the cost of the egress of STAC files should be miniscule compared to that of + the actual data. The STAC community can help you work with cloud providers for potential free hosting if you are doing open + data as requestor pays and aren't able to pay the costs of a completely open STAC bucket, as they are most all supportive of + STAC (but no guarantees and it may be on an alternate cloud). +2. For Asset href values to resources in a requestor pays bucket, use the cloud provider-specific protocol + (e.g., `s3://` on AWS and `gs://` on Google Cloud) instead of an `https://` url. + Most clients do not have special handling for `https://` links to cloud provider resources that require a requestor pays flag and authentication, + so they simply fail. Many clients have special handling for `s3://` or `gs://` URLs + that will add a requestor pays parameter and will apply appropriate authentication to the request. + Using cloud-specific protocols will at least give users an option to register a paid account and + allow the data provider to properly charge for access. + STAC-specific tools in turn can look for the cloud-specific protocols and know to use the requestor pays feature for that specific cloud platform. ## Item Practices @@ -161,8 +168,9 @@ flexible enough that providers can fill it with tens or even hundreds of fields providers have lots of metadata then that can be linked to in the [Asset Object](item-spec/item-spec.md#asset-object) (recommended) or in a [Link Object](item-spec/item-spec.md#link-object). There is a lot of metadata that is only of relevance to loading and processing data, and while STAC does not prohibit providers from putting those type of fields in their items, -it is not recommended. For very large catalogs (hundreds of millions of records), every additional field that is indexed will cost substantial money, so data providers are advised to just put the fields to be searched in STAC, so [STAC API](https://github.com/radiantearth/stac-api-spec) -providers don't have bloated indices that no one actually uses. +it is not recommended. For very large catalogs (hundreds of millions of records), +every additional field that is indexed will cost substantial money, so data providers are advised to just put the fields to be searched in STAC and +[STAC API](https://github.com/radiantearth/stac-api-spec) providers don't have bloated indices that no one actually uses. ### Datetime selection @@ -244,17 +252,24 @@ found in Item properties at the asset level. This mechanism of overriding or pro makes discovery more difficult and should generally be avoided. However, there are some core and extension fields for which providing them at at the Asset level can prove to be very useful for using the data. -- `datetime`: Provide individual timestamp on an Item, in case the Item has a `start_datetime` and `end_datetime`, but an Asset is for one specific time. +- `datetime`: Provide individual timestamp on an Item, in case the Item has a `start_datetime` and `end_datetime`, + but an Asset is for one specific time. - `gsd` ([Common Metadata](item-spec/common-metadata.md#instrument)): Specify some assets with different spatial resolution than the overall best resolution. -- `eo:bands` ([EO extension](https://github.com/stac-extensions/eo/)): Provide spectral band information, and order of bands, within an individual asset. -- `proj:epsg`/`proj:wkt2`/`proj:projjson` ([projection extension](https://github.com/stac-extensions/projection/)): Specify different projection for some assets. If the projection is different - for all assets it should probably not be provided as an Item property. If most assets are one projection, and there is - a single reprojected version (such as a Web Mercator preview image), it is sensible to specify the main projection in the - Item and the alternate projection for the affected asset(s). -- `proj:shape`/`proj:transform` ([projection extension](https://github.com/stac-extensions/projection/)): If assets have different spatial resolutions and slightly different exact bounding boxes, specify these per asset to indicate the size of the asset in pixels and its exact GeoTransform in the native projection. -- `sar:polarizations` ([sar extension](https://github.com/stac-extensions/sar)): Provide the polarization content and ordering of a specific asset, similar to `eo:bands`. -- `sar:product_type` ([sar extension](https://github.com/stac-extensions/sar)): If mixing multiple product types within a single Item, this can be used to specify the product_type for each asset. +- `eo:bands` ([EO extension](https://github.com/stac-extensions/eo/)): + Provide spectral band information, and order of bands, within an individual asset. +- `proj:epsg`/`proj:wkt2`/`proj:projjson` ([projection extension](https://github.com/stac-extensions/projection/)): + Specify different projection for some assets. If the projection is different + for all assets it should probably not be provided as an Item property. If most assets are one projection, and there is + a single reprojected version (such as a Web Mercator preview image), it is sensible to specify the main projection in the + Item and the alternate projection for the affected asset(s). +- `proj:shape`/`proj:transform` ([projection extension](https://github.com/stac-extensions/projection/)): + If assets have different spatial resolutions and slightly different exact bounding boxes, + specify these per asset to indicate the size of the asset in pixels and its exact GeoTransform in the native projection. +- `sar:polarizations` ([sar extension](https://github.com/stac-extensions/sar)): + Provide the polarization content and ordering of a specific asset, similar to `eo:bands`. +- `sar:product_type` ([sar extension](https://github.com/stac-extensions/sar)): + If mixing multiple product types within a single Item, this can be used to specify the product_type for each asset. ### Working with Media Types @@ -448,11 +463,13 @@ if you follow these recommendations. 1. Root documents (Catalogs / Collections) should be at the root of a directory tree containing the static catalog. 2. Catalogs should be named `catalog.json` and Collections should be named `collection.json`. 3. Items should be named `.json`. -4. Sub-Catalogs should be stored in subdirectories of their parent (and only 1 subdirectory deeper than a document's parent) (e.g. `.../sample/sub1/catalog.json`). +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, +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. #### Dynamic Catalog Layout @@ -487,31 +504,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 +557,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 +565,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 +584,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 @@ -615,7 +637,8 @@ a number of the common official relations that are used in production STAC imple ### 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 +657,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 +692,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. 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/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..ab6963bc 100644 --- a/collection-spec/collection-spec.md +++ b/collection-spec/collection-spec.md @@ -27,17 +27,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 @@ -84,7 +85,11 @@ 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 @@ -92,16 +97,29 @@ Collections are *strongly recommended* to provide summaries of the values of fie 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. +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. +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. 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,19 @@ 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**: 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). -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 +190,22 @@ 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, 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). -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 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. -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]]`. +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]]`. ### 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 +216,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,8 +238,10 @@ 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. @@ -216,9 +255,13 @@ This is done where there is not a clear official option, or where STAC uses an o | 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 @@ -236,8 +279,10 @@ or streamed. The definition provided here, at the Collection level, is the same ### Stats 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 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. 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`. @@ -255,6 +300,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/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/extensions/README.md b/extensions/README.md index e864f3ce..3b04a1f2 100644 --- a/extensions/README.md +++ b/extensions/README.md @@ -35,11 +35,13 @@ Each extension has at least one *owner*. You can find extension owners in each e ## 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. +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. + 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. ## Stable STAC Extensions @@ -79,7 +81,8 @@ Best practices for extension proposals are still emerging in this section. ### 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 +166,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..07df2234 100644 --- a/item-spec/common-metadata.md +++ b/item-spec/common-metadata.md @@ -61,7 +61,9 @@ While a STAC Item can have a nominal datetime describing the capture, these prop 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. -**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 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`. | 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,10 +122,11 @@ 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 last element of the list. ## Instrument @@ -182,5 +188,6 @@ The GSD of a sensor can vary depending on off-nadir and wavelength, so it is at 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. +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..5ab33ef7 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) @@ -84,12 +84,14 @@ structure, it must be listed in all affected parts (e.g. Catalog, Collection and 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. 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#field-and-id-formatting) for additional recommendations. #### assets @@ -108,7 +110,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 @@ -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,8 +183,10 @@ 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. @@ -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/overview.md b/overview.md index 3d752aae..b498f7b5 100644 --- a/overview.md +++ b/overview.md @@ -21,10 +21,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 @@ -68,8 +68,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, 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 From 90f8d37ba6b065240061c8da33cecfffe89b67f0 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Thu, 15 Apr 2021 14:37:12 +0200 Subject: [PATCH 13/61] Update STAC Node Validator and fix examples --- examples/extensions-collection/proj-example/proj-example.json | 1 - package.json | 2 +- 2 files changed, 1 insertion(+), 2 deletions(-) diff --git a/examples/extensions-collection/proj-example/proj-example.json b/examples/extensions-collection/proj-example/proj-example.json index 91fa8130..e8e0d89f 100644 --- a/examples/extensions-collection/proj-example/proj-example.json +++ b/examples/extensions-collection/proj-example/proj-example.json @@ -242,7 +242,6 @@ "eo:bands": [ { "name": "B8", - "common_name": "panchromatic", "center_wavelength": 0.59, "full_width_half_max": 0.18 } diff --git a/package.json b/package.json index 3fb2aeee..a787cad3 100644 --- a/package.json +++ b/package.json @@ -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.0.1" } } From 6c8df30064e2552b0070404effca6e9acbc836cb Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Thu, 15 Apr 2021 16:07:22 +0200 Subject: [PATCH 14/61] Item: Validate that collection property is set if link with collection rel type is available #1088 --- .../proj-example/proj-example.json | 5 +++ item-spec/item-spec.md | 2 +- item-spec/json-schema/item.json | 42 ++++++++++++++++--- 3 files changed, 42 insertions(+), 7 deletions(-) diff --git a/examples/extensions-collection/proj-example/proj-example.json b/examples/extensions-collection/proj-example/proj-example.json index e8e0d89f..71d3b2d3 100644 --- a/examples/extensions-collection/proj-example/proj-example.json +++ b/examples/extensions-collection/proj-example/proj-example.json @@ -219,6 +219,11 @@ "rel": "parent", "href": "../collection.json", "type": "application/json" + }, + { + "rel": "collection", + "href": "../collection.json", + "type": "application/json" } ], "assets": { diff --git a/item-spec/item-spec.md b/item-spec/item-spec.md index 84209294..e36b3551 100644 --- a/item-spec/item-spec.md +++ b/item-spec/item-spec.md @@ -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 diff --git a/item-spec/json-schema/item.json b/item-spec/json-schema/item.json index 34d351f3..e228e2d2 100644 --- a/item-spec/json-schema/item.json +++ b/item-spec/json-schema/item.json @@ -159,12 +159,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": {} + } } } } From 9c6be4b5ece6cf774228432eed0dea36c66a6f3c Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Thu, 15 Apr 2021 16:12:31 +0200 Subject: [PATCH 15/61] Collectionless item has collection field & link #1081 --- CHANGELOG.md | 1 + examples/catalog.json | 6 ++++++ examples/collectionless-item.json | 12 +++--------- 3 files changed, 10 insertions(+), 9 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9a8027a1..ac468ee2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -19,6 +19,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)) diff --git a/examples/catalog.json b/examples/catalog.json index 1bac09f9..c309c1f6 100644 --- a/examples/catalog.json +++ b/examples/catalog.json @@ -21,6 +21,12 @@ "type": "application/json", "title": "Collection with no items (standalone)" }, + { + "rel": "item", + "href": "./collectionless-item.json", + "type": "application/json", + "title": "Collection with no items (standalone)" + }, { "rel": "self", "href": "https://raw.githubusercontent.com/radiantearth/stac-spec/v1.0.0-rc.2/examples/catalog.json", diff --git a/examples/collectionless-item.json b/examples/collectionless-item.json index 250bb704..c2384f52 100644 --- a/examples/collectionless-item.json +++ b/examples/collectionless-item.json @@ -73,20 +73,14 @@ }, "collection": "CS3", "links": [ - { - "rel": "collection", - "href": "./collection.json", - "type": "application/json", - "title": "Simple Example Collection" - }, { "rel": "root", - "href": "./collection.json", + "href": "./catalog.json", "type": "application/json" }, { - "rel": "root", - "href": "./collection.json", + "rel": "parent", + "href": "./catalog.json", "type": "application/json" }, { From 840a4cfc512f615767ee28eadb0a18b7103bdd92 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Thu, 15 Apr 2021 16:18:58 +0200 Subject: [PATCH 16/61] Remove collection field --- examples/collectionless-item.json | 1 - 1 file changed, 1 deletion(-) diff --git a/examples/collectionless-item.json b/examples/collectionless-item.json index c2384f52..a1b890c1 100644 --- a/examples/collectionless-item.json +++ b/examples/collectionless-item.json @@ -71,7 +71,6 @@ "cs:sat_id": "CS3", "cs:product_level": "LV1B" }, - "collection": "CS3", "links": [ { "rel": "root", From 93765a55968d66b3efbf5f9bc8594623132cd07b Mon Sep 17 00:00:00 2001 From: Chris Holmes Date: Thu, 15 Apr 2021 08:15:50 -0700 Subject: [PATCH 17/61] Made requirement for collection fields / rels clearer --- item-spec/item-spec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/item-spec/item-spec.md b/item-spec/item-spec.md index e36b3551..6349b015 100644 --- a/item-spec/item-spec.md +++ b/item-spec/item-spec.md @@ -183,7 +183,7 @@ This happens where there is not a clear official option, or where STAC uses an o | 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. | +| 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 From 2daab18fd75b6b45eae9bf14ccc4da9f6db1177c Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Thu, 15 Apr 2021 17:38:02 +0200 Subject: [PATCH 18/61] Fix CI --- collection-spec/collection-spec.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/collection-spec/collection-spec.md b/collection-spec/collection-spec.md index a6834e0c..3f5f954a 100644 --- a/collection-spec/collection-spec.md +++ b/collection-spec/collection-spec.md @@ -168,12 +168,14 @@ The object describes the spatial extents of the Collection. | ------- | ------------ | -------------------------------------------------------------------- | | bbox | \[\[number]] | **REQUIRED.** Potential *spatial extents* covered by the Collection. | -**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. +**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). +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 From 16e80e963f616b293f0725ea62975ad8d9188dd4 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Thu, 15 Apr 2021 17:47:15 +0200 Subject: [PATCH 19/61] Update examples/collection.json Co-authored-by: Chris Holmes --- examples/collection.json | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/examples/collection.json b/examples/collection.json index 4325aec4..87047035 100644 --- a/examples/collection.json +++ b/examples/collection.json @@ -85,7 +85,8 @@ { "rel": "item", "href": "./simple-item.json", - "type": "application/geo+json" + "type": "application/geo+json", + "title": "Simple Item" }, { "rel": "item", From d0336de88e20485ca8d45c4f09dc23a2e2ccb042 Mon Sep 17 00:00:00 2001 From: Chris Holmes Date: Mon, 19 Apr 2021 21:05:06 -0700 Subject: [PATCH 20/61] updates to make clear root can be catalog or collection --- catalog-spec/catalog-spec.md | 59 ++++++++++++------------------ collection-spec/collection-spec.md | 4 +- overview.md | 22 ++++++----- 3 files changed, 39 insertions(+), 46 deletions(-) diff --git a/catalog-spec/catalog-spec.md b/catalog-spec/catalog-spec.md index 573e848a..b3fa521c 100644 --- a/catalog-spec/catalog-spec.md +++ b/catalog-spec/catalog-spec.md @@ -1,8 +1,7 @@ -# STAC Catalog Specification +# STAC Catalog Specification - [Catalog fields](#catalog-fields) - [Additional Field Information](#additional-field-information) - - [stac_version](#stac_version) - [stac_extensions](#stac_extensions) - [Link Object](#link-object) - [Relation types](#relation-types) @@ -11,18 +10,15 @@ - [STAC Media Types](#stac-media-types) - [Extensions](#extensions) -This document explains the structure and content of a STAC **Catalog** object. A STAC Catalog object -represents a logical group of other Catalog, -[Collection](../collection-spec/collection-spec.md), and [Item](../item-spec/item-spec.md) objects. -These Items can be linked to directly from a Catalog, or the Catalog can link to other Catalogs (often called -sub-catalogs) that contain links to Collections and Items. The division of sub-catalogs is up to the implementor, -but is generally done to aid the ease of online browsing by people. +This document explains the structure and content of a STAC Catalog. A STAC Catalog is a +[Collection](../collection-spec/collection-spec.md) of [STAC Items](../item-spec/item-spec.md). These Items can be +linked to directly from a Catalog, or the Catalog can link to other Catalogs (often called sub-Catalogs) that contain +links to Items. The division of sub-catalogs is up to the implementor, but is generally done to aid the ease of +online browsing by people. -A Catalog object will typically be the entry point into a STAC catalog. Their -purpose is discovery: to be browsed by people or be crawled -by clients to build a searchable index. - -Any JSON object that contains all the required fields is a valid STAC Catalog object. +Catalogs are not intended to be queried. Their purpose is discovery: to be browsed by people and crawled +by machines to build a search index. A Catalog can be represented in JSON format. Any JSON object +that contains all the required fields is a valid STAC Catalog. - [Examples](../examples/) - See an example [catalog.json](../examples/catalog.json). The [collection.json](../examples/collection.json) is also a valid @@ -43,8 +39,8 @@ also a valid STAC Catalog. | Element | Type | Description | | --------------- | ------------- | ------------------------------------------------------------ | +| stac_version | string | **REQUIRED.** The STAC version the Catalog implements. STAC versions can be mixed, but please keep the [recommended best practices](../best-practices.md#mixing-stac-versions) in mind. | | type | string | **REQUIRED.** Set to `Catalog` if this Catalog only implements the Catalog spec. | -| stac_version | string | **REQUIRED.** The STAC version the Catalog implements. | | stac_extensions | \[string] | A list of extension identifiers the Catalog implements. | | id | string | **REQUIRED.** Identifier for the Catalog. | | title | string | A short descriptive one-line title for the Catalog. | @@ -54,29 +50,22 @@ also a valid STAC Catalog. ### Additional Field Information -#### stac_version - -In general, STAC versions can be mixed, but please keep the [recommended best practices](../best-practices.md#mixing-stac-versions) in mind. - #### stac_extensions -A list of extensions the Catalog 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 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. +A list of extensions the Catalog implements. This does NOT declare the extensions of children or Items. The list contains URLs to the JSON Schema files it can be validated against. For [core extensions](../extensions/README.md#core-stac-extensions), a "shortcut" can be used. This means you can specify the folder name of the extension, for example `view` for the View extension. If the versions of the extension and the Catalog diverge, you can specify the URL of the JSON schema file. +This list must only contain extensions that extend the Catalog itself, see the the 'Scope' column in the list of extensions. ### Link Object This object describes a relationship with another entity. Data providers are advised to be liberal with links. -| Field Name | Type | Description | -| ---------- | ------ | ----------- | -| href | string | **REQUIRED.** The actual link in the format of an URL. Relative and absolute links are both allowed. | +| Field Name | Type | Description | +| ---------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------- | +| href | string | **REQUIRED.** The actual link in the format of an URL. Relative and absolute links are both allowed. | | rel | string | **REQUIRED.** Relationship between the current document and the linked document. See chapter ["Relation types"](#relation-types) for more information. | -| type | string | [Media type](#media-types) of the referenced entity. | -| title | string | A human readable title to be used in rendered displays of the link. | +| type | string | [Media type](#media-types) of the referenced entity. | +| title | string | A human readable title to be used in rendered displays of the link. | For a full discussion of the situations where relative and absolute links are recommended see the ['Use of links'](../best-practices.md#use-of-links) section of the STAC best practices. @@ -88,8 +77,8 @@ The following types are commonly used as `rel` types in the Link Object of a STA | Type | Description | | ------- | ----------- | | 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. | +| root | STRONGLY RECOMMENDED. URL to the root STAC entity (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 entity (Catalog or Collection). Non-root Catalogs should include a link to their parent. | | child | URL to a child STAC Catalog or Collection. | | item | URL to a STAC Item. | @@ -117,11 +106,11 @@ A STAC Catalog is a JSON file ([RFC 8259](https://tools.ietf.org/html/rfc8259)), The following table lists the Media Types to use for STAC structures. -| Media Type | Description | -| ---------------------- | ---------------------------------------------------------- | -| `application/geo+json` | A STAC [Item](../item-spec/item-spec.md) | -| `application/json` | A STAC Catalog | -| `application/json` | A STAC [Collection](../collection-spec/collection-spec.md) | +| Media Type | Description | +| ------------------------------ | ------------------------------------------------------------ | +| `application/geo+json` | A STAC [Item](../item-spec/item-spec.md) | +| `application/json` | A STAC [Catalog](#stac-catalog-specification) | +| `application/json` | A STAC [Collection](../collection-spec/collection-spec.md) | ## Extensions diff --git a/collection-spec/collection-spec.md b/collection-spec/collection-spec.md index f4e331c7..280a948e 100644 --- a/collection-spec/collection-spec.md +++ b/collection-spec/collection-spec.md @@ -252,8 +252,8 @@ This is done where there is not a clear official option, or where STAC uses an o | 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. | +| 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 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. | diff --git a/overview.md b/overview.md index b498f7b5..68bef150 100644 --- a/overview.md +++ b/overview.md @@ -53,10 +53,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 @@ -78,10 +79,10 @@ 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 @@ -91,14 +92,14 @@ points to [STAC Items](item-spec/README.md), or to other STAC catalogs. It provi 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 -- 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 @@ -137,6 +138,9 @@ root catalog might be a sub-catalog of someone else's structure. The goal is for information and links they want to, while also encouraging a natural web of information to arise as Catalogs and Items are linked to across the web. +*NOTE: The above examples all say Catalog, but those can all be Collections as well, as it has all the fields necessary to +serve as a Catalog* + ### Static and Dynamic Catalogs The Catalog specification is designed so it can be implemented as easily as possibly. This can be as simple as @@ -164,8 +168,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 From 2be5e0408834ad4e65a2fca0213c06ec56afb7da Mon Sep 17 00:00:00 2001 From: Chris Holmes Date: Mon, 19 Apr 2021 21:13:25 -0700 Subject: [PATCH 21/61] got rid of old changes that snuck in --- catalog-spec/catalog-spec.md | 59 +++++++++++++++++++++--------------- 1 file changed, 35 insertions(+), 24 deletions(-) diff --git a/catalog-spec/catalog-spec.md b/catalog-spec/catalog-spec.md index b3fa521c..573e848a 100644 --- a/catalog-spec/catalog-spec.md +++ b/catalog-spec/catalog-spec.md @@ -1,7 +1,8 @@ -# STAC Catalog Specification +# STAC Catalog Specification - [Catalog fields](#catalog-fields) - [Additional Field Information](#additional-field-information) + - [stac_version](#stac_version) - [stac_extensions](#stac_extensions) - [Link Object](#link-object) - [Relation types](#relation-types) @@ -10,15 +11,18 @@ - [STAC Media Types](#stac-media-types) - [Extensions](#extensions) -This document explains the structure and content of a STAC Catalog. A STAC Catalog is a -[Collection](../collection-spec/collection-spec.md) of [STAC Items](../item-spec/item-spec.md). These Items can be -linked to directly from a Catalog, or the Catalog can link to other Catalogs (often called sub-Catalogs) that contain -links to Items. The division of sub-catalogs is up to the implementor, but is generally done to aid the ease of -online browsing by people. +This document explains the structure and content of a STAC **Catalog** object. A STAC Catalog object +represents a logical group of other Catalog, +[Collection](../collection-spec/collection-spec.md), and [Item](../item-spec/item-spec.md) objects. +These Items can be linked to directly from a Catalog, or the Catalog can link to other Catalogs (often called +sub-catalogs) that contain links to Collections and Items. The division of sub-catalogs is up to the implementor, +but is generally done to aid the ease of online browsing by people. -Catalogs are not intended to be queried. Their purpose is discovery: to be browsed by people and crawled -by machines to build a search index. A Catalog can be represented in JSON format. Any JSON object -that contains all the required fields is a valid STAC Catalog. +A Catalog object will typically be the entry point into a STAC catalog. Their +purpose is discovery: to be browsed by people or be crawled +by clients to build a searchable index. + +Any JSON object that contains all the required fields is a valid STAC Catalog object. - [Examples](../examples/) - See an example [catalog.json](../examples/catalog.json). The [collection.json](../examples/collection.json) is also a valid @@ -39,8 +43,8 @@ also a valid STAC Catalog. | Element | Type | Description | | --------------- | ------------- | ------------------------------------------------------------ | -| stac_version | string | **REQUIRED.** The STAC version the Catalog implements. STAC versions can be mixed, but please keep the [recommended best practices](../best-practices.md#mixing-stac-versions) in mind. | | type | string | **REQUIRED.** Set to `Catalog` if this Catalog only implements the Catalog spec. | +| stac_version | string | **REQUIRED.** The STAC version the Catalog implements. | | stac_extensions | \[string] | A list of extension identifiers the Catalog implements. | | id | string | **REQUIRED.** Identifier for the Catalog. | | title | string | A short descriptive one-line title for the Catalog. | @@ -50,22 +54,29 @@ also a valid STAC Catalog. ### Additional Field Information +#### stac_version + +In general, STAC versions can be mixed, but please keep the [recommended best practices](../best-practices.md#mixing-stac-versions) in mind. + #### stac_extensions -A list of extensions the Catalog implements. This does NOT declare the extensions of children or Items. The list contains URLs to the JSON Schema files it can be validated against. For [core extensions](../extensions/README.md#core-stac-extensions), a "shortcut" can be used. This means you can specify the folder name of the extension, for example `view` for the View extension. If the versions of the extension and the Catalog diverge, you can specify the URL of the JSON schema file. -This list must only contain extensions that extend the Catalog itself, see the the 'Scope' column in the list of extensions. +A list of extensions the Catalog 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 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 This object describes a relationship with another entity. Data providers are advised to be liberal with links. -| Field Name | Type | Description | -| ---------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------- | -| href | string | **REQUIRED.** The actual link in the format of an URL. Relative and absolute links are both allowed. | +| Field Name | Type | Description | +| ---------- | ------ | ----------- | +| href | string | **REQUIRED.** The actual link in the format of an URL. Relative and absolute links are both allowed. | | rel | string | **REQUIRED.** Relationship between the current document and the linked document. See chapter ["Relation types"](#relation-types) for more information. | -| type | string | [Media type](#media-types) of the referenced entity. | -| title | string | A human readable title to be used in rendered displays of the link. | +| type | string | [Media type](#media-types) of the referenced entity. | +| title | string | A human readable title to be used in rendered displays of the link. | For a full discussion of the situations where relative and absolute links are recommended see the ['Use of links'](../best-practices.md#use-of-links) section of the STAC best practices. @@ -77,8 +88,8 @@ The following types are commonly used as `rel` types in the Link Object of a STA | Type | Description | | ------- | ----------- | | 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 entity (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 entity (Catalog or Collection). Non-root Catalogs should include a link to their parent. | +| 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. | | item | URL to a STAC Item. | @@ -106,11 +117,11 @@ A STAC Catalog is a JSON file ([RFC 8259](https://tools.ietf.org/html/rfc8259)), The following table lists the Media Types to use for STAC structures. -| Media Type | Description | -| ------------------------------ | ------------------------------------------------------------ | -| `application/geo+json` | A STAC [Item](../item-spec/item-spec.md) | -| `application/json` | A STAC [Catalog](#stac-catalog-specification) | -| `application/json` | A STAC [Collection](../collection-spec/collection-spec.md) | +| Media Type | Description | +| ---------------------- | ---------------------------------------------------------- | +| `application/geo+json` | A STAC [Item](../item-spec/item-spec.md) | +| `application/json` | A STAC Catalog | +| `application/json` | A STAC [Collection](../collection-spec/collection-spec.md) | ## Extensions From 04664cbe090ce500b3ec61c0f3e14a08dc78d8ff Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Tue, 20 Apr 2021 15:34:08 +0200 Subject: [PATCH 22/61] Add preview relation type #1090 --- CHANGELOG.md | 4 ++++ best-practices.md | 5 +++-- 2 files changed, 7 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 2e5a4424..e08c397a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. ## [Unreleased] +### Added + +- Added `preview` relation type for interoperable thumbnails to best practices. ([#1090](https://github.com/radiantearth/stac-spec/issues/1090)) + ### 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)) diff --git a/best-practices.md b/best-practices.md index 77e01e6b..b12638d0 100644 --- a/best-practices.md +++ b/best-practices.md @@ -627,13 +627,14 @@ 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. | +| preview | 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. | ### Versioning for Catalogs From 5a994b7dac681b82529c152d5182f6f2099d29de Mon Sep 17 00:00:00 2001 From: Chris Holmes Date: Tue, 20 Apr 2021 08:35:29 -0700 Subject: [PATCH 23/61] Update overview.md Co-authored-by: Matthias Mohr --- overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/overview.md b/overview.md index 68bef150..4e9d84b5 100644 --- a/overview.md +++ b/overview.md @@ -93,7 +93,7 @@ linking structure that can be used recursively so that many Items can be include 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 +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 From 60bf0bcc7e79b4d171cafea23eae864646ec8601 Mon Sep 17 00:00:00 2001 From: Chris Holmes Date: Tue, 20 Apr 2021 08:36:50 -0700 Subject: [PATCH 24/61] more updates --- best-practices.md | 18 +++++++++++------- item-spec/item-spec.md | 2 +- 2 files changed, 12 insertions(+), 8 deletions(-) diff --git a/best-practices.md b/best-practices.md index 77e01e6b..164a8cef 100644 --- a/best-practices.md +++ b/best-practices.md @@ -71,8 +71,8 @@ So to enable all the great web tools (like [stacindex.org](http://stacindex.org) [Google Cloud Storage](https://cloud.google.com/storage/docs/cross-origin), or [Apache Server](https://enable-cors.org/server_apache.html). Many more are listed on [enable-cors.org](https://enable-cors.org/server.html). We recommend enabling CORS for all requests ('\*'), so that diverse online tools can access your data. If you aren't sure if your server has CORS enabled you can use -[test-cors.org](https://www.test-cors.org/). Enter the URL of your STAC root [Catalog](catalog-spec/catalog-spec.md) JSON -and make sure it gets a response. +[test-cors.org](https://www.test-cors.org/). Enter the URL of your STAC root [Catalog](catalog-spec/catalog-spec.md) or +[Collection](collection-spec/collection-spec.md) JSON and make sure it gets a response. ### STAC on the Web @@ -81,7 +81,7 @@ surprised that there is nothing about HTML in the entire specification. This is should be on web pages without ending up with very bad looking pages. But the importance of having web-accessible versions of every STAC Item is paramount. -The main recommendation is to have an HTML page for every single STAC Item and Catalog. They should be visually pleasing, +The main recommendation is to have an HTML page for every single STAC Item, Catalog and Collection. They should be visually pleasing, crawlable by search engines and ideally interactive. The current best practice is to use a tool in the STAC ecosystem called [STAC Browser](https://github.com/radiantearth/stac-browser/). It can crawl most any valid STAC implementation and generate unique web pages for each Item and Catalog (or Collection). While it has a default look and feel, the design can easily be @@ -393,6 +393,10 @@ file that just has the bands needed for display ## Catalog & Collection Practices +*Note: This section uses the term 'Catalog' (with an uppercase C) to refer to the JSON entity specified in the +[Catalog spec](catalog-spec/catalog-spec.md), and 'catalog' (with a lowercase c) to refer to any full STAC implementation, +which can be any mix of Catalogs Collections and Items.* + ### Static and Dynamic Catalogs As mentioned in the main [overview](overview.md), there are two main types of catalogs - static @@ -446,7 +450,7 @@ providers, and users could browse down to both. The leaf Items should just be li ### Catalog Layout -Creating a catalog involves a number of decisions as to what folder structure to use to represent sub-catalogs, items +Creating a catalog involves a number of decisions as to what folder structure to use to represent sub-catalogs, Items and assets, and how to name them. The specification leaves this totally open, and you can link things as you want. But it is recommended to be thoughtful about the organization of sub-catalogs, putting them into a structure that a person might reasonably browse (since they likely will with [STAC on the Web](#stac-on-the-web) recommendations). For example @@ -610,7 +614,7 @@ implement it. 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 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. @@ -632,8 +636,8 @@ a number of the common official relations that are used in production STAC imple | 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. | ### Versioning for Catalogs diff --git a/item-spec/item-spec.md b/item-spec/item-spec.md index 5f609c52..2ac20a66 100644 --- a/item-spec/item-spec.md +++ b/item-spec/item-spec.md @@ -84,7 +84,7 @@ It is important that an Item identifier is unique within a Collection, and that [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. +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. From 6b24f7c9dc264178ee58da0b03777fa8d02bf296 Mon Sep 17 00:00:00 2001 From: Chris Holmes Date: Tue, 20 Apr 2021 08:49:27 -0700 Subject: [PATCH 25/61] put note up top --- overview.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/overview.md b/overview.md index 4e9d84b5..306daf5f 100644 --- a/overview.md +++ b/overview.md @@ -87,6 +87,9 @@ 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 @@ -138,9 +141,6 @@ root catalog might be a sub-catalog of someone else's structure. The goal is for information and links they want to, while also encouraging a natural web of information to arise as Catalogs and Items are linked to across the web. -*NOTE: The above examples all say Catalog, but those can all be Collections as well, as it has all the fields necessary to -serve as a Catalog* - ### Static and Dynamic Catalogs The Catalog specification is designed so it can be implemented as easily as possibly. This can be as simple as From 6755d41c68f45cdcbf908b20c91c101fce685f2a Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Tue, 20 Apr 2021 16:43:45 +0200 Subject: [PATCH 26/61] First try at supporting JSON Schema in summaries #1045 --- CHANGELOG.md | 7 ++++++- catalog-spec/catalog-spec.md | 2 +- catalog-spec/json-schema/catalog-core.json | 15 ++++++++++++--- collection-spec/collection-spec.md | 21 +++++++++++++++------ examples/collection-only/collection.json | 8 +++++--- package.json | 2 +- schema.json | 0 7 files changed, 40 insertions(+), 15 deletions(-) delete mode 100644 schema.json diff --git a/CHANGELOG.md b/CHANGELOG.md index 2e5a4424..f9f0f2c6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,11 +7,16 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. ## [Unreleased] +### 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)) + ### 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). ## [v1.0.0-rc.2] - 2021-03-30 @@ -46,7 +51,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)) diff --git a/catalog-spec/catalog-spec.md b/catalog-spec/catalog-spec.md index 573e848a..6cdd6d55 100644 --- a/catalog-spec/catalog-spec.md +++ b/catalog-spec/catalog-spec.md @@ -49,7 +49,7 @@ 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). | +| summaries | Map | A map of property summaries, either a set of values, a range of values or a [JSON Schema](https://json-schema.org). 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 diff --git a/catalog-spec/json-schema/catalog-core.json b/catalog-spec/json-schema/catalog-core.json index 503d7a66..dec52cf9 100644 --- a/catalog-spec/json-schema/catalog-core.json +++ b/catalog-spec/json-schema/catalog-core.json @@ -99,9 +99,18 @@ "summaries": { "type": "object", "additionalProperties": { - "oneOf": [ + "anyOf": [ { - "title": "Stats", + "title": "JSON Schema", + "type": "object", + "allOf": [ + { + "$ref": "http://json-schema.org/draft-07/schema" + } + ] + }, + { + "title": "Range", "type": "object", "required": [ "minimum", @@ -129,7 +138,7 @@ "type": "array", "minItems": 1, "items": { - "description": "Any data type could occur." + "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." } } ] diff --git a/collection-spec/collection-spec.md b/collection-spec/collection-spec.md index f4e331c7..203eb8b1 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) @@ -54,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. | @@ -95,12 +96,12 @@ Summaries help to fully define Collections, especially if they don't link to any 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: +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. Statistics in a [Stats Object](#stats-object): Statistics by default only specify the range (minimum and maximum values), +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. @@ -281,9 +282,9 @@ 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. +For summaries with a lot of continuous values, 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. @@ -295,6 +296,14 @@ 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. + +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. + ## 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 diff --git a/examples/collection-only/collection.json b/examples/collection-only/collection.json index 9a8da7c3..3d394e89 100644 --- a/examples/collection-only/collection.json +++ b/examples/collection-only/collection.json @@ -78,9 +78,11 @@ "minimum": 6.78, "maximum": 89.9 }, - "sci:citation": [ - "Copernicus Sentinel data [Year]" - ], + "sci:citation": { + "$schema": "http://json-schema.org/draft-07/schema#", + "type": "string", + "pattern": "Copernicus Sentinel data \\d{4}" + }, "gsd": [ 10, 30, diff --git a/package.json b/package.json index a787cad3..ed5c9edb 100644 --- a/package.json +++ b/package.json @@ -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": "^1.0.1" + "stac-node-validator": "^1.1.0" } } diff --git a/schema.json b/schema.json deleted file mode 100644 index e69de29b..00000000 From 40ab95491db46207eaac7cac23f4327f3be44d90 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Thu, 22 Apr 2021 11:18:53 +0200 Subject: [PATCH 27/61] Update collection-spec/collection-spec.md --- collection-spec/collection-spec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/collection-spec/collection-spec.md b/collection-spec/collection-spec.md index 203eb8b1..349bda0d 100644 --- a/collection-spec/collection-spec.md +++ b/collection-spec/collection-spec.md @@ -284,7 +284,7 @@ or streamed. The definition provided here, at the Collection level, is the same ### Range Object -For summaries with a lot of continuous values, statistics can be added. +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. From ee8022b24d40f55a9b6d9b56d2729def8f676c3c Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Thu, 22 Apr 2021 17:37:08 +0200 Subject: [PATCH 28/61] Example (WIP), more details --- catalog-spec/json-schema/catalog-core.json | 1 + collection-spec/collection-spec.md | 3 +- .../collection-with-schemas.json | 281 ++++++++++++++++++ 3 files changed, 284 insertions(+), 1 deletion(-) create mode 100644 examples/collection-only/collection-with-schemas.json diff --git a/catalog-spec/json-schema/catalog-core.json b/catalog-spec/json-schema/catalog-core.json index dec52cf9..214df4bb 100644 --- a/catalog-spec/json-schema/catalog-core.json +++ b/catalog-spec/json-schema/catalog-core.json @@ -103,6 +103,7 @@ { "title": "JSON Schema", "type": "object", + "minProperties": 1, "allOf": [ { "$ref": "http://json-schema.org/draft-07/schema" diff --git a/collection-spec/collection-spec.md b/collection-spec/collection-spec.md index 349bda0d..fa14e58f 100644 --- a/collection-spec/collection-spec.md +++ b/collection-spec/collection-spec.md @@ -300,9 +300,10 @@ Implementors are free to add other derived statistical values to the object, for 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. +to align with the JSON Schemas provided by STAC. Empty schemas are not allowed. ## Media Type for STAC Collections diff --git a/examples/collection-only/collection-with-schemas.json b/examples/collection-only/collection-with-schemas.json new file mode 100644 index 00000000..4aa2c21e --- /dev/null +++ b/examples/collection-only/collection-with-schemas.json @@ -0,0 +1,281 @@ +{ + "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/sat/v1.0.0/schema.json", + "https://stac-extensions.github.io/view/v1.0.0/schema.json" + ], + "id": "S2", + "type": "Collection", + "title": "Level 1C Sentinel-2 images", + "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": "self", + "type": "application/json", + "href": "https://tamn.snapplanet.io/collections/S2" + }, + { + "rel": "root", + "type": "application/json", + "href": "https://tamn.snapplanet.io" + }, + { + "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:21.459000Z", + "maximum": "2021-04-22T11:30:12.767000Z" + }, + "collection": { + "type": "string", + "const": "sentinel-2", + "title": "Sentinel 2", + "count": 6613407 + }, + "instruments": { + "type": "string", + "const": "msi", + "title": "MSI", + "count": 6613431 + }, + "landcover": { + "type": "string", + "oneOf": [ + { + "const": "landcover:cultivated", + "title": "Cultivated", + "count": 490750 + }, + { + "const": "landcover:desert", + "title": "Desert", + "count": 543120 + }, + { + "const": "landcover:flooded", + "title": "Flooded", + "count": 5187 + }, + { + "const": "landcover:forest", + "title": "Forest", + "count": 767807 + }, + { + "const": "landcover:herbaceous", + "title": "Herbaceous", + "count": 674281 + }, + { + "const": "landcover:ice", + "title": "Ice", + "count": 231285 + }, + { + "const": "landcover:urban", + "title": "Urban", + "count": 1219 + }, + { + "const": "landcover:water", + "title": "Water", + "count": 2303314 + } + ] + }, + "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 + } + ] + }, + "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 From eb7b9d29e97777302cb9f1c70ccb2f491c4acb09 Mon Sep 17 00:00:00 2001 From: Chris Holmes Date: Thu, 22 Apr 2021 11:20:48 -0700 Subject: [PATCH 29/61] Attempt to provide the main text --- best-practices.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/best-practices.md b/best-practices.md index b12638d0..cba44bec 100644 --- a/best-practices.md +++ b/best-practices.md @@ -634,7 +634,7 @@ a number of the common official relations that are used in production STAC imple | 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. | -| preview | 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. | +| preview | This link relation can be used to "refer to a resource that serves as a preview of the link's context, likely with reduced quality or limited content" (from [rfc6903](https://tools.ietf.org/html/rfc6903#section-3)). For geospatial information this is generally a thumbnail, and in STAC this would usually be the same href as the [thumbnail](#thumbnail) asset, to enable more general clients to make use of it. | ### Versioning for Catalogs From 233b757cb59948f1d5993b6299b20cd73577054b Mon Sep 17 00:00:00 2001 From: Brad Hards Date: Fri, 23 Apr 2021 17:40:14 +1000 Subject: [PATCH 30/61] Minor change to Collection usage wording --- overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/overview.md b/overview.md index 3d752aae..8c35e597 100644 --- a/overview.md +++ b/overview.md @@ -80,7 +80,7 @@ The second case is used when one wants to represent diverse data in a single pla 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. -So in conclusion it's best to use Collections for what you want user to find as starting point, and then +So in conclusion it's best to use Collections for what you want a user to find as a starting point, and then 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. From 59df72d09d33282e5d0a10f14d45d3c05a9c5087 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Fri, 23 Apr 2021 13:47:31 +0200 Subject: [PATCH 31/61] Some more details --- best-practices.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/best-practices.md b/best-practices.md index cba44bec..a1873b98 100644 --- a/best-practices.md +++ b/best-practices.md @@ -45,6 +45,7 @@ - [Keep catalogs in sync with cloud notification and queue services](#keep-catalogs-in-sync-with-cloud-notification-and-queue-services) - [How to Differentiate STAC Files](#how-to-differentiate-stac-files) + This document makes a number of recommendations for creating real world SpatioTemporal Asset Catalogs. None of them are required to meet the core specification, but following these practices will make life easier for client tooling and for users. They come about from practical experience of implementors and introduce a bit more 'constraint' for @@ -293,7 +294,7 @@ following table lists some of the most common ones you may encounter or use. | `image/png` | Visual PNGs (e.g. thumbnails) | | `image/jpeg` | Visual JPEGs (e.g. thumbnails, oblique) | | `text/xml` or `application/xml` | XML metadata [RFC 7303](https://www.ietf.org/rfc/rfc7303.txt) | -| `application/json` | A JSON file (often metadata, or [labels](https://github.com/radiantearth/stac-spec/tree/master/extensions/label#labels-required)) | +| `application/json` | A JSON file (often metadata, or [labels](https://github.com/radiantearth/stac-spec/tree/master/extensions/label#labels-required)) | | `text/plain` | Plain text (often metadata) | | `application/geo+json` | [GeoJSON](https://geojson.org/) | | `application/geopackage+sqlite3` | [GeoPackage](https://www.geopackage.org/) | @@ -634,7 +635,7 @@ a number of the common official relations that are used in production STAC imple | 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. | -| preview | This link relation can be used to "refer to a resource that serves as a preview of the link's context, likely with reduced quality or limited content" (from [rfc6903](https://tools.ietf.org/html/rfc6903#section-3)). For geospatial information this is generally a thumbnail, and in STAC this would usually be the same href as the [thumbnail](#thumbnail) asset, to enable more general clients to make use of it. | +| 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. | ### Versioning for Catalogs From 54d7be4957dd6ec92c7c63a14c359fc9426d1576 Mon Sep 17 00:00:00 2001 From: Chris Holmes Date: Fri, 23 Apr 2021 07:27:25 -0700 Subject: [PATCH 32/61] updates from review comments --- best-practices.md | 10 +++++----- catalog-spec/catalog-spec.md | 6 +++--- collection-spec/collection-spec.md | 2 +- 3 files changed, 9 insertions(+), 9 deletions(-) diff --git a/best-practices.md b/best-practices.md index 164a8cef..c04cf116 100644 --- a/best-practices.md +++ b/best-practices.md @@ -467,11 +467,11 @@ if you follow these recommendations. 1. Root documents (Catalogs / Collections) should be at the root of a directory tree containing the static catalog. 2. Catalogs should be named `catalog.json` and Collections should be named `collection.json`. 3. Items should be named `.json`. -4. Sub-Catalogs should be stored in subdirectories of their parent +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. +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 sub-Catalog, grouping / partitioning as relevant to the dataset. +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. @@ -487,7 +487,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 @@ -612,7 +612,7 @@ 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 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'. diff --git a/catalog-spec/catalog-spec.md b/catalog-spec/catalog-spec.md index 573e848a..64d2409e 100644 --- a/catalog-spec/catalog-spec.md +++ b/catalog-spec/catalog-spec.md @@ -36,8 +36,8 @@ 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. Every STAC Collection contains all +the same fields as Catalog, though returns 'Collection' instead of 'Catalog' for the type field. ## Catalog fields @@ -93,7 +93,7 @@ The following types are commonly used as `rel` types in the Link Object of a STA | child | URL to a child STAC 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 **REQUIRED**. 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/collection-spec/collection-spec.md b/collection-spec/collection-spec.md index 280a948e..c1614b99 100644 --- a/collection-spec/collection-spec.md +++ b/collection-spec/collection-spec.md @@ -254,7 +254,7 @@ This is done where there is not a clear official option, or where STAC uses an o | 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 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 Catalog or Collection. | +| 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. | From e257928222c33013e216f4850b0d2eb9f75e1578 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Fri, 23 Apr 2021 16:36:21 +0200 Subject: [PATCH 33/61] Couple of changes for better alignment between the specs + list formatting --- best-practices.md | 4 ++-- catalog-spec/catalog-spec.md | 9 +++++---- item-spec/item-spec.md | 4 ++-- 3 files changed, 9 insertions(+), 8 deletions(-) diff --git a/best-practices.md b/best-practices.md index c04cf116..9a33eade 100644 --- a/best-practices.md +++ b/best-practices.md @@ -470,11 +470,11 @@ if you follow these recommendations. 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. + 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. + don't add a Catalog at levels 2 and 4. #### Dynamic Catalog Layout diff --git a/catalog-spec/catalog-spec.md b/catalog-spec/catalog-spec.md index 64d2409e..325ea58f 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 contains all -the same fields as Catalog, though returns 'Collection' instead of 'Catalog' for the type field. +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 @@ -89,8 +90,8 @@ 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 or Collection) is **REQUIRED**. diff --git a/item-spec/item-spec.md b/item-spec/item-spec.md index 2ac20a66..641fd3da 100644 --- a/item-spec/item-spec.md +++ b/item-spec/item-spec.md @@ -192,8 +192,8 @@ This happens where there is not a clear official option, or where STAC uses an o | 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. | +| 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. | From b74d5b8c647b2f1ffa556f17e4e1f68552decc15 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Fri, 23 Apr 2021 17:18:59 +0200 Subject: [PATCH 34/61] Better integrate example --- examples/catalog.json | 6 +++ .../collection-with-schemas.json | 46 ++++++++----------- examples/collection-only/collection.json | 7 ++- examples/collection.json | 1 + 4 files changed, 32 insertions(+), 28 deletions(-) diff --git a/examples/catalog.json b/examples/catalog.json index c309c1f6..5272652d 100644 --- a/examples/catalog.json +++ b/examples/catalog.json @@ -21,6 +21,12 @@ "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", diff --git a/examples/collection-only/collection-with-schemas.json b/examples/collection-only/collection-with-schemas.json index 4aa2c21e..58562783 100644 --- a/examples/collection-only/collection-with-schemas.json +++ b/examples/collection-only/collection-with-schemas.json @@ -5,9 +5,9 @@ "https://stac-extensions.github.io/sat/v1.0.0/schema.json", "https://stac-extensions.github.io/view/v1.0.0/schema.json" ], - "id": "S2", + "id": "sentinel-2", "type": "Collection", - "title": "Level 1C Sentinel-2 images", + "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": { @@ -32,14 +32,12 @@ }, "links": [ { - "rel": "self", - "type": "application/json", - "href": "https://tamn.snapplanet.io/collections/S2" + "rel": "parent", + "href": "../catalog.json" }, { "rel": "root", - "type": "application/json", - "href": "https://tamn.snapplanet.io" + "href": "../catalog.json" }, { "rel": "license", @@ -73,67 +71,61 @@ ], "summaries": { "datetime": { - "minimum": "2017-04-12T02:57:21.459000Z", - "maximum": "2021-04-22T11:30:12.767000Z" - }, - "collection": { - "type": "string", - "const": "sentinel-2", - "title": "Sentinel 2", - "count": 6613407 + "minimum": "2017-04-12T02:57:21Z", + "maximum": "2021-04-22T11:30:12Z" }, "instruments": { "type": "string", "const": "msi", - "title": "MSI", + "title": "Multispectral Intrument", "count": 6613431 }, - "landcover": { + "resto:landcover": { "type": "string", "oneOf": [ { - "const": "landcover:cultivated", + "const": "cultivated", "title": "Cultivated", "count": 490750 }, { - "const": "landcover:desert", + "const": "desert", "title": "Desert", "count": 543120 }, { - "const": "landcover:flooded", + "const": "flooded", "title": "Flooded", "count": 5187 }, { - "const": "landcover:forest", + "const": "forest", "title": "Forest", "count": 767807 }, { - "const": "landcover:herbaceous", + "const": "herbaceous", "title": "Herbaceous", "count": 674281 }, { - "const": "landcover:ice", + "const": "ice", "title": "Ice", "count": 231285 }, { - "const": "landcover:urban", + "const": "urban", "title": "Urban", "count": 1219 }, { - "const": "landcover:water", + "const": "water", "title": "Water", "count": 2303314 } ] }, - "location": { + "resto:location": { "type": "string", "oneOf": [ { @@ -178,7 +170,7 @@ } ] }, - "season": { + "resto:season": { "type": "integer", "oneOf": [ { diff --git a/examples/collection-only/collection.json b/examples/collection-only/collection.json index 3d394e89..3019510e 100644 --- a/examples/collection-only/collection.json +++ b/examples/collection-only/collection.json @@ -1,7 +1,12 @@ { "type": "Collection", "stac_version": "1.0.0-rc.2", - "stac_extensions": [], + "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/scientific/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", diff --git a/examples/collection.json b/examples/collection.json index 87047035..28604ecf 100644 --- a/examples/collection.json +++ b/examples/collection.json @@ -2,6 +2,7 @@ "id": "simple-collection", "type": "Collection", "stac_extensions": [ + "https://stac-extensions.github.io/eo/v1.0.0/schema.json", "https://stac-extensions.github.io/view/v1.0.0/schema.json" ], "stac_version": "1.0.0-rc.2", From 1f3b72b83e8b1135b01ccdc9526354a44a2cb72b Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Fri, 23 Apr 2021 18:17:31 +0200 Subject: [PATCH 35/61] All timestamps in UTC #1095 --- CHANGELOG.md | 1 + collection-spec/collection-spec.md | 2 +- collection-spec/json-schema/collection.json | 3 ++- item-spec/common-metadata.md | 4 ++-- item-spec/json-schema/datetime.json | 15 ++++++++++----- 5 files changed, 16 insertions(+), 9 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 2e5a4424..68ce46e1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. - 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)) +- `changed`, `created` (common metadata) and temporal extents (collections): Timestamps must be always in UTC ([#1095](https://github.com/radiantearth/stac-spec/issues/1095)) ## [v1.0.0-rc.2] - 2021-03-30 diff --git a/collection-spec/collection-spec.md b/collection-spec/collection-spec.md index f4e331c7..c76be328 100644 --- a/collection-spec/collection-spec.md +++ b/collection-spec/collection-spec.md @@ -197,7 +197,7 @@ Clients only interested in the overall extent will only need to access the first 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 inner array consists of exactly two dates and times, each in UTC. 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. diff --git a/collection-spec/json-schema/collection.json b/collection-spec/json-schema/collection.json index 422385f2..19bb9611 100644 --- a/collection-spec/json-schema/collection.json +++ b/collection-spec/json-schema/collection.json @@ -153,7 +153,8 @@ "string", "null" ], - "format": "date-time" + "format": "date-time", + "pattern": "(\\+00:00|Z)$" } } } diff --git a/item-spec/common-metadata.md b/item-spec/common-metadata.md index 07df2234..d5326d76 100644 --- a/item-spec/common-metadata.md +++ b/item-spec/common-metadata.md @@ -43,8 +43,8 @@ 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). diff --git a/item-spec/json-schema/datetime.json b/item-spec/json-schema/datetime.json index 3a1480db..fa540a32 100644 --- a/item-spec/json-schema/datetime.json +++ b/item-spec/json-schema/datetime.json @@ -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 From 14fec945cbd424f7323379ba36a699fe70493d8d Mon Sep 17 00:00:00 2001 From: Chris Holmes Date: Fri, 23 Apr 2021 09:36:24 -0700 Subject: [PATCH 36/61] More emphasis on UTC requirement --- item-spec/item-spec.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/item-spec/item-spec.md b/item-spec/item-spec.md index 5f609c52..0518dd60 100644 --- a/item-spec/item-spec.md +++ b/item-spec/item-spec.md @@ -127,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 @@ -136,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 From 314cfa1325397b6c1964ac41db06c9ac7176c988 Mon Sep 17 00:00:00 2001 From: Chris Holmes Date: Fri, 23 Apr 2021 12:01:48 -0700 Subject: [PATCH 37/61] include parent and root rel types, even for same file --- CHANGELOG.md | 1 + best-practices.md | 4 ++++ examples/core-item.json | 5 +++++ examples/extended-item.json | 5 +++++ examples/simple-item.json | 5 +++++ 5 files changed, 20 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 05d6b38d..fd9f56ac 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. ### Added - 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. ### Changed diff --git a/best-practices.md b/best-practices.md index 8ab6a3fb..322e2824 100644 --- a/best-practices.md +++ b/best-practices.md @@ -641,6 +641,10 @@ a number of the common official relations that are used in production STAC imple | 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 `rel`. 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 diff --git a/examples/core-item.json b/examples/core-item.json index a71eb08f..06fa8b0a 100644 --- a/examples/core-item.json +++ b/examples/core-item.json @@ -65,6 +65,11 @@ "href": "./collection.json", "type": "application/json" }, + { + "rel": "parent", + "href": "./collection.json", + "type": "application/json" + }, { "rel": "alternate", "type": "text/html", diff --git a/examples/extended-item.json b/examples/extended-item.json index 10db0ce1..b27f4752 100644 --- a/examples/extended-item.json +++ b/examples/extended-item.json @@ -93,6 +93,11 @@ "href": "./collection.json", "type": "application/json" }, + { + "rel": "parent", + "href": "./collection.json", + "type": "application/json" + }, { "rel": "alternate", "type": "text/html", diff --git a/examples/simple-item.json b/examples/simple-item.json index ad4d526d..f505fda8 100644 --- a/examples/simple-item.json +++ b/examples/simple-item.json @@ -51,6 +51,11 @@ "rel": "root", "href": "./collection.json", "type": "application/json" + }, + { + "rel": "parent", + "href": "./collection.json", + "type": "application/json" } ], "assets": { From ea23b295933a2e4c18f0fb5d5638c24ff2682e50 Mon Sep 17 00:00:00 2001 From: Brad Hards Date: Sun, 25 Apr 2021 09:57:44 +1000 Subject: [PATCH 38/61] minor editorial cleanup for common-metadata --- item-spec/common-metadata.md | 46 ++++++++++++++++++------------------ 1 file changed, 23 insertions(+), 23 deletions(-) diff --git a/item-spec/common-metadata.md b/item-spec/common-metadata.md index d5326d76..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 @@ -49,7 +49,7 @@ Fields to provide additional temporal information such as ranges with a start an 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,12 +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. +**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 | | -------------- | ------ | ------------------------------------------------------------ | @@ -126,11 +126,11 @@ The provider's role(s) can be one or more of the following elements: - *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. + 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) @@ -147,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 @@ -162,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 @@ -184,10 +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 +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. From 0d8916ff15efb636ff0f643c96c241c3f0f1b233 Mon Sep 17 00:00:00 2001 From: Chris Holmes Date: Mon, 26 Apr 2021 11:32:21 -0700 Subject: [PATCH 39/61] remove scientific extension --- examples/collection-only/collection.json | 6 ------ 1 file changed, 6 deletions(-) diff --git a/examples/collection-only/collection.json b/examples/collection-only/collection.json index 3019510e..01f580bf 100644 --- a/examples/collection-only/collection.json +++ b/examples/collection-only/collection.json @@ -4,7 +4,6 @@ "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/scientific/v1.0.0/schema.json", "https://stac-extensions.github.io/view/v1.0.0/schema.json" ], "id": "sentinel-2", @@ -83,11 +82,6 @@ "minimum": 6.78, "maximum": 89.9 }, - "sci:citation": { - "$schema": "http://json-schema.org/draft-07/schema#", - "type": "string", - "pattern": "Copernicus Sentinel data \\d{4}" - }, "gsd": [ 10, 30, From 5890f7ec40799efb555707080ca30f1413e90182 Mon Sep 17 00:00:00 2001 From: Chris Holmes Date: Mon, 26 Apr 2021 12:07:43 -0700 Subject: [PATCH 40/61] clarifications on using gsd as an asset field --- best-practices.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/best-practices.md b/best-practices.md index 8ab6a3fb..68bf0f52 100644 --- a/best-practices.md +++ b/best-practices.md @@ -255,8 +255,10 @@ providing them at at the Asset level can prove to be very useful for using the d - `datetime`: Provide individual timestamp on an Item, in case the Item has a `start_datetime` and `end_datetime`, but an Asset is for one specific time. -- `gsd` ([Common Metadata](item-spec/common-metadata.md#instrument)): Specify some assets with different spatial resolution -than the overall best resolution. +- `gsd` ([Common Metadata](item-spec/common-metadata.md#instrument)): Specify some assets that represent instruments + with different spatial resolution than the overall best resolution. Note this should not be used for different + spatial resolutions due to specific processing of assets - look into the [raster + extension](https://github.com/stac-extensions/raster) for that use case. - `eo:bands` ([EO extension](https://github.com/stac-extensions/eo/)): Provide spectral band information, and order of bands, within an individual asset. - `proj:epsg`/`proj:wkt2`/`proj:projjson` ([projection extension](https://github.com/stac-extensions/projection/)): From 6fb42d9bb50f674c9f07d7160ba56eed314378b5 Mon Sep 17 00:00:00 2001 From: Chris Holmes Date: Mon, 26 Apr 2021 12:15:10 -0700 Subject: [PATCH 41/61] update changelog --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 05d6b38d..67730259 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,6 +17,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. - 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)) - `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 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) ## [v1.0.0-rc.2] - 2021-03-30 From ab58068f488462f0d1d36d41999725c805aa979b Mon Sep 17 00:00:00 2001 From: Chris Holmes Date: Mon, 26 Apr 2021 13:07:47 -0700 Subject: [PATCH 42/61] Update CHANGELOG.md Co-authored-by: Kyle Barron --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 67730259..1396e8bf 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,7 +17,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. - 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)) - `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 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 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)) ## [v1.0.0-rc.2] - 2021-03-30 From 476e1796dd73020423b1b2d78d548bfad9c958bd Mon Sep 17 00:00:00 2001 From: Chris Holmes Date: Mon, 26 Apr 2021 13:08:06 -0700 Subject: [PATCH 43/61] Update CHANGELOG.md Co-authored-by: Kyle Barron --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1396e8bf..aa4f0963 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,7 +14,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. ### 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) +- 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)) - `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 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)) From 457a5d57a34078fe0a3e340893ad92ed2c7a2525 Mon Sep 17 00:00:00 2001 From: Frederico Liporace Date: Tue, 27 Apr 2021 13:38:25 -0300 Subject: [PATCH 44/61] Rephrase summaries; exception for summary schema; typo --- collection-spec/collection-spec.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/collection-spec/collection-spec.md b/collection-spec/collection-spec.md index c566eb91..59589ed7 100644 --- a/collection-spec/collection-spec.md +++ b/collection-spec/collection-spec.md @@ -90,10 +90,10 @@ and consumers have not been granted any explicit right to use the data. 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). +different fields in the Collection are, without having 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. + Fields selected to be included in summaries should consider all the field's values in every Item underneath the collection, including in any nested sub-Catalogs. A summary for a field can be specified in two ways: @@ -105,8 +105,8 @@ A summary for a field can be specified in two ways: 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 +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). From 16b4b4280fa37cd24055c91efe2dbf419c81a98c Mon Sep 17 00:00:00 2001 From: Frederico Liporace Date: Tue, 27 Apr 2021 13:42:05 -0300 Subject: [PATCH 45/61] Changelog for issue #1106 --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 05d6b38d..194e90f5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,6 +17,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. - 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)) - `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)) ## [v1.0.0-rc.2] - 2021-03-30 From 7762cca3108cc8bf59148797d38992d873f7deca Mon Sep 17 00:00:00 2001 From: Frederico Liporace Date: Tue, 27 Apr 2021 14:49:32 -0300 Subject: [PATCH 46/61] Fixing .md link --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 194e90f5..77fc70b6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,7 +17,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. - 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)) - `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 collection summaries do not require that all property fields are summarized. ([#1106](https://github.com/radiantearth/stac-spec/issues/1106)) ## [v1.0.0-rc.2] - 2021-03-30 From 4e4a7f7a7bec346b9a29307f8341535b9838734a Mon Sep 17 00:00:00 2001 From: Chris Holmes Date: Wed, 28 Apr 2021 09:52:16 -0700 Subject: [PATCH 47/61] Filled out 3rd option for summaries --- collection-spec/collection-spec.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/collection-spec/collection-spec.md b/collection-spec/collection-spec.md index f237bc4a..fac9bda0 100644 --- a/collection-spec/collection-spec.md +++ b/collection-spec/collection-spec.md @@ -105,6 +105,8 @@ A summary for a field can be specified in three ways: 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 they summarize. So the values in the array or the values given for `minimum` and `maxmimum` must comply to the original data type From e5060dc99e0926eec6c15637571f73fb11a63e90 Mon Sep 17 00:00:00 2001 From: Chris Holmes Date: Wed, 28 Apr 2021 09:53:12 -0700 Subject: [PATCH 48/61] Update collection-spec/collection-spec.md Co-authored-by: Matthias Mohr --- collection-spec/collection-spec.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/collection-spec/collection-spec.md b/collection-spec/collection-spec.md index fac9bda0..125953da 100644 --- a/collection-spec/collection-spec.md +++ b/collection-spec/collection-spec.md @@ -307,6 +307,8 @@ Each schema must be valid against all corresponding values available for the pro 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 From 3e3677c65f6e4b768d985ca2cf6b481ef2cc7272 Mon Sep 17 00:00:00 2001 From: Chris Holmes Date: Wed, 28 Apr 2021 10:10:26 -0700 Subject: [PATCH 49/61] fix from PR review --- best-practices.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/best-practices.md b/best-practices.md index 322e2824..21e4867e 100644 --- a/best-practices.md +++ b/best-practices.md @@ -641,9 +641,9 @@ a number of the common official relations that are used in production STAC imple | 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 `rel`. For example the +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. +recommended to include both. ### Versioning for Catalogs From 31e9f91c1aeb242d7c2ff585eb5bea9385fd0fdb Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Thu, 29 Apr 2021 14:48:25 +0200 Subject: [PATCH 50/61] Apply suggestions from code review Co-authored-by: Chris Holmes --- collection-spec/collection-spec.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/collection-spec/collection-spec.md b/collection-spec/collection-spec.md index 59589ed7..72ac70ae 100644 --- a/collection-spec/collection-spec.md +++ b/collection-spec/collection-spec.md @@ -91,9 +91,10 @@ and consumers have not been granted any explicit right to use the data. 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 having 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 +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 consider all the field's values in every Item underneath the collection, including in any nested sub-Catalogs. + 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 two ways: From 13bec8242027d77b96a1f2a452c94cd6fc52ba7f Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Thu, 29 Apr 2021 14:52:21 +0200 Subject: [PATCH 51/61] Update collection-spec/collection-spec.md --- collection-spec/collection-spec.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/collection-spec/collection-spec.md b/collection-spec/collection-spec.md index 71496154..46846e8c 100644 --- a/collection-spec/collection-spec.md +++ b/collection-spec/collection-spec.md @@ -92,7 +92,8 @@ and consumers have not been granted any explicit right to use the data. 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 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 +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. From 9abb6e61a24931c5c90869fdb3a6114e5f6b407b Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Thu, 29 Apr 2021 15:36:09 +0200 Subject: [PATCH 52/61] Catalog: Require child / item in JSON Schema #1100 --- catalog-spec/json-schema/catalog.json | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/catalog-spec/json-schema/catalog.json b/catalog-spec/json-schema/catalog.json index 0f2c110f..c971c80b 100644 --- a/catalog-spec/json-schema/catalog.json +++ b/catalog-spec/json-schema/catalog.json @@ -22,6 +22,22 @@ "type": { "title": "Type of STAC entity", "const": "Catalog" + }, + "links": { + "title": "Links", + "type": "array", + "contains": { + "description": "A link to at least one `item` or `child` is REQUIRED in Catalogs.", + "type": "object", + "properties": { + "rel": { + "enum": [ + "child", + "item" + ] + } + } + } } } } From c39776707eb71ed43358f529ba248f180266df71 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Thu, 29 Apr 2021 16:06:12 +0200 Subject: [PATCH 53/61] best practices: some clarifications #1108 --- best-practices.md | 20 ++++++++++++-------- item-spec/item-spec.md | 2 +- 2 files changed, 13 insertions(+), 9 deletions(-) diff --git a/best-practices.md b/best-practices.md index df78ce76..2f48b281 100644 --- a/best-practices.md +++ b/best-practices.md @@ -9,7 +9,8 @@ - [Deploying STAC Browser](#deploying-stac-browser) - [Requester Pays](#requester-pays) - **[Item Best Practices](#item-practices)** - - [Field and ID formatting](#field-and-id-formatting) + - [Field and ID formatting](#item-ids) + - [Searchable Identifiers](#searchable-identifiers) - [Field selection and Metadata Linking](#field-selection-and-metadata-linking) - [Datetime selection](#datetime-selection) - [Unlocated Items](#unlocated-items) @@ -147,19 +148,22 @@ For data providers using STAC with requester pays buckets, there are two main re ## Item Practices -### Field and ID formatting +### Item IDs When defining one's STAC properties and fields there are many choices to make on how to name various aspects of one's data. One of the key properties is the ID. The specification is quite flexible on ID's, primarily so that existing providers can easily use their same ID when they translate their data into STAC - they just need to be sure it is globally -unique, so may need a prefix. But the use of URI reserved characters such as `:` or `/` is discouraged since this will +unique, so may need a prefix. But the use of URI or file path reserved characters such as `:` or `/` is discouraged since this will result in [percented encoded](https://tools.ietf.org/html/rfc3986#section-2) [STAC API](https://github.com/radiantearth/stac-api-spec) -endpoints. This isn't a blocker, it just makes the ID's served through API's a bit less parsable. +endpoints and also the [IDs can't be used as file names](#catalog-layout). -When defining unique fields for search, like constellation or platform, it is recommended that -the value consist of only lowercase characters, numbers, `_`, and `-`. Examples include `sentinel-1a` (Sentinel-1), -`landsat-8` (Landsat-8) and `envisat` (Envisat). This is to provide consistency for search across Collections, so that -people can just search for 'landsat-8', instead of thinking through all the ways providers might have chosen to name it. +### Searchable Identifiers + +When coming up with values for fields that contain searchable identifiers of some sort, like `constellation` or `platform`, +it is recommended that the identifiers consist of only lowercase characters, numbers, `_`, and `-`. +Examples include `sentinel-1a` (Sentinel-1), `landsat-8` (Landsat-8) and `envisat` (Envisat). +This is to provide consistency for search across Collections, so that people can just search for `landsat-8`, +instead of thinking through all the ways providers might have chosen to name it. ### Field selection and Metadata Linking diff --git a/item-spec/item-spec.md b/item-spec/item-spec.md index 0ea52c7a..48358145 100644 --- a/item-spec/item-spec.md +++ b/item-spec/item-spec.md @@ -90,7 +90,7 @@ 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. +See the [id section of best practices](../best-practices.md#item-ids) for additional recommendations. #### assets From 431e0af540793e22587b4d4f819e0b7138a9340b Mon Sep 17 00:00:00 2001 From: Emmanuel Mathot Date: Thu, 29 Apr 2021 16:56:30 +0200 Subject: [PATCH 54/61] Update best-practices.md great :-) Co-authored-by: Chris Holmes --- best-practices.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/best-practices.md b/best-practices.md index 2f48b281..0b129280 100644 --- a/best-practices.md +++ b/best-practices.md @@ -155,7 +155,7 @@ data. One of the key properties is the ID. The specification is quite flexible o providers can easily use their same ID when they translate their data into STAC - they just need to be sure it is globally unique, so may need a prefix. But the use of URI or file path reserved characters such as `:` or `/` is discouraged since this will result in [percented encoded](https://tools.ietf.org/html/rfc3986#section-2) [STAC API](https://github.com/radiantearth/stac-api-spec) -endpoints and also the [IDs can't be used as file names](#catalog-layout). +endpoints and it prevents the use of IDs as file names as recommended in the [catalog layout](#catalog-layout) best practices. ### Searchable Identifiers From 20f7e716e8606248c3b6779e1b46bdd8ee9024f1 Mon Sep 17 00:00:00 2001 From: Chris Holmes Date: Thu, 29 Apr 2021 11:16:52 -0700 Subject: [PATCH 55/61] new overview section --- CHANGELOG.md | 2 ++ overview.md | 25 ++++++++++++++++++++++++- 2 files changed, 26 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ccef6db1..96b1e62f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,6 +12,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. - 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. +- Overview section linking to various foundational standards. ### Changed @@ -22,6 +23,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. - `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. ## [v1.0.0-rc.2] - 2021-03-30 diff --git a/overview.md b/overview.md index 306daf5f..bc65df31 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 their [Feature Collection](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#_collection_) +(and the full API 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. STAC defines `null` explicitly +for some fields, where it has a particular meaning. It should not be used otherwise - 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 From 3a3cc0992dfdfc396a9f4876c616c47456f8f52a Mon Sep 17 00:00:00 2001 From: Chris Holmes Date: Thu, 29 Apr 2021 11:20:47 -0700 Subject: [PATCH 56/61] updated changelog with pr link --- CHANGELOG.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 96b1e62f..4bdfcd2f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,7 +12,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. - 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. -- Overview section linking to various foundational standards. +- Overview section linking to various foundational standards. ([#1111](https://github.com/radiantearth/stac-spec/pull/1111)) ### Changed @@ -23,7 +23,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. - `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. +- 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 From 17c149324bae9572b826b8353802a52e712b0c56 Mon Sep 17 00:00:00 2001 From: Chris Holmes Date: Thu, 29 Apr 2021 13:05:12 -0700 Subject: [PATCH 57/61] updates from PR review --- overview.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/overview.md b/overview.md index bc65df31..0e9952c3 100644 --- a/overview.md +++ b/overview.md @@ -21,8 +21,8 @@ JSON Schemas provide the core testing definitions, and are used in an array of v 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 their [Feature Collection](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#_collection_) -(and the full API is the foundation for the STAC API specification). +Collection extends their [Collection](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#_collection_) +JSON (and the full API 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 @@ -30,9 +30,8 @@ recommended to read up on them. STAC development is guided by set of core philos 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. STAC defines `null` explicitly -for some fields, where it has a particular meaning. It should not be used otherwise - instead the field should be left -out entirely.* +*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 From dfeaf64c639e707484fb8a85cf847729a49019fb Mon Sep 17 00:00:00 2001 From: Chris Holmes Date: Thu, 29 Apr 2021 13:07:45 -0700 Subject: [PATCH 58/61] more fixes from PR feedback --- overview.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/overview.md b/overview.md index 0e9952c3..34ec0291 100644 --- a/overview.md +++ b/overview.md @@ -21,8 +21,8 @@ JSON Schemas provide the core testing definitions, and are used in an array of v 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 their [Collection](http://docs.opengeospatial.org/is/17-069r3/17-069r3.html#_collection_) -JSON (and the full API is the foundation for the STAC API specification). +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 From 06aea1c5658a5e0533d05298e1fe7340903c567c Mon Sep 17 00:00:00 2001 From: Chris Holmes Date: Thu, 29 Apr 2021 13:08:57 -0700 Subject: [PATCH 59/61] less characters in a line --- overview.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/overview.md b/overview.md index 34ec0291..e87d43ec 100644 --- a/overview.md +++ b/overview.md @@ -31,7 +31,8 @@ building small reusable parts that are loosely coupled, focusing on developers, [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.* +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 From d6103b8262a4b0b77536a00a3f3d835254427fce Mon Sep 17 00:00:00 2001 From: Chris Holmes Date: Thu, 29 Apr 2021 13:42:06 -0700 Subject: [PATCH 60/61] update versions, changelog edits --- CHANGELOG.md | 7 +++++-- catalog-spec/json-schema/catalog-core.json | 4 ++-- catalog-spec/json-schema/catalog.json | 2 +- collection-spec/json-schema/collection.json | 2 +- examples/catalog.json | 4 ++-- examples/collection-only/collection-with-schemas.json | 2 +- examples/collection-only/collection.json | 2 +- examples/collection.json | 4 ++-- examples/collectionless-item.json | 2 +- examples/core-item.json | 2 +- examples/extended-item.json | 2 +- examples/extensions-collection/collection.json | 2 +- .../extensions-collection/proj-example/proj-example.json | 2 +- examples/simple-item.json | 2 +- item-spec/json-schema/basics.json | 2 +- item-spec/json-schema/datetime.json | 2 +- item-spec/json-schema/instrument.json | 2 +- item-spec/json-schema/item.json | 4 ++-- item-spec/json-schema/licensing.json | 2 +- item-spec/json-schema/provider.json | 2 +- package.json | 2 +- 21 files changed, 29 insertions(+), 26 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4bdfcd2f..46d40690 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,11 +7,13 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. ## [Unreleased] +## [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. +- 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 @@ -19,7 +21,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. - 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). +- 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)) @@ -421,6 +423,7 @@ See the [milestone 0.4.0 in the issue tracker](https://github.com/radiantearth/s Thanks @hgs-msmith, @matthewhanson, @hgs-trutherford, @rouault, @joshfix, @alkamin, @hemphillda, @jeffnaus and @fredliporace for contributing to the spec directly, and to [everyone](https://github.com/opengeospatial/wfs3hackathon/blob/master/notes/introductions.md#participants) who participated in the [Ft Collins sprint](https://github.com/radiantearth/community-sprints/tree/master/03072018-ft-collins-co) and brought great ideas. [Unreleased]: +[v1.0.0-rc.2]: [v1.0.0-rc.2]: [v1.0.0-rc.1]: [v1.0.0-beta.2]: diff --git a/catalog-spec/json-schema/catalog-core.json b/catalog-spec/json-schema/catalog-core.json index 214df4bb..987fe547 100644 --- a/catalog-spec/json-schema/catalog-core.json +++ b/catalog-spec/json-schema/catalog-core.json @@ -1,6 +1,6 @@ { "$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#", + "$id": "https://schemas.stacspec.org/v1.0.0-rc.3/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": [ @@ -22,7 +22,7 @@ "stac_version": { "title": "STAC version", "type": "string", - "const": "1.0.0-rc.2" + "const": "1.0.0-rc.3" }, "stac_extensions": { "title": "STAC extensions", diff --git a/catalog-spec/json-schema/catalog.json b/catalog-spec/json-schema/catalog.json index c971c80b..052052e1 100644 --- a/catalog-spec/json-schema/catalog.json +++ b/catalog-spec/json-schema/catalog.json @@ -1,6 +1,6 @@ { "$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-rc.3/catalog-spec/json-schema/catalog.json#", "title": "STAC Catalog Specification", "description": "This object represents Catalogs in a SpatioTemporal Asset Catalog.", "allOf": [ diff --git a/collection-spec/json-schema/collection.json b/collection-spec/json-schema/collection.json index 19bb9611..942144c1 100644 --- a/collection-spec/json-schema/collection.json +++ b/collection-spec/json-schema/collection.json @@ -1,6 +1,6 @@ { "$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-rc.3/collection-spec/json-schema/collection.json#", "title": "STAC Collection Specification", "description": "This object represents Collections in a SpatioTemporal Asset Catalog.", "allOf": [ diff --git a/examples/catalog.json b/examples/catalog.json index 5272652d..1003b20b 100644 --- a/examples/catalog.json +++ b/examples/catalog.json @@ -1,7 +1,7 @@ { "id": "examples", "type": "Catalog", - "stac_version": "1.0.0-rc.2", + "stac_version": "1.0.0-rc.3", "description": "This catalog is a simple demonstration of an example catalog that is used to organize a hierarchy of collections and their items.", "links": [ { @@ -35,7 +35,7 @@ }, { "rel": "self", - "href": "https://raw.githubusercontent.com/radiantearth/stac-spec/v1.0.0-rc.2/examples/catalog.json", + "href": "https://raw.githubusercontent.com/radiantearth/stac-spec/v1.0.0-rc.3/examples/catalog.json", "type": "application/json" } ] diff --git a/examples/collection-only/collection-with-schemas.json b/examples/collection-only/collection-with-schemas.json index 58562783..1cddc65c 100644 --- a/examples/collection-only/collection-with-schemas.json +++ b/examples/collection-only/collection-with-schemas.json @@ -1,5 +1,5 @@ { - "stac_version": "1.0.0-rc.2", + "stac_version": "1.0.0-rc.3", "stac_extensions": [ "https://stac-extensions.github.io/eo/v1.0.0/schema.json", "https://stac-extensions.github.io/sat/v1.0.0/schema.json", diff --git a/examples/collection-only/collection.json b/examples/collection-only/collection.json index 01f580bf..c5cb7a2c 100644 --- a/examples/collection-only/collection.json +++ b/examples/collection-only/collection.json @@ -1,6 +1,6 @@ { "type": "Collection", - "stac_version": "1.0.0-rc.2", + "stac_version": "1.0.0-rc.3", "stac_extensions": [ "https://stac-extensions.github.io/eo/v1.0.0/schema.json", "https://stac-extensions.github.io/projection/v1.0.0/schema.json", diff --git a/examples/collection.json b/examples/collection.json index 28604ecf..790bcf8d 100644 --- a/examples/collection.json +++ b/examples/collection.json @@ -5,7 +5,7 @@ "https://stac-extensions.github.io/eo/v1.0.0/schema.json", "https://stac-extensions.github.io/view/v1.0.0/schema.json" ], - "stac_version": "1.0.0-rc.2", + "stac_version": "1.0.0-rc.3", "description": "A simple collection demonstrating core catalog fields with links to a couple of items", "title": "Simple Example Collection", "providers": [ @@ -103,7 +103,7 @@ }, { "rel": "self", - "href": "https://raw.githubusercontent.com/radiantearth/stac-spec/v1.0.0-rc.2/examples/collection.json", + "href": "https://raw.githubusercontent.com/radiantearth/stac-spec/v1.0.0-rc.3/examples/collection.json", "type": "application/json" } ] diff --git a/examples/collectionless-item.json b/examples/collectionless-item.json index a1b890c1..c4b224d5 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-rc.3", "stac_extensions": [ "https://stac-extensions.github.io/eo/v1.0.0/schema.json", "https://stac-extensions.github.io/view/v1.0.0/schema.json" diff --git a/examples/core-item.json b/examples/core-item.json index 06fa8b0a..dc95ff80 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-rc.3", "stac_extensions": [], "type": "Feature", "id": "20201211_223832_CS2", diff --git a/examples/extended-item.json b/examples/extended-item.json index b27f4752..85b3f598 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-rc.3", "stac_extensions": [ "https://stac-extensions.github.io/eo/v1.0.0/schema.json", "https://stac-extensions.github.io/projection/v1.0.0/schema.json", diff --git a/examples/extensions-collection/collection.json b/examples/extensions-collection/collection.json index a79fabe3..fa0fe85d 100644 --- a/examples/extensions-collection/collection.json +++ b/examples/extensions-collection/collection.json @@ -1,7 +1,7 @@ { "id": "extensions-collection", "type": "Collection", - "stac_version": "1.0.0-rc.2", + "stac_version": "1.0.0-rc.3", "description": "A heterogenous collection containing deeper examples of various extensions", "links": [ { diff --git a/examples/extensions-collection/proj-example/proj-example.json b/examples/extensions-collection/proj-example/proj-example.json index 71d3b2d3..64a42dc1 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-rc.3", "id": "proj-example", "properties": { "datetime": "2018-10-01T01:08:32.033000Z", diff --git a/examples/simple-item.json b/examples/simple-item.json index f505fda8..f74871fb 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-rc.3", "stac_extensions": [], "type": "Feature", "id": "20201211_223832_CS2", diff --git a/item-spec/json-schema/basics.json b/item-spec/json-schema/basics.json index a5b26a3d..6b66ccf5 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-rc.3/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 fa540a32..87fb300b 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-rc.3/item-spec/json-schema/datetime.json#", "title": "Date and Time Fields", "type": "object", "dependencies": { diff --git a/item-spec/json-schema/instrument.json b/item-spec/json-schema/instrument.json index 78d836ba..722af252 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-rc.3/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 e228e2d2..10bfa2b2 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-rc.3/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,7 +93,7 @@ "stac_version": { "title": "STAC version", "type": "string", - "const": "1.0.0-rc.2" + "const": "1.0.0-rc.3" }, "stac_extensions": { "title": "STAC extensions", diff --git a/item-spec/json-schema/licensing.json b/item-spec/json-schema/licensing.json index a20dde60..525b7c25 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-rc.3/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..36f43cb0 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-rc.3/item-spec/json-schema/provider.json#", "title": "Provider Fields", "type": "object", "properties": { diff --git a/package.json b/package.json index ed5c9edb..1789d03a 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "stac-spec", - "version": "1.0.0-rc.2", + "version": "1.0.0-rc.3", "description": "STAC spec helpers to check the spec.", "repository": "https://github.com/radiantearth/stac-spec", "license": "Apache-2.0", From 094b90d649cb37b1fd6b7d8df34451aafee02aab Mon Sep 17 00:00:00 2001 From: Chris Holmes Date: Thu, 29 Apr 2021 13:48:10 -0700 Subject: [PATCH 61/61] fixed linking issue --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 46d40690..f8c64c9d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -423,7 +423,7 @@ See the [milestone 0.4.0 in the issue tracker](https://github.com/radiantearth/s Thanks @hgs-msmith, @matthewhanson, @hgs-trutherford, @rouault, @joshfix, @alkamin, @hemphillda, @jeffnaus and @fredliporace for contributing to the spec directly, and to [everyone](https://github.com/opengeospatial/wfs3hackathon/blob/master/notes/introductions.md#participants) who participated in the [Ft Collins sprint](https://github.com/radiantearth/community-sprints/tree/master/03072018-ft-collins-co) and brought great ideas. [Unreleased]: -[v1.0.0-rc.2]: +[v1.0.0-rc.3]: [v1.0.0-rc.2]: [v1.0.0-rc.1]: [v1.0.0-beta.2]: