From d2f0c4839d9a47c6cb1af46f94e16d91eadb1f57 Mon Sep 17 00:00:00 2001 From: Chris Holmes Date: Thu, 20 Aug 2020 07:48:43 -0700 Subject: [PATCH 1/5] Added more information to make ID's unique --- item-spec/item-spec.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/item-spec/item-spec.md b/item-spec/item-spec.md index 7c5fdb375..ba309cb26 100644 --- a/item-spec/item-spec.md +++ b/item-spec/item-spec.md @@ -31,7 +31,7 @@ inherited from GeoJSON. | ---------- | -------------------------------------------------------------------------- | ----------- | | 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. As most geospatial assets are already defined by some identification scheme by the data provider it is recommended to simply use that ID. Data providers are advised to include sufficient information to make their IDs globally unique, including things like unique satellite IDs. | +| id | string | **REQUIRED.** Provider identifier. If the item is part of a [Collection](../collection-spec/README.md) its ID should be unique within that collection. | | type | string | **REQUIRED.** Type of the GeoJSON Object. MUST be set to `Feature`. | | 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). | @@ -42,6 +42,12 @@ inherited from GeoJSON. **stac_version**: In general, STAC versions can be mixed, but please keep the [recommended best practices](../best-practices.md#mixing-stac-versions) in mind. +**id**: It is important that an ID is unique within a collection, as the item ID plus the collection (ID plus the +[Provider](../collection-spec/collection-spec.md#provider-object)) gives us a globally unique ID. As most geospatial assets are already uniquely defined by some +identification scheme from the data provider it is recommended to simply use that ID. Data providers are advised to include sufficient information to make their +IDs globally unique, including things like unique satellite IDs. See the [id section of best practices](../best-practices.md#field-and-id-formatting) for +additional recommendations. + **stac_extensions**: A list of extensions the Item implements. The list contains URLs to the JSON Schema files it can be validated against. For official [content extensions](../extensions/README.md#list-of-content-extensions), a "shortcut" can be used. This means you can specify the folder name of the extension, for example `pointcloud` for the Point Cloud extension. This does *not* apply for API extensions. If the versions of the extension and the item diverge, you can specify the URL of the JSON schema file. This list must only contain extensions that extend the Item itself, see the the 'Scope' column in the list of extensions. If an extension such as the `eo` extension has influence on multiple parts of the whole catalog structure, it must be listed in all affected parts (e.g. Collection and Item for the `eo` extension). From 9f7cc1bc9ecbeea869e0ffe7ac3d3b8f02bde36b Mon Sep 17 00:00:00 2001 From: Chris Holmes Date: Tue, 23 Feb 2021 21:23:00 -0800 Subject: [PATCH 2/5] updates based on PR comments, added h4s for linking --- collection-spec/collection-spec.md | 8 +++++++- item-spec/item-spec.md | 31 +++++++++++++++++++++++------- 2 files changed, 31 insertions(+), 8 deletions(-) diff --git a/collection-spec/collection-spec.md b/collection-spec/collection-spec.md index 4b49e1020..3224e3df9 100644 --- a/collection-spec/collection-spec.md +++ b/collection-spec/collection-spec.md @@ -19,7 +19,7 @@ STAC Collections are meant to be compatible with *OGC API - Features* Collection | --------------- | ------------------------------------------------ | ------------------------------------------------ | | stac_version | string | **REQUIRED.** The STAC version the Collection implements. STAC versions can be mixed, but please keep the [recommended best practices](../best-practices.md#mixing-stac-versions) in mind. | | 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 the provider, ideally globally unique. | | 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. | @@ -31,6 +31,12 @@ STAC Collections are meant to be compatible with *OGC API - Features* Collection ### Additional Field Information +#### 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. + #### stac_extensions A list of extensions the Collection implements. This does NOT declare the extensions of child Catalogs or Items. The list contains URLs to the JSON Schema files it can be validated against. For official [extensions](../extensions/README.md#list-of-stac-extensions), a "shortcut" can be used. This means you can specify the folder name of the extension, for example `version` for the Versioning Indicators extension. If the versions of the extension and the collection diverge, you can specify the URL of the JSON schema file. diff --git a/item-spec/item-spec.md b/item-spec/item-spec.md index ffac09d8f..81ff8099a 100644 --- a/item-spec/item-spec.md +++ b/item-spec/item-spec.md @@ -31,7 +31,7 @@ inherited from GeoJSON. | ---------- | -------------------------------------------------------------------------- | ----------- | | 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. If the item is part of a [Collection](../collection-spec/README.md) its ID should be unique within that collection. | +| id | string | **REQUIRED.** Provider identifier. The ID should be unique within the [Collection](../collection-spec/README.md) that contains the item. | | type | string | **REQUIRED.** Type of the GeoJSON Object. MUST be set to `Feature`. | | 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). | @@ -40,18 +40,33 @@ inherited from GeoJSON. | assets | Map | **REQUIRED.** Dictionary of asset objects that can be downloaded, each with a unique key. | | collection | string | The `id` of the STAC Collection this Item references to (see [`collection` relation type](#relation-types)). This field is *required* if such a relation type is present. This field provides an easy way for a user to search for any Items that belong in a specified Collection. | -**stac_version**: In general, STAC versions can be mixed, but please keep the [recommended best practices](../best-practices.md#mixing-stac-versions) in mind. +### Additional Field Information -**id**: It is important that an ID is unique within a collection, as the item ID plus the collection (ID plus the -[Provider](../collection-spec/collection-spec.md#provider-object)) gives us a globally unique ID. As most geospatial assets are already uniquely defined by some +#### stac_version + +In general, STAC versions can be mixed, but please keep the [recommended best practices](../best-practices.md#mixing-stac-versions) in mind. + +#### id + +It is important that an Item identifier is unique within a collection, and that the +[Collection identifier](../collection-spec/collection-spec.md#id) in turn is unique globally. Then the two can be combined to +give a globally unique identifier. Items are *[strongly recommended](#collections)* to have collections, and not having one makes +it more difficult to be used in the wider STAC ecosystem. If an Item does not have a collection then it should strive to provide +a globally unique identifier, with a long, unique prefix, to have a better chance of being globally unique. + +As most geospatial assets are already uniquely defined by some identification scheme from the data provider it is recommended to simply use that ID. Data providers are advised to include sufficient information to make their IDs globally unique, including things like unique satellite IDs. See the [id section of best practices](../best-practices.md#field-and-id-formatting) for additional recommendations. -**stac_extensions**: A list of extensions the Item implements. The list contains URLs to the JSON Schema files it can be validated against. For official [extensions](../extensions/README.md#list-of-stac-extensions), a "shortcut" can be used. This means you can specify the folder name of the extension, for example `pointcloud` for the Point Cloud extension. This does *not* apply for API extensions. If the versions of the extension and the item diverge, you can specify the URL of the JSON schema file. +#### stac_extensions + +A list of extensions the Item implements. The list contains URLs to the JSON Schema files it can be validated against. For official [extensions](../extensions/README.md#list-of-stac-extensions), a "shortcut" can be used. This means you can specify the folder name of the extension, for example `pointcloud` for the Point Cloud extension. This does *not* apply for API extensions. If the versions of the extension and the item diverge, you can specify the URL of the JSON schema file. This list must only contain extensions that extend the Item itself, see the the 'Scope' column in the list of extensions. If an extension such as the `tiled-assets` extension has influence on multiple parts of the whole catalog structure, it must be listed in all affected parts (e.g. Catalog, Collection and Item for the `tiled-assets` extension). -**assets**: Dictionary of asset objects that can be downloaded, each with a unique key. +#### assets + +Dictionary of asset objects that can be downloaded, each with a unique key. In general, the keys don't have any meaning and are considered to be non-descriptive unique identifiers. Providers may assign any meaning to the keys for their respective use cases, but must not expect that clients understand them. To communicate the purpose of an asset better use the `roles` field in the [Asset Object](#asset-object). @@ -62,7 +77,9 @@ by multiple files - all should be linked to. It is generally recommended that di levels or formats are not exhaustively listed in an Item, but instead are represented by related Items that are linked to, but the best practices around this are still emerging. -**bbox**: Bounding Box of the asset represented by this item using either 2D or 3D geometries, formatted according to [RFC 7946, section 5](https://tools.ietf.org/html/rfc7946#section-5). The length of the array must be 2*n where n is the number of dimensions. The array contains all axes of the southwesterly most extent followed by all axes of the northeasterly most extent specified in Longitude/Latitude or Longitude/Latitude/Elevation based on [WGS 84](http://www.opengis.net/def/crs/OGC/1.3/CRS84). When using 3D geometries, the elevation of the southwesterly most extent is the minimum depth/height in meters and the elevation of the northeasterly most extent is the maximum. This field enables more naive clients to easily index and search geospatially. STAC compliant APIs are required to compute intersection operations with the item's geometry field, not its bbox. +#### bbox + +Bounding Box of the asset represented by this item using either 2D or 3D geometries, formatted according to [RFC 7946, section 5](https://tools.ietf.org/html/rfc7946#section-5). The length of the array must be 2\*n where n is the number of dimensions. The array contains all axes of the southwesterly most extent followed by all axes of the northeasterly most extent specified in Longitude/Latitude or Longitude/Latitude/Elevation based on [WGS 84](http://www.opengis.net/def/crs/OGC/1.3/CRS84). When using 3D geometries, the elevation of the southwesterly most extent is the minimum depth/height in meters and the elevation of the northeasterly most extent is the maximum. This field enables more naive clients to easily index and search geospatially. STAC compliant APIs are required to compute intersection operations with the item's geometry field, not its bbox. ### Properties Object From a9c6fe3c231b3e2d4d6e440ff5ac3aeaca157d7a Mon Sep 17 00:00:00 2001 From: Chris Holmes Date: Tue, 23 Feb 2021 21:24:28 -0800 Subject: [PATCH 3/5] changelog update --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index bac193b3e..097119f72 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -28,6 +28,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. - `proj:geometry` allows all GeoJSON geometries instead of just a polygon. - `label:description` and `processing:lineage` allow CommonMark for rich-text representation ([#950](https://github.com/radiantearth/stac-spec/issues/950)) - Renamed "Scientific Extension" to "Scientific Citation Extension" ([#990](https://github.com/radiantearth/stac-spec/issues/990)) +- Enhanced the way the spec talks about ID's to encourage more global uniqueness. ### Removed From 021021377d6a5d6be454c4f53ef950cfbeb0f968 Mon Sep 17 00:00:00 2001 From: Chris Holmes Date: Thu, 25 Feb 2021 14:41:58 -0800 Subject: [PATCH 4/5] Update item-spec/item-spec.md Co-authored-by: Rob Emanuele --- item-spec/item-spec.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/item-spec/item-spec.md b/item-spec/item-spec.md index 81ff8099a..361ab4048 100644 --- a/item-spec/item-spec.md +++ b/item-spec/item-spec.md @@ -51,8 +51,7 @@ In general, STAC versions can be mixed, but please keep the [recommended best pr It is important that an Item identifier is unique within a collection, and that the [Collection identifier](../collection-spec/collection-spec.md#id) in turn is unique globally. Then the two can be combined to give a globally unique identifier. Items are *[strongly recommended](#collections)* to have collections, and not having one makes -it more difficult to be used in the wider STAC ecosystem. If an Item does not have a collection then it should strive to provide -a globally unique identifier, with a long, unique prefix, to have a better chance of being globally unique. +it more difficult to be used in the wider STAC ecosystem. If an Item does not have a Collection, then the Item identifier should be unique within its root Catalog. As most geospatial assets are already uniquely defined by some identification scheme from the data provider it is recommended to simply use that ID. Data providers are advised to include sufficient information to make their From 8a620b7571ec2497b9debe1b8de0f54899c904d8 Mon Sep 17 00:00:00 2001 From: Chris Holmes Date: Thu, 25 Feb 2021 14:42:08 -0800 Subject: [PATCH 5/5] Update collection-spec/collection-spec.md Co-authored-by: Rob Emanuele --- 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 3224e3df9..d5a71601b 100644 --- a/collection-spec/collection-spec.md +++ b/collection-spec/collection-spec.md @@ -19,7 +19,7 @@ STAC Collections are meant to be compatible with *OGC API - Features* Collection | --------------- | ------------------------------------------------ | ------------------------------------------------ | | stac_version | string | **REQUIRED.** The STAC version the Collection implements. STAC versions can be mixed, but please keep the [recommended best practices](../best-practices.md#mixing-stac-versions) in mind. | | stac_extensions | \[string] | A list of extension identifiers the Collection implements. | -| id | string | **REQUIRED.** Identifier for the collection that is unique across the provider, ideally globally unique. | +| id | string | **REQUIRED.** Identifier for the collection that is unique across the provider. | | 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. |