From cfb0cd84ba82c200fcfb32aa9b1520c01ef6756d Mon Sep 17 00:00:00 2001 From: Daniel Silk Date: Tue, 22 Jun 2021 09:07:51 +1200 Subject: [PATCH 01/25] docs: fix collectionless item title in catalog example --- examples/catalog.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/catalog.json b/examples/catalog.json index b5910be3c..38e27412e 100644 --- a/examples/catalog.json +++ b/examples/catalog.json @@ -32,7 +32,7 @@ "rel": "item", "href": "./collectionless-item.json", "type": "application/json", - "title": "Collection with no items (standalone)" + "title": "Item that does not have a collection (not recommended, but allowed by the spec)" }, { "rel": "self", From 858a0a6c9787901aa0902ada62585093efcc128b Mon Sep 17 00:00:00 2001 From: Andy Wilson Date: Tue, 20 Jul 2021 00:08:05 -0500 Subject: [PATCH 02/25] Fix a typo in collection-spec.md `ollections` -> `Collections` --- collection-spec/collection-spec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/collection-spec/collection-spec.md b/collection-spec/collection-spec.md index 8b6f4f155..83a6ea776 100644 --- a/collection-spec/collection-spec.md +++ b/collection-spec/collection-spec.md @@ -256,7 +256,7 @@ 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. +The following table explains places where custom STAC `rel` types are used for Collections. This is done where there is not a clear official option, or where STAC uses an official type but adds additional meaning for the STAC context. | Type | Description | From d0482ac3e1df2fd154c589ee2efe61e2c14a7b16 Mon Sep 17 00:00:00 2001 From: Pete Gadomski Date: Mon, 2 Aug 2021 14:15:09 -0600 Subject: [PATCH 03/25] Minor punctuation fix in best practices --- best-practices.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/best-practices.md b/best-practices.md index 6eed1e189..724d7d1f8 100644 --- a/best-practices.md +++ b/best-practices.md @@ -402,7 +402,7 @@ file that just has the bands needed for display *Note: This section uses the term 'Catalog' (with an uppercase C) to refer to the JSON entity specified in the [Catalog spec](catalog-spec/catalog-spec.md), and 'catalog' (with a lowercase c) to refer to any full STAC implementation, -which can be any mix of Catalogs Collections and Items.* +which can be any mix of Catalogs, Collections, and Items.* ### Static and Dynamic Catalogs From a04c3c89221f8cce1d0b2240646a0e2828a6475e Mon Sep 17 00:00:00 2001 From: Chris Holmes Date: Wed, 13 Oct 2021 11:17:42 -0700 Subject: [PATCH 04/25] Very minor text fixes (#1158) Co-authored-by: Matthew Hanson --- collection-spec/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/collection-spec/README.md b/collection-spec/README.md index c94bfc317..ecd8046e9 100644 --- a/collection-spec/README.md +++ b/collection-spec/README.md @@ -7,8 +7,8 @@ Collection can have parent Catalog and Collection objects, as well as child Item and Collection objects. These parent-child relationships among objects of these types, as there is no subtyping relationship between the Collection and Catalog types, even through they share field names. -A Collection provides a flexible mechanism to provide additional metadata about a set of Items. -Generally, is used to describe a set of assets that +A Collection provides a flexible mechanism to provide additional metadata about a set of Items. +Generally, it is used to describe a set of assets that are defined with the same properties and share higher-level metadata. There is no standardized name for this sort of logical grouping, but other places it is called a " dataset series" (ESA, ISO 19115), "collection" (CNES, NASA), "dataset" (JAXA), or "product" From 44ae12b68db85049058220bd6f6e914b4edd2658 Mon Sep 17 00:00:00 2001 From: Daniel Silk Date: Mon, 29 Nov 2021 08:20:59 +1300 Subject: [PATCH 05/25] fix: change epsg summary to an array of all values `proj:epsg` should be summarised as an array of all values, not a Range Object, per [stac-fields](https://github.com/stac-utils/stac-fields/blob/v1.0.0-beta.10/fields.json#L575) and [other examples](https://github.com/radiantearth/stac-spec/blob/v1.0.0/examples/collection-only/collection.json#L90). --- examples/collection.json | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/examples/collection.json b/examples/collection.json index 07643b600..6a60a4b04 100644 --- a/examples/collection.json +++ b/examples/collection.json @@ -61,10 +61,9 @@ "minimum": 1.2, "maximum": 1.2 }, - "proj:epsg": { - "minimum": 32659, - "maximum": 32659 - }, + "proj:epsg": [ + 32659 + ], "view:sun_elevation": { "minimum": 54.9, "maximum": 54.9 From 232a2d43bc9171ceeb697d7ef2f73eacc9fb312b Mon Sep 17 00:00:00 2001 From: Tim Schaub Date: Tue, 22 Feb 2022 15:48:25 -0700 Subject: [PATCH 06/25] Assorted spelling changes --- overview.md | 8 ++++---- principles.md | 2 +- process.md | 6 +++--- 3 files changed, 8 insertions(+), 8 deletions(-) diff --git a/overview.md b/overview.md index e87d43ecb..d566e5592 100644 --- a/overview.md +++ b/overview.md @@ -104,7 +104,7 @@ The second case is used when one wants to represent diverse data in a single pla has an internal catalog with Landsat 8, Sentinel 2, NAIP data and several commercial imagery providers then they'd have a root Catalog that would link to a number of different Collections. -So in conclusion it's best to use Collections for what you want user to find as starting point, and then +So in conclusion it's best to use Collections for what you want users to find as the starting point, and then Catalogs are just for structuring and grouping the data. Future work includes a mechanism to actually search Collection-level data, hopefully in concert with other specifications. @@ -166,7 +166,7 @@ linked to across the web. ### Static and Dynamic Catalogs -The Catalog specification is designed so it can be implemented as easily as possibly. This can be as simple as +The Catalog specification is designed so it can be implemented as easily as possible. This can be as simple as simply putting linked json files on a file server or an object storage service (like [AWS S3](https://aws.amazon.com/s3/)), or it can be generated on the fly by a live server. The first type of implementation is often called a 'static catalog', and any catalog that is not just files is called a 'dynamic catalog'. You can read more about the two types along with @@ -177,7 +177,7 @@ along with how to keep a [dynamic catalog in sync](best-practices.md#static-to-d In addition to information about different catalog types, the [best practices document](best-practices.md) has a number of suggestions on how to organize and implement good catalogs. The [catalog specification](catalog-spec/catalog-spec.md) -is designed for maximum flexbility, so none of these are required, but they provide guidance for implementors who +is designed for maximum flexibility, so none of these are required, but they provide guidance for implementors who want to follow what most of the STAC community is doing. - [Catalog Layout](best-practices.md#catalog-layout) is likely the most important section, as following its @@ -209,5 +209,5 @@ and doesn't require links down to sub-catalogs and Items. This is most often use does operations at the layer / coverage level, letting users manipulate a whole collection of assets at once. They often have an optimized internal format that doesn't make sense to expose as Items. [OpenEO](https://openeo.org/) and [Google Earth Engine](https://earthengine.google.com/) are two examples that only use STAC collections, and -both would be hardpressed to expose individual Items due to their architectures. For others implementing STAC +both would be hard-pressed to expose individual Items due to their architectures. For others implementing STAC Collections can also be a nice way to start and achieve some level of interoperability. diff --git a/principles.md b/principles.md index 72ef53be1..42c9a3ab9 100644 --- a/principles.md +++ b/principles.md @@ -17,7 +17,7 @@ so it should also be core. [JSON API](http://jsonapi.org/) should be used as bas - **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, +as separate specifications that build on the core. But the core specs should be small and easily understandable, 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. diff --git a/process.md b/process.md index 92fbb7b64..3becf50b4 100644 --- a/process.md +++ b/process.md @@ -38,7 +38,7 @@ The current list of people who are part of the 'core STAC team', and can approve - [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 +and/or helping review other PR's. Nominations are reviewed by the [PSC](#project-steering-committee), and must receive 3 positive votes and no negatives. ### Release Process @@ -93,7 +93,7 @@ reviews. #### Project Steering Committee -For the rare case where a decision cannot be reached by consensus, there is a Project Steerting Committee that has ultimate +For the rare case where a decision cannot be reached by consensus, there is a Project Steering Committee that has ultimate decision making authority. This consists of individuals who are intended to represent the various communities which have a 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. @@ -115,6 +115,6 @@ A new PSC member can be nominated at any time. Voting for a new PSC is done by c generally given in recognition to very significant contributions to the specification or the broader ecosystem. PSC members are not expected to be technical, and we hope to recognized contributions in documentation, outreach and evangelism. -Nominated PSC members must recieve a majority of +1 vote’s from the PSC, and no -1’s. +Nominated PSC members must receive a majority of +1 vote’s from the PSC, and no -1’s. The initial PSC was selected by Chris Holmes, who was deemed the 'Benevolent Dictator for Life' for the bootstrapping phase. From ea2b25a806956e4c5888eb05ea12b55f5f0e39ab Mon Sep 17 00:00:00 2001 From: Jonathan Healy Date: Fri, 25 Feb 2022 07:18:42 -0800 Subject: [PATCH 07/25] a few grammar errors (#1163) Co-authored-by: Matthew Hanson Co-authored-by: Chris Holmes --- best-practices.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/best-practices.md b/best-practices.md index 724d7d1f8..746c8f149 100644 --- a/best-practices.md +++ b/best-practices.md @@ -255,7 +255,7 @@ Both are compliant with OGC API - Features, adding richer search capabilities to As [described in the Item spec](item-spec/item-spec.md#additional-fields-for-assets), it is possible to use fields typically found in Item properties at the asset level. This mechanism of overriding or providing Item Properties only in the Assets 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. +providing them 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. @@ -283,7 +283,7 @@ providing them at at the Asset level can prove to be very useful for using the d [Media Types](https://en.wikipedia.org/wiki/Media_type) are a key element that enables STAC to be a rich source of information for clients. The best practice is to use as specific of a media type as is possible (so if a file is a GeoJSON then don't use a JSON media type), and to use [registered](https://www.iana.org/assignments/media-types/media-types.xhtml) IANA types as much as possible. -The following table lists types that commonly show up in STAC assets. And the the [section](#formats-with-no-registered-media-type) +The following table lists types that commonly show up in STAC assets. And the [section](#formats-with-no-registered-media-type) past that gives recommendations on what to do if you have a format in your asset that does not have an IANA registered type. #### Common Media Types in STAC @@ -729,7 +729,7 @@ database, but it could just as easily be a server-based process. Any tool that crawls a STAC implementation or encounters a STAC file in the wild needs a clear way to determine if it is an Item, Collection or Catalog. As of 1.0.0 this is done primarily -with the `type` field, and secondarily in Items with `stac_version`, or optionally the `rel` of the link to it. +with the `type` field, and secondarily in Items with `stac_version`, or optionally with the `rel` of the link to it. ```shell if type is 'Collection' @@ -744,8 +744,8 @@ else When crawling a STAC implementation, one can also make use of the [relation type](catalog-spec/catalog-spec.md#relation-types ) (`rel` field) when following a link. If it is an `item` rel type then the file must be a STAC Item. If it is `child`, `parent` or -`root` then it must be a Catalog or a Collection, though the final determination between the two requires looking at the the `type` field -in the Catalog or Collection JSON that is linked to. Note that there is also a `type` field in STAC Link and Asset objects, but that +`root` then it must be a Catalog or a Collection, though the final determination between the two requires looking at the `type` field +in the Catalog or Collection JSON that it is linked to. Note that there is also a `type` field in STAC Link and Asset objects, but that is for the Media Type, but there are not specific media types for Catalog and Collection. See the sections on [STAC media types](catalog-spec/catalog-spec.md#media-types), and [Asset media types](item-spec/item-spec.md#asset-media-type) for more information. From 417df5cff175d758f8abf26c89f29ec9791fe0d2 Mon Sep 17 00:00:00 2001 From: Pete Gadomski Date: Tue, 8 Mar 2022 10:10:34 -0700 Subject: [PATCH 08/25] fix: reword recommendations on `self` links There was some confusing language about when `self` links should be used. This commit fixes the language in the "Use of links" section of the best practices document, and updates the wording in the item spec to reference the best practices section. --- best-practices.md | 8 ++++---- item-spec/item-spec.md | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/best-practices.md b/best-practices.md index 746c8f149..68902c780 100644 --- a/best-practices.md +++ b/best-practices.md @@ -561,10 +561,10 @@ just meant to give users a sense of what types of values they could expect. ### Use of links -The STAC specifications allow both relative and absolute links, and says that `self` links are not required, but are -strongly recommended. This is what the spec must say to enable the various use cases, but there is more subtlety for when it -is essential to use different link types. The best practice is to use one of the below catalog types, applying the link -recommendations consistently, instead of just haphazardly applying relative links in some places and absolute ones in other places. +The STAC specifications allow both relative and absolute links, and it is important to choose the correct link types so that +your STAC catalogs are easy to explore and resilient to any future changes to their layouts. The best practice is to use one +of the below catalog types, applying the link recommendations consistently, instead of just haphazardly applying relative links +in some places and absolute ones in other places. #### Self-contained Catalogs diff --git a/item-spec/item-spec.md b/item-spec/item-spec.md index 48358145a..6b5e5f350 100644 --- a/item-spec/item-spec.md +++ b/item-spec/item-spec.md @@ -61,7 +61,7 @@ inherited from GeoJSON. | geometry | [GeoJSON Geometry Object](https://tools.ietf.org/html/rfc7946#section-3.1) \| [null](https://tools.ietf.org/html/rfc7946#section-3.2) | **REQUIRED.** Defines the full footprint of the asset represented by this item, formatted according to [RFC 7946, section 3.1](https://tools.ietf.org/html/rfc7946#section-3.1). The footprint should be the default GeoJSON geometry, though additional geometries can be included. Coordinates are specified in Longitude/Latitude or Longitude/Latitude/Elevation based on [WGS 84](http://www.opengis.net/def/crs/OGC/1.3/CRS84). | | bbox | \[number] | **REQUIRED if `geometry` is not `null`.** Bounding Box of the asset represented by this Item, formatted according to [RFC 7946, section 5](https://tools.ietf.org/html/rfc7946#section-5). | | properties | [Properties Object](#properties-object) | **REQUIRED.** A dictionary of additional metadata for the Item. | -| links | \[[Link Object](#link-object)] | **REQUIRED.** List of link objects to resources and related URLs. A link with the `rel` set to `self` is strongly recommended. | +| links | \[[Link Object](#link-object)] | **REQUIRED.** List of link objects to resources and related URLs. See the [best practices](../best-practices.md#use-of-links) for details on when the use `self` links is strongly recommended. | | assets | Map | **REQUIRED.** Dictionary of asset objects that can be downloaded, each with a unique key. | | collection | string | The `id` of the STAC Collection this Item references to (see [`collection` relation type](#relation-types)). This field is *required* if such a relation type is present and is *not allowed* otherwise. This field provides an easy way for a user to search for any Items that belong in a specified Collection. Must be a non-empty string. | From 07d42ea58f4cec535ae2640974b14dfbd517efa2 Mon Sep 17 00:00:00 2001 From: Pete Gadomski Date: Tue, 8 Mar 2022 10:11:03 -0700 Subject: [PATCH 09/25] chore: update changelog --- CHANGELOG.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 47bf6e227..1d3af6a21 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. ## [Unreleased] +### Removed + +- "Strongly recommended" language around `self` links in the item spec. ([#1173](https://github.com/radiantearth/stac-spec/pull/1173)) + ## [v1.0.0] - 2021-05-25 ### Added From 48ada873b82575892369681d6b7a4f43c37c5330 Mon Sep 17 00:00:00 2001 From: Phil Varner Date: Tue, 18 Oct 2022 17:39:01 -0400 Subject: [PATCH 10/25] update code of conduct to v2.1 (#1185) * update code of conduct to v2.1 --- .remarkignore | 1 + CODE_OF_CONDUCT.md | 156 ++++++++++++++++++++++++++++++--------------- 2 files changed, 107 insertions(+), 50 deletions(-) create mode 100644 .remarkignore diff --git a/.remarkignore b/.remarkignore new file mode 100644 index 000000000..332776060 --- /dev/null +++ b/.remarkignore @@ -0,0 +1 @@ +/CODE_OF_CONDUCT.md \ No newline at end of file diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 984c77e64..5eac9d63d 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -2,75 +2,131 @@ ## Our Pledge -In the interest of fostering an open and welcoming environment, we as -contributors and maintainers pledge to making participation in our project and -our community a harassment-free experience for everyone, regardless of age, body -size, disability, ethnicity, sex characteristics, gender identity and expression, -level of experience, education, socio-economic status, nationality, personal -appearance, race, religion, or sexual identity and orientation. +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, caste, color, religion, or sexual +identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. ## Our Standards -Examples of behavior that contributes to creating a positive environment -include: +Examples of behavior that contributes to a positive environment for our +community 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 +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +* Focusing on what is best not just for us as individuals, but for the overall + community -Examples of unacceptable behavior by participants include: +Examples of unacceptable behavior include: -- 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 - address, without explicit permission -- Other conduct which could reasonably be considered inappropriate in a - professional setting +* The use of sexualized language or imagery, and sexual attention or advances of + any kind +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or email address, + without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting -## Our Responsibilities +## Enforcement Responsibilities -Project maintainers are responsible for clarifying the standards of acceptable -behavior and are expected to take appropriate and fair corrective action in -response to any instances of unacceptable behavior. +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. -Project maintainers have the right and responsibility to remove, edit, or -reject comments, commits, code, wiki edits, issues, and other contributions -that are not aligned to this Code of Conduct, or to ban temporarily or -permanently any contributor for other behaviors that they deem inappropriate, -threatening, offensive, or harmful. +Community leaders have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, and will communicate reasons for moderation +decisions when appropriate. ## Scope -This Code of Conduct applies both within project spaces and in public spaces -when an individual is representing the project or its community. Examples of -representing a project or community include using an official project e-mail -address, posting via an official social media account, or acting as an appointed -representative at an online or offline event. Representation of a project may be -further defined and clarified by project maintainers. +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official e-mail address, +posting via an official social media account, or acting as an appointed +representative at an online or offline event. ## Enforcement Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported by contacting the project team at [stac-spec-admins@googlegroups.com](mailto:stac-spec-admins@googlegroups.com). All -complaints will be reviewed and investigated and will result in a response that -is deemed necessary and appropriate to the circumstances. The project team is -obligated to maintain confidentiality with regard to the reporter of an incident. -Further details of specific enforcement policies may be posted separately. +reported to the community leaders responsible for enforcement at +[stac-spec-admins@googlegroups.com](mailto:stac-spec-admins@googlegroups.com). +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. + +### 2. Warning -Project maintainers who do not follow or enforce the Code of Conduct in good -faith may face temporary or permanent repercussions as determined by other -members of the project's leadership. +**Community Impact**: A violation through a single incident or series of +actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or permanent +ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within the +community. ## Attribution -This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, -available at +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.1, available at +[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1]. + +Community Impact Guidelines were inspired by +[Mozilla's code of conduct enforcement ladder][Mozilla CoC]. -[homepage]: +For answers to common questions about this code of conduct, see the FAQ at +[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at +[https://www.contributor-covenant.org/translations][translations]. -For answers to common questions about this code of conduct, see - +[homepage]: https://www.contributor-covenant.org +[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html +[Mozilla CoC]: https://github.com/mozilla/diversity +[FAQ]: https://www.contributor-covenant.org/faq +[translations]: https://www.contributor-covenant.org/translations From 60d472275b053a16dbaeb9722f4503619bdc02c0 Mon Sep 17 00:00:00 2001 From: Takahiro Miyoshi Date: Sat, 22 Oct 2022 23:06:25 +0900 Subject: [PATCH 11/25] Fix typos in best-practices.md --- best-practices.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/best-practices.md b/best-practices.md index 68902c780..79105313d 100644 --- a/best-practices.md +++ b/best-practices.md @@ -281,7 +281,7 @@ providing them at the Asset level can prove to be very useful for using the data ### Working with Media Types [Media Types](https://en.wikipedia.org/wiki/Media_type) are a key element that enables STAC to be a rich source of information for -clients. The best practice is to use as specific of a media type as is possible (so if a file is a GeoJSON then don't use a JSON +clients. The best practice is to use as specific of a media type as possible (so if a file is a GeoJSON then don't use a JSON media type), and to use [registered](https://www.iana.org/assignments/media-types/media-types.xhtml) IANA types as much as possible. The following table lists types that commonly show up in STAC assets. And the [section](#formats-with-no-registered-media-type) past that gives recommendations on what to do if you have a format in your asset that does not have an IANA registered type. @@ -341,7 +341,7 @@ In addition to the thumbnail, data and overview [roles listed](item-spec/item-sp are a number of roles that are emerging in practice, but don't have enough widespread use to justify standardizing them. So if you want to re-use other roles then try to find them on the list below, and also feel free to suggest more to include here. -The 'source' field lists where the role comes from. The ones the say Item Spec are the only 'official' roles that are fully +The 'source' field lists where the role comes from. The ones that say Item Spec are the only 'official' roles that are fully standardized. In time others on this list may migrate to a more 'official' list. Those that say 'best practice' are just from this doc, the listing is the table below. The ones from extensions are mostly just 'best practices' in the extensions, as there are few actual role requirements. From 9579d64b277a2da4e43004103a4b04f5d3d89d00 Mon Sep 17 00:00:00 2001 From: Takahiro Miyoshi Date: Fri, 28 Oct 2022 00:41:35 +0900 Subject: [PATCH 12/25] Fix typos (repeated "the") --- collection-spec/collection-spec.md | 2 +- item-spec/item-spec.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/collection-spec/collection-spec.md b/collection-spec/collection-spec.md index 83a6ea776..6d621c633 100644 --- a/collection-spec/collection-spec.md +++ b/collection-spec/collection-spec.md @@ -70,7 +70,7 @@ In general, STAC versions can be mixed, but please keep the [recommended best pr A list of extensions the Collection implements. The list consists of URLs to JSON Schema files that can be used for validation. This list must only contain extensions that extend the Collection specification itself, -see the the 'Scope' for each of the extensions. +see the 'Scope' for each of the extensions. This must **not** declare the extensions that are only implemented in child Collection objects or child Item objects. #### id diff --git a/item-spec/item-spec.md b/item-spec/item-spec.md index 6b5e5f350..aed4b2dc1 100644 --- a/item-spec/item-spec.md +++ b/item-spec/item-spec.md @@ -76,7 +76,7 @@ In general, STAC versions can be mixed, but please keep the [recommended best pr A list of extensions the Item implements. The list consists of URLs to JSON Schema files that can be used for validation. This list must only contain extensions that extend the Item specification itself, -see the the 'Scope' for each of the extensions. +see the 'Scope' for each of the extensions. #### id @@ -247,7 +247,7 @@ is recommended only in special cases. See [Additional Fields for Assets](#additi Any media type can be used in an Item's asset `type` field, and [registered](https://www.iana.org/assignments/media-types/media-types.xhtml) Media Types are preferred. STAC Items that have sidecar metadata files associated with a data asset (e.g, `.tfw`, Landsat 8 MTL files) -should use media types appropriate for the the metadata file. For example, if it is a plain text file, then `text/plain` +should use media types appropriate for the metadata file. For example, if it is a plain text file, then `text/plain` would be appropriate; if it is an XML, then `text/xml` is appropriate. For more information on media types as well as a list of [common media types](../best-practices.md#common-media-types-in-stac) used in STAC see the [best practice on working with media types](../best-practices.md#working-with-media-types). From bdd391ad75a5197752bdce1078148175241d1637 Mon Sep 17 00:00:00 2001 From: Nick Klein-Baer <47011214+nkleinbaer@users.noreply.github.com> Date: Mon, 9 Jan 2023 10:04:49 -0700 Subject: [PATCH 13/25] update description for property in (#1206) --- item-spec/item-spec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/item-spec/item-spec.md b/item-spec/item-spec.md index aed4b2dc1..64b6f5c4c 100644 --- a/item-spec/item-spec.md +++ b/item-spec/item-spec.md @@ -59,7 +59,7 @@ inherited from GeoJSON. | stac_extensions | \[string] | A list of extensions the Item implements. | | id | string | **REQUIRED.** Provider identifier. The ID should be unique within the [Collection](../collection-spec/collection-spec.md) that contains the Item. | | geometry | [GeoJSON Geometry Object](https://tools.ietf.org/html/rfc7946#section-3.1) \| [null](https://tools.ietf.org/html/rfc7946#section-3.2) | **REQUIRED.** Defines the full footprint of the asset represented by this item, formatted according to [RFC 7946, section 3.1](https://tools.ietf.org/html/rfc7946#section-3.1). The footprint should be the default GeoJSON geometry, though additional geometries can be included. Coordinates are specified in Longitude/Latitude or Longitude/Latitude/Elevation based on [WGS 84](http://www.opengis.net/def/crs/OGC/1.3/CRS84). | -| bbox | \[number] | **REQUIRED if `geometry` is not `null`.** Bounding Box of the asset represented by this Item, formatted according to [RFC 7946, section 5](https://tools.ietf.org/html/rfc7946#section-5). | +| bbox | \[number] | **REQUIRED if `geometry` is not `null`, prohibited if `geometry` is `null`.** Bounding Box of the asset represented by this Item, formatted according to [RFC 7946, section 5](https://tools.ietf.org/html/rfc7946#section-5). | | properties | [Properties Object](#properties-object) | **REQUIRED.** A dictionary of additional metadata for the Item. | | links | \[[Link Object](#link-object)] | **REQUIRED.** List of link objects to resources and related URLs. See the [best practices](../best-practices.md#use-of-links) for details on when the use `self` links is strongly recommended. | | assets | Map | **REQUIRED.** Dictionary of asset objects that can be downloaded, each with a unique key. | From a5c65d7f1739fbbebd8efca7ea39970178752c3d Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Mon, 9 Jan 2023 18:07:24 +0100 Subject: [PATCH 14/25] Update extensions readme (#1205) --- extensions/README.md | 153 +++++++++++++++++++++---------------------- 1 file changed, 75 insertions(+), 78 deletions(-) diff --git a/extensions/README.md b/extensions/README.md index 151983d04..684fa7985 100644 --- a/extensions/README.md +++ b/extensions/README.md @@ -2,14 +2,13 @@ - [Overview](#overview) - [Using Extensions](#using-extensions) - - [Extension IDs in `stac_extensions`](#extension-ids-in-stac_extensions) -- [Stable STAC Extensions](#stable-stac-extensions) + - [Extension identifiers in `stac_extensions`](#extension-identifiers-in-stac_extensions) - [Community Extensions](#community-extensions) - [Proposed extensions](#proposed-extensions) +- [Extension Maturity](#extension-maturity) - [Extending STAC](#extending-stac) - [General Conventions](#general-conventions) - [Proposing new extensions](#proposing-new-extensions) - - [Extension Maturity](#extension-maturity) - [Prefixes](#prefixes) - [Use of arrays and objects](#use-of-arrays-and-objects) @@ -18,74 +17,74 @@ One of the most important aspects of the SpatioTemporal Asset Catalog specification is its extensibility. The core STAC specification defines only a minimal core, but is designed for extension. It is expected that most real-world implementations will use several 'extensions' to fully describe their data. This document describes how extensions -work, and links to the 'core' extensions included in this repo, as well as to a variety of 'community' extensions. +work. -**For the complete list of available extensions see the [STAC extensions overview page](https://stac-extensions.github.io/).** +**For a list of most available extensions see the [STAC extensions overview page](https://stac-extensions.github.io/).** +Please note the [extension maturity](#extension-maturity) for each extension. -Extensions to the core STAC specification provide additional JSON fields that can be used to better describe +Extensions to the core STAC specification provide additional fields that can be used to better describe the data. Most tend to be about describing a particular domain or type of data, but some imply functionality. Extensions include a JSON Schema precisely describing the structure, a natural language description of the fields, and thorough examples. Anybody can create an extension for their data, and data providers often work together to share -fields between them to create a shared community extensions. See the section below on '[Extending STAC](#extending-stac)') -for information on how to get started. And everyone is encouraged to link to the extension in the table below, so others -can be aware of it. +fields between them to create a shared community extension. See the section below on '[Extending STAC](#extending-stac)') +for information on how to get started. Everyone is encouraged to add their extensions to the +[STAC extensions overview page](https://stac-extensions.github.io/), so others can be aware of it. -Each extension has at least one *owner*. You can find extension owners in each extension's README. +Each extension should have at least one *owner*. You can find extension owners in each extension's README. ## Using Extensions -When deciding how to model data in STAC it is highly recommended to first look at the [list of -extensions](https://stac-extensions.github.io/) and re-use fields there instead of creating your own version. This -increases interoperability, as users know that the meaning of your fields is the same as in other STAC +When deciding how to model data in STAC it is highly recommended to first look at the +[list of extensions](https://stac-extensions.github.io/) and re-use fields there instead of creating your own version. +This increases interoperability, as users know that the meaning of your fields is the same as in other STAC implementations. Many clients will also understand more mature extensions for better display and querying. -To incorporate an extension in STAC the 'extension ID' of the extension must be added to the `stac_extensions` +To incorporate an extension in STAC the 'Identifier' of the extension must be added to the `stac_extensions` array of the STAC [Catalog](../catalog-spec/catalog-spec.md#stac_extensions), [Collection](../collection-spec/collection-spec.md#stac_extensions) or [Item](../item-spec/item-spec.md#stac_extensions) -object. This identifier is a link to the JSON Schema URL that validates the fields in the extension, so STAC validators -can fetch the Schema to validate that the STAC object properly follows the extension. These JSON Schema URLs also act as -identifiers for specific version of the extension that the STAC object implements. The extension ID can be -found listed as the 'identifier' in the second line of the README of any extension made with the [extension -template](https://github.com/stac-extensions/template), and new ones get published automatically with any release made -with the template. - -### Extension IDs in `stac_extensions` - -The logic for when an object should list an extension ID in its `stac_extension` array is as follows: - -- If the object directly implements the extension (by following the specified requirements - usually by including -fields, but occasionally implementing alternate behaviors), the `stac_extensions` of that object should contain the extension ID. -- If an Asset implements fields of the extension, then `stac_extensions` of the Item or Collection which holds that - Asset should contain the extension ID. +object. This identifier is a URL to the JSON Schema that allows to validate the fields in the extension. +These JSON Schema URLs also include the version number of the extension. The 'Identifier' can usually be +found in the first lines of the README of any extension made with the +[extension template](https://github.com/stac-extensions/template). + +### Extension identifiers in `stac_extensions` + +Generally, if an extension is implemented in a STAC file in a place where the extension scope applies to, +the extension identifier should be added to the `stac_extension` array. The scope of an extension is usually +explained in the README of an extension. Implementing an extension by following the specified requirements usually means including +fields, but occasionally also means implementing alternate behaviors. + +There is no direct inheritance between children and parents though, so if for example an Item implements an extension, +but the Collection doesn't reflect the usage of the extension, the extension identifier must only be added to the +`stac_extension` array in the Item, but not to the Collection. If the Collection itself implements the extension though +or 'summarizies' a field in Collection Summaries or Item Asset Definitions, the extension identifier should be added to the +Collection. + +**Examples** + +- If the Catalog, Collection or Item object directly implements the extension, + the `stac_extensions` of that object should contain the extension Identifier. +- If an Asset object implements an extension, the `stac_extensions` of the Item or Collection which holds that + Asset should contain the extension identifier. - If a Collection [summary](../collection-spec/collection-spec.md#summaries) contains Item fields that implement an extension, then - the `stac_extensions` array of that Collection should list the extension ID. For example, if a Collection `summaries` field + the `stac_extensions` array of that Collection should list the extension identifier. For example, if a Collection `summaries` field contains a summary of `eo:bands`, then that Collection should have the EO extension JSON Schema URL in the `stac_extensions` array. - If an object implements an extension that results in fields from a separate extension to be referenced, then the latter extension - ID should be included in the `stac_extensions` array for that object. For example, if a Collection implements the + identifier should be included in the `stac_extensions` array for that object. For example, if a Collection implements the [item_assets](https://github.com/stac-extensions/item-assets) extension, and in the `item_assets` field there is an Asset Definition - which includes `eo:bands`, then the EO extension ID should be listed in that Collection's `stac_extensions`. - -## Stable STAC Extensions - -These extensions are considered stable and are widely used in many production implementations. As additional extensions advance -through the [Extension Maturity](#extension-maturity) classification they, will be added here. - -| Extension Title | Description | -|-----------------------------------------------------------------------|--------------------------------| -| [Electro-Optical](https://github.com/stac-extensions/eo/) | Covers electro-optical data that represents a snapshot of the Earth for a single date and time. It could consist of multiple spectral bands, for example visible bands, infrared bands, red edge bands and panchromatic bands. The extension provides common fields like bands, cloud cover, gsd and more. | -| [Projection](https://github.com/stac-extensions/projection/) | Provides a way to describe Items whose assets are in a geospatial projection. | -| [Scientific Citation](https://github.com/stac-extensions/scientific/) | Metadata that indicate from which publication data originates and how the data itself should be cited or referenced. | -| [View Geometry](https://github.com/stac-extensions/view/) | View Geometry adds metadata related to angles of sensors and other radiance angles that affect the view of resulting data | + which includes `eo:bands`, then the EO extension identifier should be listed in that Collection's `stac_extensions`. ## Community Extensions -There are many more extensions that are part of the broader STAC ecosystem. The center of activity for these is the -[stac-extensions GitHub organization](https://github.com/stac-extensions), which has a number of extension repositories. For -an overview of all extensions with their [Extension Maturity](#extension-maturity) classification see the -[STAC extensions overview page](https://stac-extensions.github.io/). +Everyone is welcome to contribute extensions to the STAC ecosystem. The center of activity for these is the +[stac-extensions GitHub organization](https://github.com/stac-extensions), which has a number of extension repositories. +Some of these, especially the [stable extensions](#extension-maturity), are observed by the STAC PSC. +The community can also host STAC extensions in other places, but we encourage the community to +at least list them in the [STAC extensions overview page](https://stac-extensions.github.io/) so that +everyone can be aware of all extensions at any time and a high level of interoperability is possible. ### Proposed extensions @@ -96,18 +95,37 @@ These are ideas that others would likely use and potentially collaborate on. Any ideas there, and see the section below on [proposing new extensions](#proposing-new-extensions) for the workflow to advance ideas into full-fledged community extensions. +## Extension Maturity + +There are many extensions being built with STAC, but they have varying degrees of maturity. All community extensions +listed here included must include a maturity classification, so that STAC spec users can easily get a sense of how +much they can count on the extension. + +| Maturity Classification | Min Impl # | Description | Stability | +| ----------------------- | ----------- | ----------- | --------- | +| Proposal | 0 | An idea put forward by a community member to gather feedback | Not stable - breaking changes almost guaranteed as implementers try out the idea. | +| Pilot | 1 | Idea is fleshed out, with examples and a JSON schema, and implemented in one or more catalogs. Additional implementations encouraged to help give feedback | Approaching stability - breaking changes are not anticipated but can easily come from additional feedback. | +| Candidate | 3 | A number of implementers are using it and are standing behind it as a solid extension. User can generally count on an extension at this maturity level. | Mostly stable, breaking changes require a new version and minor changes are unlikely. The extension has a code owner, designated in its README. | +| Stable | 6 | Highest current level of maturity. The community of extension maintainers commits to a STAC review process for any changes, which are not made lightly. | Completely stable, all changes require a new version number and review process. | +| Deprecated | N/A | A previous extension that has likely been superseded by a newer one or did not work out for some reason. | DO NOT USE, is not supported | + +Maturity mostly comes through diverse implementations, so the minimum number of implementations +column is the main gating function for an extension to mature. But extension authors can also +choose to hold back the maturity advancement if they don't feel they are yet ready to commit to +the less breaking changes of the next level. + ## Extending STAC -Anyone is welcome to create an extension. There are several types of extensions, some just add additional fields, +Anyone is welcome to extend STAC and evolve the additions into a full STAC extension with a README, JSON Schema and examples. +There are several types of extensions, some just add additional fields, some change the behavior of STAC and some introduce completely new functionality. New extensions should try to align with existing extensions as well as possible and may even re-use fields and their definitions until they may get split into a new extension that combines commonly used fields across multiple extensions. -Best practices for extension proposals are still emerging in this section. ### General Conventions Creating a new extension usually involves defining a set of logically grouped fields, and specifying what the allowed values -for those fields are. This should be done in the extension text and in JSON Schema, to provide validation. While one +for those fields are. This should be done in the extension text (README) and in JSON Schema, to provide validation. While one can theoretically add fields anywhere in JSON there are some conventions as to where to add them in STAC objects. 1. Additional attributes relating to an [Item](../item-spec/item-spec.md) should be added into the Item Properties object, @@ -116,8 +134,9 @@ can theoretically add fields anywhere in JSON there are some conventions as to w For example, the `eo:bands` attribute may be used in Item Properties to describe the aggregation of all bands available in the Item Asset objects contained in the Item, but may also be used in an individual Item Asset to describe only the bands available in that asset. 3. Additional attributes relating to a [Catalog](../catalog-spec/catalog-spec.md) or - [Collection](../collection-spec/collection-spec.md) should be added to the root of the object. -4. Extensions may also extend other extensions, declaring that dependency in the text and JSON Schema. + [Collection](../collection-spec/collection-spec.md) should be added to the top-level of the object. +4. All other objects can generally also be extended, e.g. Link Objects, Provider Objects, Band Objects, etc. +5. Extensions may also extend other extensions, declaring that dependency in the text and JSON Schema. ### Proposing new extensions @@ -126,38 +145,16 @@ Extensions can be hosted anywhere, but should use the 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 -transfer it to the stac-extensions org later. +transfer it to the stac-extensions organization later. For new extensions that require community discussion, we recommend the following workflow: - Use the stac-extensions template to sketch out your proposed extension - Open an issue on this repository with the prefix "New Extension: " and describe the extension. Include a link to the extension repository. -- Discussion can occur on that issue, or discussion can move to issues/pull requests on the extension repository directly. + Also post it in the Gitter chat for broader recognition. +- Discussion should take place as issues/pull requests on the extension repository directly, but can als occur on the issue created before. - Once the extension has an initial release, the issue on stac-spec will be closed. -### Extension Maturity - -There are many extensions being built with STAC, but they have varying degrees of maturity. All community extensions -listed here included must include a maturity classification, so that STAC spec users can easily get a sense of how -much they can count on the extension. Extension creators are encouraged to list their extensions here, even if it is just -an rough proposal, so others can potentially collaborate. - -| Maturity Classification | Min Impl # | Description | Stability | -| ----------------------- | ----------- | ----------- | --------- | -| Proposal | 0 | An idea put forward by a community member to gather feedback | Not stable - breaking changes almost guaranteed as implementers try out the idea. | -| Pilot | 1 | Idea is fleshed out, with examples and a JSON schema, and implemented in one or more catalogs. Additional implementations encouraged to help give feedback | Approaching stability - breaking changes are not anticipated but can easily come from additional feedback | -| Candidate | 3 | A number of implementers are using it and are standing behind it as a solid extension. Can generally count on an extension at this maturity level | Mostly stable, breaking changes require a new version and minor changes are unlikely. The extension has a code owner, designated in its README. | -| Stable | 6 | Highest current level of maturity. The community of extension maintainers commits to a STAC review process for any changes, which are not made lightly. | Completely stable, all changes require a new version number and review process. | -| Deprecated | N/A | A previous extension that has likely been superseded by a newer one or did not work out for some reason. | DO NOT USE, is not supported | - -Maturity mostly comes through diverse implementations, so the minimum number of implementations -column is the main gating function for an extension to mature. But extension authors can also -choose to hold back the maturity advancement if they don't feel they are yet ready to commit to -the less breaking changes of the next level. - -A 'mature' classification level will likely be added once there are extensions that have been -stable for over a year and are used in twenty or more implementations. - ### Prefixes A STAC Item can combine schema information from several different sources - the core STAC Item information, From d65aeced9a71ca08e4ce8125e840bd81ff6d4889 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Mon, 30 Jan 2023 21:29:10 +0100 Subject: [PATCH 15/25] Clarify the text around timestamps a bit. (#1207) --- item-spec/common-metadata.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/item-spec/common-metadata.md b/item-spec/common-metadata.md index b9596c46e..1eed6ff9a 100644 --- a/item-spec/common-metadata.md +++ b/item-spec/common-metadata.md @@ -49,11 +49,12 @@ Fields to provide additional temporal information such as ranges with a start an All timestamps MUST be formatted according to [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6). **created** and **updated** have different meaning depending on where they are used. -If those fields are available in the Item `properties`, they identify the creation and update times of the metadata. -Having those fields in the Item `assets` refers to the creation and update times of the actual data linked to in the Asset Object. +If those fields are available in a Collection, in a Catalog (both top-level), or in a Item (in the `properties`), +the fields refer the metadata (e.g., when the STAC metadata was created). +Having those fields in the Assets or Links, they refer to the actual data linked to (e.g., when the asset was created). -*NOTE: There are more date and time related fields available in the [Timestamps -extension](https://github.com/stac-extensions/timestamps), which is not an official extension*. +***NOTE:** There are more date and time related fields available in the +[Timestamps extension](https://github.com/stac-extensions/timestamps)*. ### Date and Time Range From 455427e43fa8392a9a49d5d22a9f67666ede7de8 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Tue, 31 Jan 2023 15:51:59 +0100 Subject: [PATCH 16/25] Clarified that trailing slashes in URIs are significant. (#1214) --- CHANGELOG.md | 4 ++++ best-practices.md | 15 ++++++++++++++- catalog-spec/catalog-spec.md | 2 +- collection-spec/collection-spec.md | 2 +- item-spec/item-spec.md | 4 ++-- 5 files changed, 22 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1d3af6a21..218f7fa5d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,10 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. - "Strongly recommended" language around `self` links in the item spec. ([#1173](https://github.com/radiantearth/stac-spec/pull/1173)) +### Changed + +- Clarified that trailing slashes in URIs are significant. ([#1212](https://github.com/radiantearth/stac-spec/discussions/1212)) + ## [v1.0.0] - 2021-05-25 ### Added diff --git a/best-practices.md b/best-practices.md index 79105313d..8dad01ea5 100644 --- a/best-practices.md +++ b/best-practices.md @@ -8,6 +8,7 @@ - [Schema.org, JSON-LD, DCAT, microformats, etc](#schemaorg-json-ld-dcat-microformats-etc) - [Deploying STAC Browser](#deploying-stac-browser) - [Requester Pays](#requester-pays) + - [Consistent URIs](#consistent-uris) - **[Item Best Practices](#item-practices)** - [Field and ID formatting](#item-ids) - [Searchable Identifiers](#searchable-identifiers) @@ -146,6 +147,18 @@ For data providers using STAC with requester pays buckets, there are two main re 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. +### Consistent URIs + +Links in STAC can be [absolute or relative](#use-of-links). +Relative links must be resolved against the absolute URI given in the link with the relation type `self` (or in some cases `root`). +To resolve relative URIs the base URIs must be precise and consistent: Having or not having a trailing slash is significant. +Without it, the last path component is considered to be a "file" name to be removed to get at the "directory" that is used as the base. +API endpoints usually behave like directories. + +**Examples:** +- is good and is problematic as catalog.json is a specific file +- is good and is problematic as `api` should not be removed when resolving URIs. + ## Item Practices ### Item IDs @@ -633,7 +646,7 @@ multiple sources to achieve this. So if you are writing a STAC client it is recommended to start with just supporting these two types of published catalogs. In turn, if your data is published online publicly or for use on an intranet then following these recommendations will ensure -that a wider range of clients will work with it. +that a wider range of clients will work with it. ### Using Relation Types diff --git a/catalog-spec/catalog-spec.md b/catalog-spec/catalog-spec.md index 8b26dce02..3b6ef0046 100644 --- a/catalog-spec/catalog-spec.md +++ b/catalog-spec/catalog-spec.md @@ -73,7 +73,7 @@ with links. | Field Name | Type | Description | | ---------- | ------ | ----------- | -| href | string | **REQUIRED.** The actual link in the format of an URL. Relative and absolute links are both allowed. | +| href | string | **REQUIRED.** The actual link in the format of an URL. Relative and absolute links are both allowed. [Trailing slashes are significant.](../best-practices.md#consistent-uris) | | rel | string | **REQUIRED.** Relationship between the current document and the linked document. See chapter ["Relation types"](#relation-types) for more information. | | type | string | [Media type](#media-types) of the referenced entity. | | title | string | A human readable title to be used in rendered displays of the link. | diff --git a/collection-spec/collection-spec.md b/collection-spec/collection-spec.md index 6d621c633..6dec8ab97 100644 --- a/collection-spec/collection-spec.md +++ b/collection-spec/collection-spec.md @@ -242,7 +242,7 @@ This object describes a relationship with another entity. Data providers are adv | Field Name | Type | Description | | ---------- | ------ | ------------------------------------------------------------ | -| href | string | **REQUIRED.** The actual link in the format of an URL. Relative and absolute links are both allowed. | +| href | string | **REQUIRED.** The actual link in the format of an URL. Relative and absolute links are both allowed. [Trailing slashes are significant.](../best-practices.md#consistent-uris) | | rel | string | **REQUIRED.** Relationship between the current document and the linked document. See chapter "[Relation types](#relation-types)" for more information. | | type | string | [Media type](../catalog-spec/catalog-spec.md#media-types) of the referenced entity. | | title | string | A human readable title to be used in rendered displays of the link. | diff --git a/item-spec/item-spec.md b/item-spec/item-spec.md index 64b6f5c4c..b44adc7db 100644 --- a/item-spec/item-spec.md +++ b/item-spec/item-spec.md @@ -173,7 +173,7 @@ It is allowed to add additional fields such as a `title` and `type`. | Field Name | Type | Description | | ---------- | ------ | ----------- | -| href | string | **REQUIRED.** The actual link in the format of an URL. Relative and absolute links are both allowed. | +| href | string | **REQUIRED.** The actual link in the format of an URL. Relative and absolute links are both allowed. [Trailing slashes are significant.](../best-practices.md#consistent-uris) | | rel | string | **REQUIRED.** Relationship between the current document and the linked document. See chapter "Relation types" for more information. | | type | string | [Media type](../catalog-spec/catalog-spec.md#media-types) of the referenced entity. | | title | string | A human readable title to be used in rendered displays of the link. | @@ -234,7 +234,7 @@ or streamed. It is allowed to add additional fields. | Field Name | Type | Description | | ----------- | --------- | ----------- | -| href | string | **REQUIRED.** URI to the asset object. Relative and absolute URI are both allowed. | +| href | string | **REQUIRED.** URI to the asset object. Relative and absolute URI are both allowed. [Trailing slashes are significant.](../best-practices.md#consistent-uris) | | title | string | The displayed title for clients and users. | | description | string | A description of the Asset providing additional details, such as how it was processed or created. [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for rich text representation. | | type | string | [Media type](#asset-media-type) of the asset. See the [common media types](../best-practices.md#common-media-types-in-stac) in the best practice doc for commonly used asset types. | From a9aacbc2836b714af705bea4fc808770bd37e12f Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Wed, 1 Feb 2023 14:52:24 +0100 Subject: [PATCH 17/25] Clarified that collection IDs should be unique across all collections in the corresponding root catalog. (#1209) --- CHANGELOG.md | 4 ++++ collection-spec/collection-spec.md | 8 ++++---- 2 files changed, 8 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 218f7fa5d..1a2a026db 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,6 +15,10 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. - Clarified that trailing slashes in URIs are significant. ([#1212](https://github.com/radiantearth/stac-spec/discussions/1212)) +### Fixed + +- Clarified that collection IDs should be unique across all collections in the corresponding root catalog. + ## [v1.0.0] - 2021-05-25 ### Added diff --git a/collection-spec/collection-spec.md b/collection-spec/collection-spec.md index 6dec8ab97..8bec50096 100644 --- a/collection-spec/collection-spec.md +++ b/collection-spec/collection-spec.md @@ -48,7 +48,7 @@ specified in [*OGC API - Features*](https://ogcapi.ogc.org/features/), but they | type | string | **REQUIRED.** Must be set to `Collection` to be a valid Collection. | | stac_version | string | **REQUIRED.** The STAC version the Collection implements. | | stac_extensions | \[string] | A list of extension identifiers the Collection implements. | -| id | string | **REQUIRED.** Identifier for the Collection that is unique across the provider. | +| id | string | **REQUIRED.** Identifier for the Collection that is unique across all collections in the root catalog. | | title | string | A short descriptive one-line title for the Collection. | | description | string | **REQUIRED.** Detailed multi-line description to fully explain the Collection. [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for rich text representation. | | keywords | \[string] | List of keywords describing the Collection. | @@ -75,9 +75,9 @@ This must **not** declare the extensions that are only implemented in child Coll #### id -It is important that Collection identifiers are unique across the provider. And providers should strive as much as possible to make -their Collection ids 'globally' unique, prefixing any common information with a unique string. This could be the provider's name if -it is a fairly unique name, or their name combined with the domain they operate in. +It is important that Collection identifiers are unique across all collections in the corresponding root catalog. +Providers should strive as much as possible to make their Collection ids 'globally' unique, prefixing any common information with a unique string. +This could be the provider's name if it is a fairly unique name, or their name combined with the domain they operate in. #### license From c9fdaaa3dd3458a2b795f05a9c8cd76cd118c557 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Tue, 21 Feb 2023 15:54:08 +0100 Subject: [PATCH 18/25] Fix media type in example --- examples/core-item.json | 2 +- examples/extended-item.json | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/examples/core-item.json b/examples/core-item.json index d07cc8df6..360f4638c 100644 --- a/examples/core-item.json +++ b/examples/core-item.json @@ -107,7 +107,7 @@ "udm": { "href": "https://storage.googleapis.com/open-cogs/stac-examples/20201211_223832_CS2_analytic_udm.tif", "title": "Unusable Data Mask", - "type": "image/tiff; application=geotiff;" + "type": "image/tiff; application=geotiff" }, "json-metadata": { "href": "http://remotedata.io/catalog/20201211_223832_CS2/extended-metadata.json", diff --git a/examples/extended-item.json b/examples/extended-item.json index 59f2de1f3..107313f09 100644 --- a/examples/extended-item.json +++ b/examples/extended-item.json @@ -181,7 +181,7 @@ "udm": { "href": "https://storage.googleapis.com/open-cogs/stac-examples/20201211_223832_CS2_analytic_udm.tif", "title": "Unusable Data Mask", - "type": "image/tiff; application=geotiff;" + "type": "image/tiff; application=geotiff" }, "json-metadata": { "href": "http://remotedata.io/catalog/20201211_223832_CS2/extended-metadata.json", From 86b94034937fba739595be1f729556baae9946b8 Mon Sep 17 00:00:00 2001 From: Matthias Mohr Date: Thu, 13 Apr 2023 11:43:25 +0200 Subject: [PATCH 19/25] Re-uses and validates common metadata everywhere #1199 #1187 (#1208) --- CHANGELOG.md | 10 ++- catalog-spec/json-schema/catalog.json | 47 ++--------- collection-spec/json-schema/collection.json | 91 ++------------------ item-spec/common-metadata.md | 2 - item-spec/json-schema/basics.json | 11 +-- item-spec/json-schema/common.json | 24 ++++++ item-spec/json-schema/datetime.json | 6 +- item-spec/json-schema/item.json | 93 ++++++++++----------- 8 files changed, 94 insertions(+), 190 deletions(-) create mode 100644 item-spec/json-schema/common.json diff --git a/CHANGELOG.md b/CHANGELOG.md index 1a2a026db..799516c70 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,13 +7,19 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. ## [Unreleased] +### Changed + +- Validate common metadata also in Catalogs, Collections and Links. +- Common metadata: If a description is given, require that it is not empty +- Clarified that trailing slashes in URIs are significant. ([#1212](https://github.com/radiantearth/stac-spec/discussions/1212)) + ### Removed - "Strongly recommended" language around `self` links in the item spec. ([#1173](https://github.com/radiantearth/stac-spec/pull/1173)) -### Changed +### Fixed -- Clarified that trailing slashes in URIs are significant. ([#1212](https://github.com/radiantearth/stac-spec/discussions/1212)) +- Several typos and minor language changes ### Fixed diff --git a/catalog-spec/json-schema/catalog.json b/catalog-spec/json-schema/catalog.json index 31b2c8f8a..65bbebd10 100644 --- a/catalog-spec/json-schema/catalog.json +++ b/catalog-spec/json-schema/catalog.json @@ -6,12 +6,16 @@ "allOf": [ { "$ref": "#/definitions/catalog" + }, + { + "$ref": "../../item-spec/json-schema/common.json#" } ], "definitions": { "catalog": { "title": "STAC Catalog", "type": "object", + "$comment": "title and description is validated through the common metadata.", "required": [ "stac_version", "type", @@ -44,49 +48,8 @@ "type": "string", "minLength": 1 }, - "title": { - "title": "Title", - "type": "string" - }, - "description": { - "title": "Description", - "type": "string", - "minLength": 1 - }, "links": { - "title": "Links", - "type": "array", - "items": { - "$ref": "#/definitions/link" - } - } - } - }, - "link": { - "type": "object", - "required": [ - "rel", - "href" - ], - "properties": { - "href": { - "title": "Link reference", - "type": "string", - "format": "iri-reference", - "minLength": 1 - }, - "rel": { - "title": "Link relation type", - "type": "string", - "minLength": 1 - }, - "type": { - "title": "Link type", - "type": "string" - }, - "title": { - "title": "Link title", - "type": "string" + "$ref": "../../item-spec/json-schema/item.json#/definitions/links" } } } diff --git a/collection-spec/json-schema/collection.json b/collection-spec/json-schema/collection.json index 2ad20902d..d13301106 100644 --- a/collection-spec/json-schema/collection.json +++ b/collection-spec/json-schema/collection.json @@ -6,13 +6,17 @@ "allOf": [ { "$ref": "#/definitions/collection" + }, + { + "$ref": "../../item-spec/json-schema/common.json#" } ], "definitions": { "collection": { "title": "STAC Collection", - "description": "These are the fields specific to a STAC Collection. All other fields are inherited from STAC Catalog.", + "description": "These are the fields specific to a STAC Collection.", "type": "object", + "$comment": "title, description, providers and license is validated through the common metadata.", "required": [ "stac_version", "type", @@ -47,15 +51,6 @@ "type": "string", "minLength": 1 }, - "title": { - "title": "Title", - "type": "string" - }, - "description": { - "title": "Description", - "type": "string", - "minLength": 1 - }, "keywords": { "title": "Keywords", "type": "array", @@ -63,48 +58,6 @@ "type": "string" } }, - "license": { - "title": "Collection License Name", - "type": "string", - "pattern": "^[\\w\\-\\.\\+]+$" - }, - "providers": { - "type": "array", - "items": { - "type": "object", - "required": [ - "name" - ], - "properties": { - "name": { - "title": "Organization name", - "type": "string" - }, - "description": { - "title": "Organization description", - "type": "string" - }, - "roles": { - "title": "Organization roles", - "type": "array", - "items": { - "type": "string", - "enum": [ - "producer", - "licensor", - "processor", - "host" - ] - } - }, - "url": { - "title": "Organization homepage", - "type": "string", - "format": "iri" - } - } - } - }, "extent": { "title": "Extents", "type": "object", @@ -178,45 +131,13 @@ "$ref": "../../item-spec/json-schema/item.json#/definitions/assets" }, "links": { - "title": "Links", - "type": "array", - "items": { - "$ref": "#/definitions/link" - } + "$ref": "../../item-spec/json-schema/item.json#/definitions/links" }, "summaries": { "$ref": "#/definitions/summaries" } } }, - "link": { - "type": "object", - "required": [ - "rel", - "href" - ], - "properties": { - "href": { - "title": "Link reference", - "type": "string", - "format": "iri-reference", - "minLength": 1 - }, - "rel": { - "title": "Link relation type", - "type": "string", - "minLength": 1 - }, - "type": { - "title": "Link type", - "type": "string" - }, - "title": { - "title": "Link title", - "type": "string" - } - } - }, "summaries": { "type": "object", "additionalProperties": { diff --git a/item-spec/common-metadata.md b/item-spec/common-metadata.md index 1eed6ff9a..e2dcf86b2 100644 --- a/item-spec/common-metadata.md +++ b/item-spec/common-metadata.md @@ -18,8 +18,6 @@ or [Collection Asset](../collection-spec/collection-spec.md#asset-object). Various *examples* are available in the folder [`examples`](../examples/). *JSON Schemas* can be found in the folder [`json-schema`](json-schema/). -By default, these fields are only included and validated against in the core [Item schema](json-schema/item.json). - Implementation of any of the fields is not required, unless explicitly required by a specification using the field. For example, `datetime` is required in STAC Items. diff --git a/item-spec/json-schema/basics.json b/item-spec/json-schema/basics.json index 68e8f37ae..dc0b4a9d0 100644 --- a/item-spec/json-schema/basics.json +++ b/item-spec/json-schema/basics.json @@ -5,14 +5,15 @@ "type": "object", "properties": { "title": { - "title": "Item Title", - "description": "A human-readable title describing the Item.", + "title": "Title", + "description": "A human-readable title describing the entity.", "type": "string" }, "description": { - "title": "Item Description", - "description": "Detailed multi-line description to fully explain the Item.", - "type": "string" + "title": "Description", + "description": "Detailed multi-line description to fully explain the entity.", + "type": "string", + "minLength": 1 } } } \ No newline at end of file diff --git a/item-spec/json-schema/common.json b/item-spec/json-schema/common.json new file mode 100644 index 000000000..27e6d27dc --- /dev/null +++ b/item-spec/json-schema/common.json @@ -0,0 +1,24 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "https://schemas.stacspec.org/v1.0.0/item-spec/json-schema/commonjson#", + "title": "STAC Common Metadata", + "type": "object", + "description": "This schema includes all common metadata fields.", + "allOf": [ + { + "$ref": "basics.json" + }, + { + "$ref": "datetime.json" + }, + { + "$ref": "instrument.json" + }, + { + "$ref": "licensing.json" + }, + { + "$ref": "provider.json" + } + ] +} diff --git a/item-spec/json-schema/datetime.json b/item-spec/json-schema/datetime.json index 4c7a3a143..91868c967 100644 --- a/item-spec/json-schema/datetime.json +++ b/item-spec/json-schema/datetime.json @@ -18,21 +18,21 @@ "properties": { "datetime": { "title": "Date and Time", - "description": "The searchable date/time of the assets, in UTC (Formatted in RFC 3339) ", + "description": "The searchable date/time of the data, in UTC (Formatted in RFC 3339) ", "type": ["string", "null"], "format": "date-time", "pattern": "(\\+00:00|Z)$" }, "start_datetime": { "title": "Start Date and Time", - "description": "The searchable start date/time of the assets, in UTC (Formatted in RFC 3339) ", + "description": "The searchable start date/time of the data, in UTC (Formatted in RFC 3339) ", "type": "string", "format": "date-time", "pattern": "(\\+00:00|Z)$" }, "end_datetime": { "title": "End Date and Time", - "description": "The searchable end date/time of the assets, in UTC (Formatted in RFC 3339) ", + "description": "The searchable end date/time of the data, in UTC (Formatted in RFC 3339) ", "type": "string", "format": "date-time", "pattern": "(\\+00:00|Z)$" diff --git a/item-spec/json-schema/item.json b/item-spec/json-schema/item.json index 8d4286783..e6ada61d8 100644 --- a/item-spec/json-schema/item.json +++ b/item-spec/json-schema/item.json @@ -10,25 +10,6 @@ } ], "definitions": { - "common_metadata": { - "allOf": [ - { - "$ref": "basics.json" - }, - { - "$ref": "datetime.json" - }, - { - "$ref": "instrument.json" - }, - { - "$ref": "licensing.json" - }, - { - "$ref": "provider.json" - } - ] - }, "core": { "allOf": [ { @@ -112,12 +93,7 @@ "minLength": 1 }, "links": { - "title": "Item links", - "description": "Links to item relations", - "type": "array", - "items": { - "$ref": "#/definitions/link" - } + "$ref": "#/definitions/links" }, "assets": { "$ref": "#/definitions/assets" @@ -125,7 +101,7 @@ "properties": { "allOf": [ { - "$ref": "#/definitions/common_metadata" + "$ref": "common.json" }, { "anyOf": [ @@ -192,33 +168,48 @@ } ] }, + "links": { + "title": "Item links", + "description": "Links to item relations", + "type": "array", + "items": { + "$ref": "#/definitions/link" + } + }, "link": { - "type": "object", - "required": [ - "rel", - "href" - ], - "properties": { - "href": { - "title": "Link reference", - "type": "string", - "format": "iri-reference", - "minLength": 1 - }, - "rel": { - "title": "Link relation type", - "type": "string", - "minLength": 1 - }, - "type": { - "title": "Link type", - "type": "string" + "allOf": [ + { + "type": "object", + "required": [ + "rel", + "href" + ], + "properties": { + "href": { + "title": "Link reference", + "type": "string", + "format": "iri-reference", + "minLength": 1 + }, + "rel": { + "title": "Link relation type", + "type": "string", + "minLength": 1 + }, + "type": { + "title": "Link type", + "type": "string" + }, + "title": { + "title": "Link title", + "type": "string" + } + } }, - "title": { - "title": "Link title", - "type": "string" + { + "$ref": "common.json" } - } + ] }, "assets": { "title": "Asset links", @@ -264,7 +255,7 @@ } }, { - "$ref": "#/definitions/common_metadata" + "$ref": "common.json" } ] } From 25d56b0f8c32e6dea2275021a6c10ca0d8899112 Mon Sep 17 00:00:00 2001 From: Emmanuel Mathot Date: Tue, 6 Jun 2023 21:15:15 +0200 Subject: [PATCH 20/25] Keywords in common metadata (#1227) * Keywords in common metadata * Added keywords in simple example * Minor alignment and clarification --------- Co-authored-by: Matthias Mohr --- CHANGELOG.md | 4 ++++ collection-spec/json-schema/collection.json | 9 +-------- examples/collection.json | 5 +++++ examples/extended-item.json | 5 +++++ item-spec/common-metadata.md | 9 +++++---- item-spec/json-schema/basics.json | 8 ++++++++ 6 files changed, 28 insertions(+), 12 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 799516c70..99574afd7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. ## [Unreleased] +### Added + +- The `keywords` field known from Collections is available in common metadata. ([#1187](https://github.com/radiantearth/stac-spec/issues/1187)) + ### Changed - Validate common metadata also in Catalogs, Collections and Links. diff --git a/collection-spec/json-schema/collection.json b/collection-spec/json-schema/collection.json index d13301106..952d96fe3 100644 --- a/collection-spec/json-schema/collection.json +++ b/collection-spec/json-schema/collection.json @@ -16,7 +16,7 @@ "title": "STAC Collection", "description": "These are the fields specific to a STAC Collection.", "type": "object", - "$comment": "title, description, providers and license is validated through the common metadata.", + "$comment": "title, description, keywords, providers and license is validated through the common metadata.", "required": [ "stac_version", "type", @@ -51,13 +51,6 @@ "type": "string", "minLength": 1 }, - "keywords": { - "title": "Keywords", - "type": "array", - "items": { - "type": "string" - } - }, "extent": { "title": "Extents", "type": "object", diff --git a/examples/collection.json b/examples/collection.json index 6a60a4b04..dd9dc3a1b 100644 --- a/examples/collection.json +++ b/examples/collection.json @@ -9,6 +9,11 @@ "stac_version": "1.0.0", "description": "A simple collection demonstrating core catalog fields with links to a couple of items", "title": "Simple Example Collection", + "keywords": [ + "simple", + "example", + "collection" + ], "providers": [ { "name": "Remote Data, Inc", diff --git a/examples/extended-item.json b/examples/extended-item.json index 59f2de1f3..bc79efe1f 100644 --- a/examples/extended-item.json +++ b/examples/extended-item.json @@ -45,6 +45,11 @@ "properties": { "title": "Extended Item", "description": "A sample STAC Item that includes a variety of examples from the stable extensions", + "keywords": [ + "extended", + "example", + "item" + ], "datetime": "2020-12-14T18:02:31.437000Z", "created": "2020-12-15T01:48:13.725Z", "updated": "2020-12-15T01:48:13.725Z", diff --git a/item-spec/common-metadata.md b/item-spec/common-metadata.md index e2dcf86b2..1d47d89ca 100644 --- a/item-spec/common-metadata.md +++ b/item-spec/common-metadata.md @@ -27,10 +27,11 @@ Descriptive fields to give a basic overview of a STAC Item. - [JSON Schema](json-schema/basics.json) -| Field Name | Type | Description | -| ----------- | ------ | ------------------------------------------------------------ | -| title | string | A human readable title describing the Item. | -| description | string | Detailed multi-line description to fully explain the Item. [CommonMark 0.29](https://commonmark.org/) syntax MAY be used for rich text representation. | +| Field Name | Type | Description | +| ----------- | --------- | ----------- | +| title | string | A human readable title describing the STAC entity. | +| description | string | Detailed multi-line description to fully explain the STAC entity. [CommonMark 0.29](https://commonmark.org/) syntax MAY be used for rich text representation. | +| keywords | \[string] | List of keywords describing the STAC entity. | ## Date and Time diff --git a/item-spec/json-schema/basics.json b/item-spec/json-schema/basics.json index dc0b4a9d0..7d3d3f116 100644 --- a/item-spec/json-schema/basics.json +++ b/item-spec/json-schema/basics.json @@ -14,6 +14,14 @@ "description": "Detailed multi-line description to fully explain the entity.", "type": "string", "minLength": 1 + }, + "keywords": { + "title": "Keywords", + "description": "List of keywords describing the entity.", + "type": "array", + "items": { + "type": "string" + } } } } \ No newline at end of file From 64331ccf308ef2317cb1cc93bc5c10262ba9f32b Mon Sep 17 00:00:00 2001 From: James Banting Date: Tue, 11 Jul 2023 09:08:16 -0700 Subject: [PATCH 21/25] Spelling corrections. See #1152 --- examples/collection-only/collection-with-schemas.json | 2 +- examples/extensions-collection/collection.json | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/examples/collection-only/collection-with-schemas.json b/examples/collection-only/collection-with-schemas.json index e0023e239..194331cd6 100644 --- a/examples/collection-only/collection-with-schemas.json +++ b/examples/collection-only/collection-with-schemas.json @@ -81,7 +81,7 @@ "instruments": { "type": "string", "const": "msi", - "title": "Multispectral Intrument", + "title": "Multispectral Instrument", "count": 6613431 }, "resto:landcover": { diff --git a/examples/extensions-collection/collection.json b/examples/extensions-collection/collection.json index bfbc3c1e5..54a60ba56 100644 --- a/examples/extensions-collection/collection.json +++ b/examples/extensions-collection/collection.json @@ -2,7 +2,7 @@ "id": "extensions-collection", "type": "Collection", "stac_version": "1.0.0", - "description": "A heterogenous collection containing deeper examples of various extensions", + "description": "A heterogeneous collection containing deeper examples of various extensions", "links": [ { "rel": "parent", From f386593b03c4a2531d031b989cd52e331d47ec30 Mon Sep 17 00:00:00 2001 From: Phil Varner Date: Tue, 26 Sep 2023 12:37:34 -0400 Subject: [PATCH 22/25] update ci node to 18 and format all files --- .circleci/config.yml | 6 +- .remarkignore | 4 +- best-practices.md | 74 ++++++++++++------------ catalog-spec/catalog-spec.md | 48 ++++++++-------- collection-spec/collection-spec.md | 88 ++++++++++++++--------------- extensions/README.md | 37 ++++++------ item-spec/common-metadata.md | 67 ++++++++++++---------- item-spec/item-spec.md | 78 ++++++++++++------------- package.json | 91 ++++++++++++++++++++++++++---- 9 files changed, 286 insertions(+), 207 deletions(-) diff --git a/.circleci/config.yml b/.circleci/config.yml index 60cd9efe6..5c87bc678 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -3,7 +3,7 @@ jobs: test_examples_node: working_directory: ~/stac docker: - - image: circleci/node:12 + - image: cimg/node:18.18.0 steps: - checkout - run: @@ -27,7 +27,7 @@ jobs: test_docs: working_directory: ~/stac docker: - - image: circleci/node:12 + - image: cimg/node:18.18.0 steps: - checkout - run: @@ -39,7 +39,7 @@ jobs: publish_schemas: working_directory: ~/stac docker: - - image: circleci/node:12 + - image: cimg/node:18.18.0 steps: - checkout - run: diff --git a/.remarkignore b/.remarkignore index 332776060..b056e3ce0 100644 --- a/.remarkignore +++ b/.remarkignore @@ -1 +1,3 @@ -/CODE_OF_CONDUCT.md \ No newline at end of file +/CODE_OF_CONDUCT.md +/CHANGELOG.md +.github/pull_request_template.md diff --git a/best-practices.md b/best-practices.md index 8dad01ea5..ca98cd230 100644 --- a/best-practices.md +++ b/best-practices.md @@ -305,20 +305,20 @@ The following table lists a number of commonly used media types in STAC. The fir yet, but reflect the community consensus direction. There are many IANA registered types that commonly show up in STAC. The following table lists some of the most common ones you may encounter or use. -| Media Type | Description | -| ------------------------------------------------------- | ------------------------------------------------------------ | -| `image/tiff; application=geotiff` | GeoTIFF with standardized georeferencing metadata | +| Media Type | Description | +| ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `image/tiff; application=geotiff` | GeoTIFF with standardized georeferencing metadata | | `image/tiff; application=geotiff; profile=cloud-optimized` | [Cloud Optimized GeoTIFF](https://www.cogeo.org/) (unofficial). Once there is an [official media type](http://osgeo-org.1560.x6.nabble.com/Media-type-tc5411498.html) it will be added and the custom media type here will be deprecated. | -| `image/jp2` | JPEG 2000 | -| `image/png` | Visual PNGs (e.g. thumbnails) | -| `image/jpeg` | Visual JPEGs (e.g. thumbnails, oblique) | -| `text/xml` or `application/xml` | XML metadata [RFC 7303](https://www.ietf.org/rfc/rfc7303.txt) | -| `application/json` | A JSON file (often metadata, or [labels](https://github.com/radiantearth/stac-spec/tree/master/extensions/label#labels-required)) | -| `text/plain` | Plain text (often metadata) | -| `application/geo+json` | [GeoJSON](https://geojson.org/) | -| `application/geopackage+sqlite3` | [GeoPackage](https://www.geopackage.org/) | -| `application/x-hdf5` | Hierarchical Data Format version 5 | -| `application/x-hdf` | Hierarchical Data Format versions 4 and earlier. | +| `image/jp2` | JPEG 2000 | +| `image/png` | Visual PNGs (e.g. thumbnails) | +| `image/jpeg` | Visual JPEGs (e.g. thumbnails, oblique) | +| `text/xml` or `application/xml` | XML metadata [RFC 7303](https://www.ietf.org/rfc/rfc7303.txt) | +| `application/json` | A JSON file (often metadata, or [labels](https://github.com/radiantearth/stac-spec/tree/master/extensions/label#labels-required)) | +| `text/plain` | Plain text (often metadata) | +| `application/geo+json` | [GeoJSON](https://geojson.org/) | +| `application/geopackage+sqlite3` | [GeoPackage](https://www.geopackage.org/) | +| `application/x-hdf5` | Hierarchical Data Format version 5 | +| `application/x-hdf` | Hierarchical Data Format versions 4 and earlier. | *Deprecation notice: GeoTiff previously used the media type `image/vnd.stac.geotiff` and Cloud Optimized GeoTiffs used `image/vnd.stac.geotiff; profile=cloud-optimized`. @@ -359,23 +359,23 @@ standardized. In time others on this list may migrate to a more 'official' list. doc, the listing is the table below. The ones from extensions are mostly just 'best practices' in the extensions, as there are few actual role requirements. -| Role Name | Source | Description | -| --------- | -------------|----------------------------------------------------------------------- | -| thumbnail | [Item Spec](item-spec/item-spec.md#asset-role-types) | An asset that represents a thumbnail of the item, typically a true color image (for items with assets in the visible wavelengths), lower-resolution (typically smaller 600x600 pixels), and typically a JPEG or PNG (suitable for display in a web browser). Multiple assets may have this purpose, but it recommended that the `type` and `roles` be unique tuples. For example, Sentinel-2 L2A provides thumbnail images in both JPEG and JPEG2000 formats, and would be distinguished by their media types. | -| data | [Item Spec](item-spec/item-spec.md#asset-role-types) | The data itself. This is a suggestion for a common role for data files to be used in case data providers don't come up with their own names and semantics. | -| metadata | [Item Spec](item-spec/item-spec.md#asset-role-types) | A metadata sidecar file describing the data in this item, for example the Landsat-8 MTL file. | -| overview | Best Practice | An asset that represents a possibly larger view than the thumbnail of the Item, for example, a true color composite of multi-band data. | -| visual | Best Practice | An asset that is a full resolution version of the data, processed for visual use (RGB only, often sharpened ([pan-sharpened](https://en.wikipedia.org/wiki/Pansharpened_image) and/or using an [unsharp mask](https://en.wikipedia.org/wiki/Unsharp_masking))). | -| date | Best Practice | An asset that provides per-pixel acquisition timestamps, typically serving as metadata to another asset | -| graphic | Best Practice | Supporting plot, illustration, or graph associated with the Item | -| data-mask | Best Practice | File indicating if corresponding pixels have Valid data and various types of invalid data | -| snow-ice | Best Practice | Points to a file that indicates whether a pixel is assessed as being snow/ice or not. | -| land-water | Best Practice | Points to a file that indicates whether a pixel is assessed as being land or water. | -| water-mask | Best Practice | Points to a file that indicates whether a pixel is assessed as being water (e.g. flooding map). | iso-19139 | Best Practice | Points to an [ISO 19139](https://www.iso.org/standard/67253.html) metadata xml file | -| iso-19115 | Best Practice | Points to an [ISO 19115](https://www.iso.org/standard/53798.html) metadata file | -| reflectance, temperature, saturation, cloud, cloud-shadow | [EO Extension](https://github.com/stac-extensions/eo/blob/main/README.md#best-practices) | See the [table](https://github.com/stac-extensions/eo/blob/main/README.md#best-practices) in EO for more information, and the definitive list of roles related to EO. | -| incidence-angle, azimuth, sun-azimuth, sun-elevation, terrain-shadow, terrain-occlusion, terrain-illumination | [View Extension](https://github.com/stac-extensions/view/blob/main/README.md#best-practices) | See the [table](https://github.com/stac-extensions/view/blob/main/README.md#best-practices) in View for more information, and the definitive list of roles related to viewing angles. | -| local-incidence-angle, noise-power, amplitude, magnitude, sigma0, beta0, gamma0, date-offset, covmat, prd | [SAR Extension](https://github.com/stac-extensions/sar/blob/main/README.md#best-practices) | See the [table](https://github.com/stac-extensions/sar/blob/main/README.md#best-practices) in SAR for more information. , and the definitive list of roles related to SAR. | +| Role Name | Source | Description | +| ------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| thumbnail | [Item Spec](item-spec/item-spec.md#asset-role-types) | An asset that represents a thumbnail of the item, typically a true color image (for items with assets in the visible wavelengths), lower-resolution (typically smaller 600x600 pixels), and typically a JPEG or PNG (suitable for display in a web browser). Multiple assets may have this purpose, but it recommended that the `type` and `roles` be unique tuples. For example, Sentinel-2 L2A provides thumbnail images in both JPEG and JPEG2000 formats, and would be distinguished by their media types. | +| data | [Item Spec](item-spec/item-spec.md#asset-role-types) | The data itself. This is a suggestion for a common role for data files to be used in case data providers don't come up with their own names and semantics. | +| metadata | [Item Spec](item-spec/item-spec.md#asset-role-types) | A metadata sidecar file describing the data in this item, for example the Landsat-8 MTL file. | +| overview | Best Practice | An asset that represents a possibly larger view than the thumbnail of the Item, for example, a true color composite of multi-band data. | +| visual | Best Practice | An asset that is a full resolution version of the data, processed for visual use (RGB only, often sharpened ([pan-sharpened](https://en.wikipedia.org/wiki/Pansharpened_image) and/or using an [unsharp mask](https://en.wikipedia.org/wiki/Unsharp_masking))). | +| date | Best Practice | An asset that provides per-pixel acquisition timestamps, typically serving as metadata to another asset | +| graphic | Best Practice | Supporting plot, illustration, or graph associated with the Item | +| data-mask | Best Practice | File indicating if corresponding pixels have Valid data and various types of invalid data | +| snow-ice | Best Practice | Points to a file that indicates whether a pixel is assessed as being snow/ice or not. | +| land-water | Best Practice | Points to a file that indicates whether a pixel is assessed as being land or water. | +| water-mask | Best Practice | Points to a file that indicates whether a pixel is assessed as being water (e.g. flooding map). | iso-19139 | Best Practice | Points to an [ISO 19139](https://www.iso.org/standard/67253.html) metadata xml file | +| iso-19115 | Best Practice | Points to an [ISO 19115](https://www.iso.org/standard/53798.html) metadata file | +| reflectance, temperature, saturation, cloud, cloud-shadow | [EO Extension](https://github.com/stac-extensions/eo/blob/main/README.md#best-practices) | See the [table](https://github.com/stac-extensions/eo/blob/main/README.md#best-practices) in EO for more information, and the definitive list of roles related to EO. | +| incidence-angle, azimuth, sun-azimuth, sun-elevation, terrain-shadow, terrain-occlusion, terrain-illumination | [View Extension](https://github.com/stac-extensions/view/blob/main/README.md#best-practices) | See the [table](https://github.com/stac-extensions/view/blob/main/README.md#best-practices) in View for more information, and the definitive list of roles related to viewing angles. | +| local-incidence-angle, noise-power, amplitude, magnitude, sigma0, beta0, gamma0, date-offset, covmat, prd | [SAR Extension](https://github.com/stac-extensions/sar/blob/main/README.md#best-practices) | See the [table](https://github.com/stac-extensions/sar/blob/main/README.md#best-practices) in SAR for more information. , and the definitive list of roles related to SAR. | Some of the particular asset roles also have some best practices: @@ -656,13 +656,13 @@ with the `type` field) to communicate the structure and content of related entit Types](https://www.iana.org/assignments/link-relations/link-relations.xhtml) as much as possible. The following table describes a number of the common official relations that are used in production STAC implementations. -| Type | Description | -| --------- | ------------------------------------------------------------ | -| alternate | It is recommended that STAC Items are also available as HTML, and should use this rel with `"type" : "text/html"` to tell clients where they can get a version of the Item or Collection to view in a browser. See [STAC on the Web in Best Practices](#stac-on-the-web) for more information. | -| canonical | The URL of the [canonical](https://en.wikipedia.org/wiki/Canonical_link_element) version of the Item or Collection. API responses and copies of catalogs should use this to inform users that they are direct copy of another STAC Item, using the canonical rel to refer back to the primary location. | -| via | The URL of the source metadata that this STAC Item or Collection is created from. Used similarly to canonical, but refers back to a non-STAC record (Landsat MTL, Sentinel tileInfo.json, etc) | -| prev | Indicates that the link's context is a part of a series, and that the previous in the series is the link target. Typically used in STAC by API's, to return smaller groups of Items or Catalogs/Collections. | -| next | Indicates that the link's context is a part of a series, and that the next in the series is the link target. Typically used in STAC by API's, to return smaller groups of Items or Catalogs/Collections. | +| Type | Description | +| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| alternate | It is recommended that STAC Items are also available as HTML, and should use this rel with `"type" : "text/html"` to tell clients where they can get a version of the Item or Collection to view in a browser. See [STAC on the Web in Best Practices](#stac-on-the-web) for more information. | +| canonical | The URL of the [canonical](https://en.wikipedia.org/wiki/Canonical_link_element) version of the Item or Collection. API responses and copies of catalogs should use this to inform users that they are direct copy of another STAC Item, using the canonical rel to refer back to the primary location. | +| via | The URL of the source metadata that this STAC Item or Collection is created from. Used similarly to canonical, but refers back to a non-STAC record (Landsat MTL, Sentinel tileInfo.json, etc) | +| prev | Indicates that the link's context is a part of a series, and that the previous in the series is the link target. Typically used in STAC by API's, to return smaller groups of Items or Catalogs/Collections. | +| next | Indicates that the link's context is a part of a series, and that the next in the series is the link target. Typically used in STAC by API's, to return smaller groups of Items or Catalogs/Collections. | | preview | Refers to a resource that serves as a preview (see [RFC 6903, sec. 3](https://tools.ietf.org/html/rfc6903#section-3)), usually a lower resolution thumbnail. In STAC this would usually be the same URL as the [thumbnail](#thumbnail) asset, but adding it as a link in addition enables OGC API clients that can't read assets to make use of it. It also adds support for thumbnails to STAC Catalogs as they can't list assets. | Being liberal with the `links` also means that it's ok to have repeated links with the same `href`. For example the diff --git a/catalog-spec/catalog-spec.md b/catalog-spec/catalog-spec.md index 3b6ef0046..e457aad14 100644 --- a/catalog-spec/catalog-spec.md +++ b/catalog-spec/catalog-spec.md @@ -2,8 +2,8 @@ - [Catalog fields](#catalog-fields) - [Additional Field Information](#additional-field-information) - - [stac_version](#stac_version) - - [stac_extensions](#stac_extensions) + - [stac\_version](#stac_version) + - [stac\_extensions](#stac_extensions) - [Link Object](#link-object) - [Relation types](#relation-types) - [Media Types](#media-types) @@ -42,15 +42,15 @@ values for `type` and `stac_extensions`. ## Catalog fields -| Element | Type | Description | -| --------------- | ------------- | ------------------------------------------------------------ | -| type | string | **REQUIRED.** Set to `Catalog` if this Catalog only implements the Catalog spec. | -| stac_version | string | **REQUIRED.** The STAC version the Catalog implements. | -| stac_extensions | \[string] | A list of extension identifiers the Catalog implements. | -| id | string | **REQUIRED.** Identifier for the Catalog. | -| title | string | A short descriptive one-line title for the Catalog. | -| description | string | **REQUIRED.** Detailed multi-line description to fully explain the Catalog. [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for rich text representation. | -| links | [[Link Object](#link-object)] | **REQUIRED.** A list of references to other documents. | +| Element | Type | Description | +| --------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| type | string | **REQUIRED.** Set to `Catalog` if this Catalog only implements the Catalog spec. | +| stac_version | string | **REQUIRED.** The STAC version the Catalog implements. | +| stac_extensions | \[string] | A list of extension identifiers the Catalog implements. | +| id | string | **REQUIRED.** Identifier for the Catalog. | +| title | string | A short descriptive one-line title for the Catalog. | +| description | string | **REQUIRED.** Detailed multi-line description to fully explain the Catalog. [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for rich text representation. | +| links | [[Link Object](#link-object)] | **REQUIRED.** A list of references to other documents. | ### Additional Field Information @@ -71,12 +71,12 @@ This must **not** declare the extensions that are only implemented in child Coll This object describes a relationship with another entity. Data providers are advised to be liberal with links. -| Field Name | Type | Description | -| ---------- | ------ | ----------- | +| Field Name | Type | Description | +| ---------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | href | string | **REQUIRED.** The actual link in the format of an URL. Relative and absolute links are both allowed. [Trailing slashes are significant.](../best-practices.md#consistent-uris) | -| rel | string | **REQUIRED.** Relationship between the current document and the linked document. See chapter ["Relation types"](#relation-types) for more information. | -| type | string | [Media type](#media-types) of the referenced entity. | -| title | string | A human readable title to be used in rendered displays of the link. | +| rel | string | **REQUIRED.** Relationship between the current document and the linked document. See chapter ["Relation types"](#relation-types) for more information. | +| type | string | [Media type](#media-types) of the referenced entity. | +| title | string | A human readable title to be used in rendered displays of the link. | For a full discussion of the situations where relative and absolute links are recommended see the ['Use of links'](../best-practices.md#use-of-links) section of the STAC best practices. @@ -85,13 +85,13 @@ For a full discussion of the situations where relative and absolute links are re The following types are commonly used as `rel` types in the Link Object of a STAC Catalog: -| Type | Description | -| ------- | ----------- | -| self | STRONGLY RECOMMENDED. *Absolute* URL to the location that the Catalog file can be found online, if available. This is particularly useful when in a download package that includes metadata, so that the downstream user can know where the data has come from. | -| root | STRONGLY RECOMMENDED. URL to the root STAC Catalog or [Collection](../collection-spec/README.md). Catalogs should include a link to their root, even if it's the root and points to itself. | -| parent | URL to the parent STAC entity (Catalog or Collection). Non-root Catalogs should include a link to their parent. | -| child | URL to a child STAC entity (Catalog or Collection). | -| item | URL to a STAC Item. | +| Type | Description | +| ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| self | STRONGLY RECOMMENDED. *Absolute* URL to the location that the Catalog file can be found online, if available. This is particularly useful when in a download package that includes metadata, so that the downstream user can know where the data has come from. | +| root | STRONGLY RECOMMENDED. URL to the root STAC Catalog or [Collection](../collection-spec/README.md). Catalogs should include a link to their root, even if it's the root and points to itself. | +| parent | URL to the parent STAC entity (Catalog or Collection). Non-root Catalogs should include a link to their parent. | +| child | URL to a child STAC entity (Catalog or Collection). | +| item | URL to a STAC Item. | **Note:** A link to at least one `item` or `child` (Catalog or Collection) is **RECOMMENDED**, but empty catalogs are allowed if there is an intent to populate it or its children were removed. @@ -121,7 +121,7 @@ The following table lists the Media Types to use for STAC structures. | Media Type | Description | | ---------------------- | ---------------------------------------------------------- | | `application/geo+json` | A STAC [Item](../item-spec/item-spec.md) | -| `application/json` | A STAC Catalog | +| `application/json` | A STAC Catalog | | `application/json` | A STAC [Collection](../collection-spec/collection-spec.md) | ## Extensions diff --git a/collection-spec/collection-spec.md b/collection-spec/collection-spec.md index 8bec50096..853f396e7 100644 --- a/collection-spec/collection-spec.md +++ b/collection-spec/collection-spec.md @@ -3,8 +3,8 @@ - [Overview](#overview) - [Collection fields](#collection-fields) - [Additional Field Information](#additional-field-information) - - [stac_version](#stac_version) - - [stac_extensions](#stac_extensions) + - [stac\_version](#stac_version) + - [stac\_extensions](#stac_extensions) - [id](#id) - [license](#license) - [summaries](#summaries) @@ -43,21 +43,21 @@ specified in [*OGC API - Features*](https://ogcapi.ogc.org/features/), but they ## Collection fields -| Element | Type | Description | -| --------------- | ------------------------------------------------ | ------------------------------------------------------------ | -| type | string | **REQUIRED.** Must be set to `Collection` to be a valid Collection. | -| stac_version | string | **REQUIRED.** The STAC version the Collection implements. | -| stac_extensions | \[string] | A list of extension identifiers the Collection implements. | -| id | string | **REQUIRED.** Identifier for the Collection that is unique across all collections in the root catalog. | -| title | string | A short descriptive one-line title for the Collection. | -| description | string | **REQUIRED.** Detailed multi-line description to fully explain the Collection. [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for rich text representation. | -| keywords | \[string] | List of keywords describing the Collection. | -| license | string | **REQUIRED.** Collection's license(s), either a SPDX [License identifier](https://spdx.org/licenses/), `various` if multiple licenses apply or `proprietary` for all other cases. | -| providers | \[[Provider Object](#provider-object)] | A list of providers, which may include all organizations capturing or processing the data or the hosting provider. Providers should be listed in chronological order with the most recent provider being the last element of the list. | -| extent | [Extent Object](#extent-object) | **REQUIRED.** Spatial and temporal extents. | -| summaries | Map | STRONGLY RECOMMENDED. A map of property summaries, either a set of values, a range of values or a [JSON Schema](https://json-schema.org). | -| links | \[[Link Object](#link-object)] | **REQUIRED.** A list of references to other documents. | -| assets | Map | Dictionary of asset objects that can be downloaded, each with a unique key. | +| Element | Type | Description | +| --------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| type | string | **REQUIRED.** Must be set to `Collection` to be a valid Collection. | +| stac_version | string | **REQUIRED.** The STAC version the Collection implements. | +| stac_extensions | \[string] | A list of extension identifiers the Collection implements. | +| id | string | **REQUIRED.** Identifier for the Collection that is unique across all collections in the root catalog. | +| title | string | A short descriptive one-line title for the Collection. | +| description | string | **REQUIRED.** Detailed multi-line description to fully explain the Collection. [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for rich text representation. | +| keywords | \[string] | List of keywords describing the Collection. | +| license | string | **REQUIRED.** Collection's license(s), either a SPDX [License identifier](https://spdx.org/licenses/), `various` if multiple licenses apply or `proprietary` for all other cases. | +| providers | \[[Provider Object](#provider-object)] | A list of providers, which may include all organizations capturing or processing the data or the hosting provider. Providers should be listed in chronological order with the most recent provider being the last element of the list. | +| extent | [Extent Object](#extent-object) | **REQUIRED.** Spatial and temporal extents. | +| summaries | Map | STRONGLY RECOMMENDED. A map of property summaries, either a set of values, a range of values or a [JSON Schema](https://json-schema.org). | +| links | \[[Link Object](#link-object)] | **REQUIRED.** A list of references to other documents. | +| assets | Map | Dictionary of asset objects that can be downloaded, each with a unique key. | ### Additional Field Information @@ -221,12 +221,12 @@ A provider is any of the organizations that captures or processes the content of 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 | -| ----------- | --------- | ------------------------------------------------------------ | -| name | string | **REQUIRED.** The name of the organization or the individual. | +| Field Name | Type | Description | +| ----------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| name | string | **REQUIRED.** The name of the organization or the individual. | | description | string | Multi-line description to add further provider information such as processing details for processors and producers, hosting details for hosts or basic contact information. [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for rich text representation. | -| roles | \[string] | Roles of the provider. Any of `licensor`, `producer`, `processor` or `host`. | -| url | string | Homepage on which the provider describes the dataset and publishes contact information. | +| roles | \[string] | Roles of the provider. Any of `licensor`, `producer`, `processor` or `host`. | +| url | string | Homepage on which the provider describes the dataset and publishes contact information. | **roles**: The provider's role(s) can be one or more of the following elements: @@ -240,12 +240,12 @@ May also include information about the final storage provider hosting the data. This object describes a relationship with another entity. Data providers are advised to be liberal with links. -| Field Name | Type | Description | -| ---------- | ------ | ------------------------------------------------------------ | +| Field Name | Type | Description | +| ---------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | href | string | **REQUIRED.** The actual link in the format of an URL. Relative and absolute links are both allowed. [Trailing slashes are significant.](../best-practices.md#consistent-uris) | -| rel | string | **REQUIRED.** Relationship between the current document and the linked document. See chapter "[Relation types](#relation-types)" for more information. | -| type | string | [Media type](../catalog-spec/catalog-spec.md#media-types) of the referenced entity. | -| title | string | A human readable title to be used in rendered displays of the link. | +| rel | string | **REQUIRED.** Relationship between the current document and the linked document. See chapter "[Relation types](#relation-types)" for more information. | +| type | string | [Media type](../catalog-spec/catalog-spec.md#media-types) of the referenced entity. | +| title | string | A human readable title to be used in rendered displays of the link. | For a full discussion of the situations where relative and absolute links are recommended see the ['Use of links'](../best-practices.md#use-of-links) section of the STAC best practices. @@ -259,15 +259,15 @@ It is recommended to use the official The following table explains places where custom STAC `rel` types are used for Collections. This is done where there is not a clear official option, or where STAC uses an official type but adds additional meaning for the STAC context. -| Type | Description | -| ------- | ------------------------------------------------------------ | -| self | STRONGLY RECOMMENDED. *Absolute* URL to the location that the Collection file can be found online, if available. This is particularly useful when in a download package that includes metadata, so that the downstream user can know where the data has come from. | -| root | URL to the root STAC entity (Catalog or Collection). Collections should include a link to their root, even if it's the root and points to itself. | -| parent | URL to the parent STAC entity (Catalog or Collection). Non-root Collections should include a link to their parent. | -| child | URL to a child STAC entity (Catalog or Collection). | -| item | URL to a STAC Item. All Items linked from a Collection MUST refer back to its Collection with the [`collection` relation type](../item-spec/item-spec.md#relation-types). | -| license | The license URL(s) for the Collection SHOULD be specified if the `license` field is set to `proprietary` or `various`. If there is no public license URL available, it is RECOMMENDED to put the license text in a separate file and link to this file. | -| derived_from | URL to a STAC Collection that was used as input data in the creation of this Collection. See the note in [STAC Item](../item-spec/item-spec.md#derived_from) for more info. | +| Type | Description | +| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| self | STRONGLY RECOMMENDED. *Absolute* URL to the location that the Collection file can be found online, if available. This is particularly useful when in a download package that includes metadata, so that the downstream user can know where the data has come from. | +| root | URL to the root STAC entity (Catalog or Collection). Collections should include a link to their root, even if it's the root and points to itself. | +| parent | URL to the parent STAC entity (Catalog or Collection). Non-root Collections should include a link to their parent. | +| child | URL to a child STAC entity (Catalog or Collection). | +| item | URL to a STAC Item. All Items linked from a Collection MUST refer back to its Collection with the [`collection` relation type](../item-spec/item-spec.md#relation-types). | +| license | The license URL(s) for the Collection SHOULD be specified if the `license` field is set to `proprietary` or `various`. If there is no public license URL available, it is RECOMMENDED to put the license text in a separate file and link to this file. | +| derived_from | URL to a STAC Collection that was used as input data in the creation of this Collection. See the note in [STAC Item](../item-spec/item-spec.md#derived_from) for more info. | A more complete list of possible `rel` types and their meaning in STAC can be found in the [Using Relation Types](../best-practices.md#using-relation-types) best practice. @@ -283,13 +283,13 @@ An Asset is an object that contains a URI to data associated with the Collection or streamed. The definition provided here, at the Collection level, is the same as the [Asset Object in Items](../item-spec/item-spec.md#asset-object). It is allowed to add additional fields. -| Field Name | Type | Description | -| ----------- | --------- | ----------- | -| href | string | **REQUIRED.** URI to the asset object. Relative and absolute URI are both allowed. | -| title | string | The displayed title for clients and users. | -| description | string | A description of the Asset providing additional details, such as how it was processed or created. [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for rich text representation. | +| Field Name | Type | Description | +| ----------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| href | string | **REQUIRED.** URI to the asset object. Relative and absolute URI are both allowed. | +| title | string | The displayed title for clients and users. | +| description | string | A description of the Asset providing additional details, such as how it was processed or created. [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for rich text representation. | | type | string | [Media type](../item-spec/item-spec.md#asset-media-type) of the asset. See the [common media types](../best-practices.md#common-media-types-in-stac) in the best practice doc for commonly used asset types. | -| roles | \[string] | The [semantic roles](../item-spec/item-spec.md#asset-role-types) of the asset, similar to the use of `rel` in links. | +| roles | \[string] | The [semantic roles](../item-spec/item-spec.md#asset-role-types) of the asset, similar to the use of `rel` in links. | ### Range Object @@ -300,8 +300,8 @@ 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`. -| Field Name | Type | Description | -| ---------- | -------------- | ----------- | +| Field Name | Type | Description | +| ---------- | -------------- | ---------------------------- | | minimum | number\|string | **REQUIRED.** Minimum value. | | maximum | number\|string | **REQUIRED.** Maximum value. | diff --git a/extensions/README.md b/extensions/README.md index 684fa7985..59dd2fac2 100644 --- a/extensions/README.md +++ b/extensions/README.md @@ -1,16 +1,17 @@ # Extensions -- [Overview](#overview) -- [Using Extensions](#using-extensions) - - [Extension identifiers in `stac_extensions`](#extension-identifiers-in-stac_extensions) -- [Community Extensions](#community-extensions) - - [Proposed extensions](#proposed-extensions) -- [Extension Maturity](#extension-maturity) -- [Extending STAC](#extending-stac) - - [General Conventions](#general-conventions) - - [Proposing new extensions](#proposing-new-extensions) - - [Prefixes](#prefixes) - - [Use of arrays and objects](#use-of-arrays-and-objects) +- [Extensions](#extensions) + - [Overview](#overview) + - [Using Extensions](#using-extensions) + - [Extension identifiers in `stac_extensions`](#extension-identifiers-in-stac_extensions) + - [Community Extensions](#community-extensions) + - [Proposed extensions](#proposed-extensions) + - [Extension Maturity](#extension-maturity) + - [Extending STAC](#extending-stac) + - [General Conventions](#general-conventions) + - [Proposing new extensions](#proposing-new-extensions) + - [Prefixes](#prefixes) + - [Use of arrays and objects](#use-of-arrays-and-objects) ## Overview @@ -101,13 +102,13 @@ There are many extensions being built with STAC, but they have varying degrees o listed here included must include a maturity classification, so that STAC spec users can easily get a sense of how much they can count on the extension. -| Maturity Classification | Min Impl # | Description | Stability | -| ----------------------- | ----------- | ----------- | --------- | -| Proposal | 0 | An idea put forward by a community member to gather feedback | Not stable - breaking changes almost guaranteed as implementers try out the idea. | -| Pilot | 1 | Idea is fleshed out, with examples and a JSON schema, and implemented in one or more catalogs. Additional implementations encouraged to help give feedback | Approaching stability - breaking changes are not anticipated but can easily come from additional feedback. | -| Candidate | 3 | A number of implementers are using it and are standing behind it as a solid extension. User can generally count on an extension at this maturity level. | Mostly stable, breaking changes require a new version and minor changes are unlikely. The extension has a code owner, designated in its README. | -| Stable | 6 | Highest current level of maturity. The community of extension maintainers commits to a STAC review process for any changes, which are not made lightly. | Completely stable, all changes require a new version number and review process. | -| Deprecated | N/A | A previous extension that has likely been superseded by a newer one or did not work out for some reason. | DO NOT USE, is not supported | +| Maturity Classification | Min Impl # | Description | Stability | +| ----------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | +| Proposal | 0 | An idea put forward by a community member to gather feedback | Not stable - breaking changes almost guaranteed as implementers try out the idea. | +| Pilot | 1 | Idea is fleshed out, with examples and a JSON schema, and implemented in one or more catalogs. Additional implementations encouraged to help give feedback | Approaching stability - breaking changes are not anticipated but can easily come from additional feedback. | +| Candidate | 3 | A number of implementers are using it and are standing behind it as a solid extension. User can generally count on an extension at this maturity level. | Mostly stable, breaking changes require a new version and minor changes are unlikely. The extension has a code owner, designated in its README. | +| Stable | 6 | Highest current level of maturity. The community of extension maintainers commits to a STAC review process for any changes, which are not made lightly. | Completely stable, all changes require a new version number and review process. | +| Deprecated | N/A | A previous extension that has likely been superseded by a newer one or did not work out for some reason. | DO NOT USE, is not supported | Maturity mostly comes through diverse implementations, so the minimum number of implementations column is the main gating function for an extension to mature. But extension authors can also diff --git a/item-spec/common-metadata.md b/item-spec/common-metadata.md index 1d47d89ca..fc50c9228 100644 --- a/item-spec/common-metadata.md +++ b/item-spec/common-metadata.md @@ -13,7 +13,14 @@ or [Collection Asset](../collection-spec/collection-spec.md#asset-object). - [Relation types](#relation-types) - [Provider](#provider) - [Provider Object](#provider-object) + - [roles](#roles) - [Instrument](#instrument) + - [Additional Field Information](#additional-field-information) + - [platform](#platform) + - [instruments](#instruments) + - [constellation](#constellation) + - [mission](#mission) + - [gsd](#gsd) Various *examples* are available in the folder [`examples`](../examples/). *JSON Schemas* can be found in the folder [`json-schema`](json-schema/). @@ -27,11 +34,11 @@ Descriptive fields to give a basic overview of a STAC Item. - [JSON Schema](json-schema/basics.json) -| Field Name | Type | Description | -| ----------- | --------- | ----------- | -| title | string | A human readable title describing the STAC entity. | +| Field Name | Type | Description | +| ----------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| title | string | A human readable title describing the STAC entity. | | description | string | Detailed multi-line description to fully explain the STAC entity. [CommonMark 0.29](https://commonmark.org/) syntax MAY be used for rich text representation. | -| keywords | \[string] | List of keywords describing the STAC entity. | +| keywords | \[string] | List of keywords describing the STAC entity. | ## Date and Time @@ -39,11 +46,11 @@ Descriptive fields to give a basic overview of a STAC Item. Fields to provide additional temporal information such as ranges with a start and an end datetime stamp. -| Field Name | Type | Description | -| ---------- | ------------ | ----------- | +| Field Name | Type | Description | +| ---------- | ------------ | -------------------------------------------------------------------------------- | | datetime | string\|null | See the [Item Spec Fields](item-spec.md#properties-object) for more information. | -| created | string | Creation date and time of the corresponding data (see below), in UTC. | -| updated | string | Date and time the corresponding data (see below) was updated last, in UTC. | +| created | string | Creation date and time of the corresponding data (see below), in UTC. | +| updated | string | Date and time the corresponding data (see below) was updated last, in UTC. | All timestamps MUST be formatted according to [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6). @@ -65,10 +72,10 @@ So if you use `start_datetime` you need to add `end_datetime` and vice-versa. Both fields are also REQUIRED if the `datetime` field is set to `null`. The datetime property in a STAC Item and these fields are not mutually exclusive. -| Field Name | Type | Description | -| -------------- | ------ | ------------------------------------------------------------ | +| Field Name | Type | Description | +| -------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | start_datetime | string | The first or start date and time for the Item, in UTC. It is formatted as `date-time` according to [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6). | -| end_datetime | string | The last or end date and time for the Item, in UTC. It is formatted as `date-time` according to [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6). | +| end_datetime | string | The last or end date and time for the Item, in UTC. It is formatted as `date-time` according to [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6). | ## Licensing @@ -77,8 +84,8 @@ Information about the license(s) of the data, which is not necessarily the same - [JSON Schema](json-schema/licensing.json) -| Field Name | Type | Description | -| ---------- | ------ | ----------- | +| Field Name | Type | Description | +| ---------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | license | string | Item's license(s), either a SPDX [License identifier](https://spdx.org/licenses/), `various` if multiple licenses apply or `proprietary` for all other cases. Should be defined at the Collection level if possible. | **license**: Data license(s) as a SPDX [License identifier](https://spdx.org/licenses/). Alternatively, use @@ -89,9 +96,9 @@ and consumers have not been granted any explicit right to use the data. ### Relation types -| Type | Description | -| ------------ | ------------------------------------------------------------ | -| license | The license URL(s) for the Item 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 supplement the STAC Item with the license text in a separate file and link to this file. | +| Type | Description | +| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| license | The license URL(s) for the Item 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 supplement the STAC Item with the license text in a separate file and link to this file. | ## Provider @@ -100,9 +107,9 @@ Information about the organizations capturing, producing, processing, hosting or - [JSON Schema](json-schema/provider.json) -| Field Name | Type | Description | -| ---------- | ------ | ----------- | -| providers | [[Provider Object](#provider-object)] | A list of providers, which may include all organizations capturing or processing the data or the hosting provider. Providers should be listed in chronological order with the most recent provider being the last element of the list. | +| Field Name | Type | Description | +| ---------- | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| providers | [[Provider Object](#provider-object)] | A list of providers, which may include all organizations capturing or processing the data or the hosting provider. Providers should be listed in chronological order with the most recent provider being the last element of the list. | ### Provider Object @@ -111,12 +118,12 @@ A provider is any of the organizations that captures or processes the content of 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 | -| ----------- | --------- | ------------------------------------------------------------ | -| name | string | **REQUIRED.** The name of the organization or the individual. | +| Field Name | Type | Description | +| ----------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| name | string | **REQUIRED.** The name of the organization or the individual. | | description | string | Multi-line description to add further provider information such as processing details for processors and producers, hosting details for hosts or basic contact information. [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for rich text representation. | -| roles | \[string] | Roles of the provider. Any of `licensor`, `producer`, `processor` or `host`. | -| url | string | Homepage on which the provider describes the dataset and publishes contact information. | +| roles | \[string] | Roles of the provider. Any of `licensor`, `producer`, `processor` or `host`. | +| url | string | Homepage on which the provider describes the dataset and publishes contact information. | #### roles @@ -135,12 +142,12 @@ with domain-specific extensions that describe the actual data, such as the `eo` - [JSON Schema](json-schema/instrument.json) -| Field Name | Type | Description | -| ------------- | --------- | ----------- | -| platform | string | Unique name of the specific platform to which the instrument is attached. | -| instruments | \[string] | Name of instrument or sensor used (e.g., MODIS, ASTER, OLI, Canon F-1). | -| constellation | string | Name of the constellation to which the platform belongs. | -| mission | string | Name of the mission for which data is collected. | +| Field Name | Type | Description | +| ------------- | --------- | ---------------------------------------------------------------------------- | +| platform | string | Unique name of the specific platform to which the instrument is attached. | +| instruments | \[string] | Name of instrument or sensor used (e.g., MODIS, ASTER, OLI, Canon F-1). | +| constellation | string | Name of the constellation to which the platform belongs. | +| mission | string | Name of the mission for which data is collected. | | gsd | number | Ground Sample Distance at the sensor, in meters (m), must be greater than 0. | ### Additional Field Information diff --git a/item-spec/item-spec.md b/item-spec/item-spec.md index b44adc7db..04f8af642 100644 --- a/item-spec/item-spec.md +++ b/item-spec/item-spec.md @@ -3,8 +3,8 @@ - [Overview](#overview) - [Item fields](#item-fields) - [Additional Field Information](#additional-field-information) - - [stac_version](#stac_version) - - [stac_extensions](#stac_extensions) + - [stac\_version](#stac_version) + - [stac\_extensions](#stac_extensions) - [id](#id) - [assets](#assets) - [bbox](#bbox) @@ -13,7 +13,7 @@ - [Additional Fields](#additional-fields) - [Link Object](#link-object) - [Relation types](#relation-types) - - [derived_from](#derived_from) + - [derived\_from](#derived_from) - [Collections](#collections) - [Asset Object](#asset-object) - [Asset Media Type](#asset-media-type) @@ -52,18 +52,18 @@ required fields is a valid STAC Item. This object describes a STAC Item. The fields `id`, `type`, `bbox`, `geometry` and `properties` are inherited from GeoJSON. -| Field Name | Type | Description | -| ---------- | -------------------------------------------------------------------------- | ----------- | -| type | string | **REQUIRED.** Type of the GeoJSON Object. MUST be set to `Feature`. | -| stac_version | string | **REQUIRED.** The STAC version the Item implements. | -| stac_extensions | \[string] | A list of extensions the Item implements. | -| id | string | **REQUIRED.** Provider identifier. The ID should be unique within the [Collection](../collection-spec/collection-spec.md) that contains the Item. | -| geometry | [GeoJSON Geometry Object](https://tools.ietf.org/html/rfc7946#section-3.1) \| [null](https://tools.ietf.org/html/rfc7946#section-3.2) | **REQUIRED.** Defines the full footprint of the asset represented by this item, formatted according to [RFC 7946, section 3.1](https://tools.ietf.org/html/rfc7946#section-3.1). The footprint should be the default GeoJSON geometry, though additional geometries can be included. Coordinates are specified in Longitude/Latitude or Longitude/Latitude/Elevation based on [WGS 84](http://www.opengis.net/def/crs/OGC/1.3/CRS84). | -| bbox | \[number] | **REQUIRED if `geometry` is not `null`, prohibited if `geometry` is `null`.** Bounding Box of the asset represented by this Item, formatted according to [RFC 7946, section 5](https://tools.ietf.org/html/rfc7946#section-5). | -| properties | [Properties Object](#properties-object) | **REQUIRED.** A dictionary of additional metadata for the Item. | -| links | \[[Link Object](#link-object)] | **REQUIRED.** List of link objects to resources and related URLs. See the [best practices](../best-practices.md#use-of-links) for details on when the use `self` links is strongly recommended. | -| assets | Map | **REQUIRED.** Dictionary of asset objects that can be downloaded, each with a unique key. | -| collection | string | The `id` of the STAC Collection this Item references to (see [`collection` relation type](#relation-types)). This field is *required* if such a relation type is present and is *not allowed* otherwise. This field provides an easy way for a user to search for any Items that belong in a specified Collection. Must be a non-empty string. | +| Field Name | Type | Description | +| --------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| type | string | **REQUIRED.** Type of the GeoJSON Object. MUST be set to `Feature`. | +| stac_version | string | **REQUIRED.** The STAC version the Item implements. | +| stac_extensions | \[string] | A list of extensions the Item implements. | +| id | string | **REQUIRED.** Provider identifier. The ID should be unique within the [Collection](../collection-spec/collection-spec.md) that contains the Item. | +| geometry | [GeoJSON Geometry Object](https://tools.ietf.org/html/rfc7946#section-3.1) \| [null](https://tools.ietf.org/html/rfc7946#section-3.2) | **REQUIRED.** Defines the full footprint of the asset represented by this item, formatted according to [RFC 7946, section 3.1](https://tools.ietf.org/html/rfc7946#section-3.1). The footprint should be the default GeoJSON geometry, though additional geometries can be included. Coordinates are specified in Longitude/Latitude or Longitude/Latitude/Elevation based on [WGS 84](http://www.opengis.net/def/crs/OGC/1.3/CRS84). | +| bbox | \[number] | **REQUIRED if `geometry` is not `null`, prohibited if `geometry` is `null`.** Bounding Box of the asset represented by this Item, formatted according to [RFC 7946, section 5](https://tools.ietf.org/html/rfc7946#section-5). | +| properties | [Properties Object](#properties-object) | **REQUIRED.** A dictionary of additional metadata for the Item. | +| links | \[[Link Object](#link-object)] | **REQUIRED.** List of link objects to resources and related URLs. See the [best practices](../best-practices.md#use-of-links) for details on when the use `self` links is strongly recommended. | +| assets | Map | **REQUIRED.** Dictionary of asset objects that can be downloaded, each with a unique key. | +| collection | string | The `id` of the STAC Collection this Item references to (see [`collection` relation type](#relation-types)). This field is *required* if such a relation type is present and is *not allowed* otherwise. This field provides an easy way for a user to search for any Items that belong in a specified Collection. Must be a non-empty string. | ### Additional Field Information @@ -125,8 +125,8 @@ Additional metadata fields can be added to the GeoJSON Object Properties. The on is `datetime` but it is recommended to add more fields, see [Additional Fields](#additional-fields) resources below. -| Field Name | Type | Description | -| ---------- | ------------ | ------------------------------------------------------------ | +| Field Name | Type | Description | +| ---------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | datetime | string\|null | **REQUIRED.** The searchable date and time of the assets, which must be in UTC. It is formatted according to [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6). `null` is allowed, but requires `start_datetime` and `end_datetime` from [common metadata](common-metadata.md#date-and-time-range) to be set. | #### datetime @@ -171,12 +171,12 @@ with the links section, to describe things like the Catalog an Item is in, relat child Items (modeled in different ways, like an 'acquisition' or derived data). It is allowed to add additional fields such as a `title` and `type`. -| Field Name | Type | Description | -| ---------- | ------ | ----------- | +| Field Name | Type | Description | +| ---------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | href | string | **REQUIRED.** The actual link in the format of an URL. Relative and absolute links are both allowed. [Trailing slashes are significant.](../best-practices.md#consistent-uris) | -| rel | string | **REQUIRED.** Relationship between the current document and the linked document. See chapter "Relation types" for more information. | -| type | string | [Media type](../catalog-spec/catalog-spec.md#media-types) of the referenced entity. | -| title | string | A human readable title to be used in rendered displays of the link. | +| rel | string | **REQUIRED.** Relationship between the current document and the linked document. See chapter "Relation types" for more information. | +| type | string | [Media type](../catalog-spec/catalog-spec.md#media-types) of the referenced entity. | +| title | string | A human readable title to be used in rendered displays of the link. | For a full discussion of the situations where relative and absolute links are recommended see the ['Use of links'](../best-practices.md#use-of-links) section of the STAC best practices. @@ -190,13 +190,13 @@ It is recommended to use the official The following table explains places where STAC use custom `rel` types are used with Items. This happens where there is not a clear official option, or where STAC uses an official type but adds additional meaning for the STAC context. -| Type | Description | -| ------------ | ------------------------------------------------------------ | -| self | STRONGLY RECOMMENDED. *Absolute* URL to the Item if it is available at a public URL. This is particularly useful when in a download package that includes metadata, so that the downstream user can know where the data has come from. | -| root | URL to the root STAC entity (Catalog or Collection). | -| parent | URL to the parent STAC entity (Catalog or Collection). | +| Type | Description | +| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| self | STRONGLY RECOMMENDED. *Absolute* URL to the Item if it is available at a public URL. This is particularly useful when in a download package that includes metadata, so that the downstream user can know where the data has come from. | +| root | URL to the root STAC entity (Catalog or Collection). | +| parent | URL to the parent STAC entity (Catalog or Collection). | | collection | STRONGLY RECOMMENDED. URL to a Collection. *Absolute* URLs should be used whenever possible. The referenced Collection is STRONGLY RECOMMENDED to implement the same STAC version as the Item. A link with this `rel` type is *required* if the `collection` field in properties is present. | -| derived_from | URL to a STAC Item that was used as input data in the creation of this Item. | +| derived_from | URL to a STAC Item that was used as input data in the creation of this Item. | A more complete list of potential `rel` types and their meaning in STAC can be found in the [Using Relation Types](../best-practices.md#using-relation-types) best practice. @@ -232,13 +232,13 @@ Linking back must happen in two places: An Asset is an object that contains a URI to data associated with the Item that can be downloaded or streamed. It is allowed to add additional fields. -| Field Name | Type | Description | -| ----------- | --------- | ----------- | -| href | string | **REQUIRED.** URI to the asset object. Relative and absolute URI are both allowed. [Trailing slashes are significant.](../best-practices.md#consistent-uris) | -| title | string | The displayed title for clients and users. | +| Field Name | Type | Description | +| ----------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| href | string | **REQUIRED.** URI to the asset object. Relative and absolute URI are both allowed. [Trailing slashes are significant.](../best-practices.md#consistent-uris) | +| title | string | The displayed title for clients and users. | | description | string | A description of the Asset providing additional details, such as how it was processed or created. [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for rich text representation. | -| type | string | [Media type](#asset-media-type) of the asset. See the [common media types](../best-practices.md#common-media-types-in-stac) in the best practice doc for commonly used asset types. | -| roles | \[string] | The [semantic roles](#asset-roles) of the asset, similar to the use of `rel` in links. | +| type | string | [Media type](#asset-media-type) of the asset. See the [common media types](../best-practices.md#common-media-types-in-stac) in the best practice doc for commonly used asset types. | +| roles | \[string] | The [semantic roles](#asset-roles) of the asset, similar to the use of `rel` in links. | [Additional fields](#additional-fields) *may* be added to the assets, though this is recommended only in special cases. See [Additional Fields for Assets](#additional-fields-for-assets)) for more information. @@ -263,12 +263,12 @@ describe the role. Like the Link `rel` field, the `roles` field can be given any value, however here are a few standardized role names. -| Role Name | Description | -| --------- | ------------------------------------------------------------------------------------- | +| Role Name | Description | +| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | thumbnail | An asset that represents a thumbnail of the Item, typically a true color image (for Items with assets in the visible wavelengths), lower-resolution (typically smaller 600x600 pixels), and typically a JPEG or PNG (suitable for display in a web browser). Multiple assets may have this purpose, but it recommended that the `type` and `roles` be unique tuples. For example, Sentinel-2 L2A provides thumbnail images in both JPEG and JPEG2000 formats, and would be distinguished by their media types. | -| overview | An asset that represents a possibly larger view than the thumbnail of the Item, for example, a true color composite of multi-band data. | -| data | The data itself. This is a suggestion for a common role for data files to be used in case data providers don't come up with their own names and semantics. | -| metadata | A metadata sidecar file describing the data in this Item, for example the Landsat-8 MTL file. | +| overview | An asset that represents a possibly larger view than the thumbnail of the Item, for example, a true color composite of multi-band data. | +| data | The data itself. This is a suggestion for a common role for data files to be used in case data providers don't come up with their own names and semantics. | +| metadata | A metadata sidecar file describing the data in this Item, for example the Landsat-8 MTL file. | It is STRONGLY RECOMMENDED to add to each STAC Item - a thumbnail with the role `thumbnail` for preview purposes diff --git a/package.json b/package.json index 0012c9c4f..e1d7ba9a2 100644 --- a/package.json +++ b/package.json @@ -6,21 +6,90 @@ "license": "Apache-2.0", "scripts": { "check": "npm run check-markdown && npm run check-examples", - "check-markdown": "remark . -f -r .circleci/rc.yaml", + "check-markdown": "remark . --frail", "check-examples": "stac-node-validator . --lint --verbose --schemas .", "format-examples": "stac-node-validator . --format --schemas .", "publish-schemas": "node .circleci/publish-schemas.js" }, "dependencies": { - "gh-pages": "^3.0.0", + "gh-pages": "^6.0.0", "klaw-sync": "^6.0.0", - "remark-cli": "^8.0.0", - "remark-lint": "^7.0.0", - "remark-lint-no-html": "^2.0.0", - "remark-preset-lint-consistent": "^3.0.0", - "remark-preset-lint-markdown-style-guide": "^3.0.0", - "remark-preset-lint-recommended": "^4.0.0", - "remark-validate-links": "^10.0.0", - "stac-node-validator": "^1.1.0" + "remark-cli": "^12.0.0", + "remark-gfm": "^4.0.0", + "remark-lint": "^9.1.2", + "remark-lint-no-html": "^3.1.2", + "remark-preset-lint-consistent": "^5.1.2", + "remark-preset-lint-markdown-style-guide": "^5.1.3", + "remark-preset-lint-recommended": "^6.1.3", + "remark-validate-links": "^13.0.0", + "stac-node-validator": "^1.3.0" + }, + "remarkConfig": { + "plugins": [ + "remark-gfm", + "validate-links", + "remark-preset-lint-consistent", + "remark-preset-lint-markdown-style-guide", + "remark-preset-lint-recommended", + "lint-no-html", + [ + "remark-lint-emphasis-marker", + "*" + ], + "remark-lint-hard-break-spaces", + "remark-lint-blockquote-indentation", + "remark-lint-no-consecutive-blank-lines", + [ + "remark-lint-maximum-line-length", + 150 + ], + [ + "remark-lint-fenced-code-flag", + false + ], + "remark-lint-fenced-code-marker", + "remark-lint-no-shell-dollars", + [ + "remark-lint-code-block-style", + "fenced" + ], + "remark-lint-heading-increment", + "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 + ], + "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-list-item-indent", + "space" + ], + "remark-lint-table-pipes", + "remark-lint-no-literal-urls", + [ + "remark-lint-no-file-name-irregular-characters", + false + ], + [ + "remark-lint-list-item-spacing", + false + ] + ] } -} +} \ No newline at end of file From 92fa0ac316e0b7ddabf424cfea9dc360b8d8c65b Mon Sep 17 00:00:00 2001 From: Phil Varner Date: Tue, 26 Sep 2023 14:03:55 -0400 Subject: [PATCH 23/25] prepare for switching to git branch main vs. dev/master --- .circleci/config.yml | 2 +- .circleci/rc.yaml | 43 ------------------------------ .github/pull_request_template.md | 4 +-- CHANGELOG.md | 2 +- CONTRIBUTING.md | 7 ++--- README.md | 9 ++++--- collection-spec/collection-spec.md | 2 +- item-spec/item-spec.md | 2 +- process.md | 14 ++++++---- 9 files changed, 24 insertions(+), 61 deletions(-) delete mode 100644 .circleci/rc.yaml diff --git a/.circleci/config.yml b/.circleci/config.yml index 5c87bc678..915a17a32 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -63,4 +63,4 @@ workflows: tags: only: /^v.*/ branches: - ignore: /^((?!dev).)*$/ \ No newline at end of file + only: main \ No newline at end of file diff --git a/.circleci/rc.yaml b/.circleci/rc.yaml deleted file mode 100644 index b0dd538ca..000000000 --- a/.circleci/rc.yaml +++ /dev/null @@ -1,43 +0,0 @@ -plugins: -# Check links - - validate-links -# Apply some recommended defaults for consistency - - remark-preset-lint-consistent - - remark-preset-lint-recommended - - lint-no-html -# General formatting - - - remark-lint-emphasis-marker - - '*' - - remark-lint-hard-break-spaces - - remark-lint-blockquote-indentation - - remark-lint-no-consecutive-blank-lines - - - remark-lint-maximum-line-length - - 150 -# Code - - remark-lint-fenced-code-flag - - remark-lint-fenced-code-marker - - remark-lint-no-shell-dollars - - - remark-lint-code-block-style - - 'fenced' -# Headings - - remark-lint-heading-increment - - 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-list-item-indent - - space -# Tables - - remark-lint-table-pipes - - 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 bd3b2f95a..4295ca3fa 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,5 +1,5 @@ -**Related Issue(s):** # - +**Related Issue(s):** +- # **Proposed Changes:** diff --git a/CHANGELOG.md b/CHANGELOG.md index 99574afd7..f5590ea85 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -474,7 +474,7 @@ See the [milestone 0.4.0 in the issue tracker](https://github.com/radiantearth/s Thanks @hgs-msmith, @matthewhanson, @hgs-trutherford, @rouault, @joshfix, @alkamin, @hemphillda, @jeffnaus and @fredliporace for contributing to the spec directly, and to [everyone](https://github.com/opengeospatial/wfs3hackathon/blob/master/notes/introductions.md#participants) who participated in the [Ft Collins sprint](https://github.com/radiantearth/community-sprints/tree/master/03072018-ft-collins-co) and brought great ideas. -[Unreleased]: +[Unreleased]: [v1.0.0]: [v1.0.0-rc.4]: [v1.0.0-rc.3]: diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5b9b2d7a2..cf1c67638 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -18,15 +18,16 @@ this broader ecosystem, while keeping the core spec as stable as we can. ### Submitting Pull Requests Any proposed changes to the specification should be done as pull requests. Please make these -requests against the [dev](https://github.com/radiantearth/stac-spec/tree/dev) branch (this will -require you to switch from the default of 'master', which we keep so it displays first). +requests against the [main](https://github.com/radiantearth/stac-spec/tree/main) branch (this will +require you to switch from the default of the most current version branch, which we keep so it +displays first). 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 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 main, as mentioned above - even if the branch was made off of main 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 diff --git a/README.md b/README.md index 70ea32468..21fb08269 100644 --- a/README.md +++ b/README.md @@ -52,10 +52,11 @@ version of the spec. It is currently version **1.0.0** of the specification. The follows [Semantic Versioning](https://semver.org/), so any breaking change will require the spec to go to 2.0.0. -The [dev](https://github.com/radiantearth/stac-spec/tree/dev) branch is where active development -takes place, and may have inconsistent examples. Whenever dev stabilizes, a release is cut and we -merge `dev` in to `master`. So `master` should be stable at any given time. -More information on how the STAC development process works can be found in +The [main](https://github.com/radiantearth/stac-spec/tree/main) branch is where active development +takes place, and may have inconsistent examples. Whenever `main` stabilizes, a release is cut and +we tag `main` and create a new branch with the same name as the tag, e.g., `v1.0.0`, and set that branch as the +default to represent the most stable release. +More information on how the STAC development process works can be found in [process.md](process.md). ## Communication diff --git a/collection-spec/collection-spec.md b/collection-spec/collection-spec.md index 853f396e7..afba57c7b 100644 --- a/collection-spec/collection-spec.md +++ b/collection-spec/collection-spec.md @@ -1,4 +1,4 @@ -# STAC Collection Specification +# STAC Collection Specification - [Overview](#overview) - [Collection fields](#collection-fields) diff --git a/item-spec/item-spec.md b/item-spec/item-spec.md index 04f8af642..88869339d 100644 --- a/item-spec/item-spec.md +++ b/item-spec/item-spec.md @@ -1,4 +1,4 @@ -# STAC Item Specification +# STAC Item Specification - [Overview](#overview) - [Item fields](#item-fields) diff --git a/process.md b/process.md index 3becf50b4..e6b8550b9 100644 --- a/process.md +++ b/process.md @@ -2,13 +2,17 @@ ### Development Process -The SpatioTemporal Asset Catalog specification is under active development. The goal is to get to a small, flexible stable +The SpatioTemporal Asset Catalog specification is under active development. The goal is to get to a small, flexible stable release that can be extended in a variety of ways. The core development team aims to release early and often, which generally -has meant a new release between two and four months since the previous one. +has meant a new release between two and four months since the previous one. -The `master` branch aims to always be stable, meaning that all the pieces of the specification are consistent and well -explained, and all the examples are consistent with the specification. The `dev` branch is a place of active development, -where a new change in one part of the spec might not yet be fully updated everywhere else. The team uses the +The `main` branch is a place of active development, +where a new change in one part of the spec might not yet be fully updated everywhere else. +Tags, such as `v1.0.0`, aim to always be stable, meaning that all the pieces of the specification +are consistent and well-explained, and all the examples are consistent with the specification. The +latest tag will also has a branch associated with it that is set to the default. + +The team uses the [stac-spec issue tracker](https://github.com/radiantearth/stac-spec/issues) to identify and track all that will be done for a release. Once all the major issues are resolved the core team makes sure everything is consistent across the spec and examples. From be3dc7262f6c893a4296282bc8b4608d26f96fc9 Mon Sep 17 00:00:00 2001 From: Phil Varner Date: Tue, 26 Sep 2023 14:06:22 -0400 Subject: [PATCH 24/25] specify name of branch --- process.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/process.md b/process.md index e6b8550b9..e7b5de286 100644 --- a/process.md +++ b/process.md @@ -10,7 +10,8 @@ The `main` branch is a place of active development, where a new change in one part of the spec might not yet be fully updated everywhere else. Tags, such as `v1.0.0`, aim to always be stable, meaning that all the pieces of the specification are consistent and well-explained, and all the examples are consistent with the specification. The -latest tag will also has a branch associated with it that is set to the default. +latest tag will also has a branch associated with it that is set to the default, e.g., +`release/v1.0.0`. The team uses the [stac-spec issue tracker](https://github.com/radiantearth/stac-spec/issues) to identify and track all that will be done for From f7ae58201c6c569068b48af98be6115a7f07522f Mon Sep 17 00:00:00 2001 From: Phil Varner Date: Tue, 26 Sep 2023 14:08:39 -0400 Subject: [PATCH 25/25] update main in pr template --- .github/pull_request_template.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 4295ca3fa..925f69e0f 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -8,7 +8,7 @@ **PR Checklist:** -- [ ] This PR is made against the dev branch (all proposed changes except releases should be against dev, not master). +- [ ] This PR is made against the `main` branch - [ ] 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.