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