diff --git a/CHANGELOG.md b/CHANGELOG.md index 4da6b229..793971d6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -38,6 +38,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. - Several typos and minor language changes - Clarified that collection IDs should be unique across all collections in the corresponding root catalog - Clarified which media types should be used for the hierarchical relation types +- Clarified in the Markdown specification that GeometryCollections are not allowed as Item Geometry ([#1160](https://github.com/radiantearth/stac-spec/pull/1160)) - Best practice: Do not recommend subdirectories for Items without sidecar files ([#1195](https://github.com/radiantearth/stac-spec/pull/1195)) - Clarified that multiple collections can point to an Item, but an Item can only point back to a single collection. ([#1273](https://github.com/radiantearth/stac-spec/pull/1273)) - Restructured asset role types and clarified usage of the roles `thumbnail`, `overview` and `visual` ([#1272](https://github.com/radiantearth/stac-spec/pull/1272)) diff --git a/best-practices.md b/best-practices.md index c81ad038..c3e6d366 100644 --- a/best-practices.md +++ b/best-practices.md @@ -505,7 +505,8 @@ if you follow these recommendations. 3. Items should be named `.json`. 4. Sub-Catalogs or sub-Collections should be stored in subdirectories of their parent (and only 1 subdirectory deeper than a document's parent, e.g. `.../sample/sub1/catalog.json`). -5. Items should be stored in subdirectories of their parent Catalog or Collection if there are usually [sidecar files](https://en.wikipedia.org/wiki/Sidecar_file) stored alongside the Item. +5. Items should be stored in subdirectories of their parent Catalog or Collection + if there are usually [sidecar files](https://en.wikipedia.org/wiki/Sidecar_file) stored alongside the Item. This means that each Item and its assets are contained in a unique subdirectory unless this would regularly lead to a single Item in a directory. 6. Limit the number of Items in a Catalog or Collection, grouping / partitioning as relevant to the dataset. 7. Use structural elements (Catalog and Collection) consistently across each 'level' of your hierarchy. diff --git a/item-spec/item-spec.md b/item-spec/item-spec.md index e877d71e..316ef193 100644 --- a/item-spec/item-spec.md +++ b/item-spec/item-spec.md @@ -7,7 +7,9 @@ - [stac\_extensions](#stac_extensions) - [id](#id) - [assets](#assets) + - [geometry](#geometry) - [bbox](#bbox) + - [collection](#collection) - [Properties Object](#properties-object) - [datetime](#datetime) - [Additional Fields](#additional-fields) @@ -51,18 +53,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 \| null | **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) if a geometry is provided or [section 3.2](https://tools.ietf.org/html/rfc7946#section-3.2) if *no* geometry is provided. | +| 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. This field is **required** if a link with a `collection` relation type is present and is **not allowed** otherwise. | ### Additional Field Information @@ -106,6 +108,18 @@ 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. +#### geometry + +Defines the full footprint of the asset represented by this item, formatted according to RFC 7946. + +If **a geometry** is provided, the value must be a Geometry Object according to +[RFC 7946, section 3.1](https://tools.ietf.org/html/rfc7946#section-3.1) +with the exception that the type `GeometryCollection` is not allowed in STAC. +If **no geometry** is provided, the value must be `null` according to +[RFC 7946, section 3.2](https://tools.ietf.org/html/rfc7946#section-3.2). + +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 Bounding Box of the asset represented by this Item using either 2D or 3D geometries, @@ -118,6 +132,13 @@ 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. +#### collection + +The `id` of the STAC Collection this Item references to with the [`collection` relation type](#relation-types) in the `links` array. + +This field provides an easy way for a user to search for any Items that belong in a specified Collection. +If present, must be a non-empty string. + ### Properties Object Additional metadata fields can be added to the GeoJSON Object Properties. The only required field