Skip to content

Commit

Permalink
Merge pull request #1294 from radiantearth/item-spec-bbox-geom
Browse files Browse the repository at this point in the history 
Disallow GeometryCollection, reformatting
  • Loading branch information
@emmanuelmathot
emmanuelmathot authored Jul 4, 2024
2 parents 3b5bf4c + 5b4c02d commit 2055e7c
Show file tree
Hide file tree
Showing 3 changed files with 36 additions and 13 deletions.
1 change: 1 addition & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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))
Expand Down
3 changes: 2 additions & 1 deletion best-practices.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -505,7 +505,8 @@ if you follow these recommendations.
3. Items should be named `<id>.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.
Expand Down
45 changes: 33 additions & 12 deletions item-spec/item-spec.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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<string, [Asset Object](#asset-object)> | **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<string, [Asset Object](#asset-object)> | **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

Expand Down Expand Up @@ -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,
Expand All @@ -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
Expand Down

0 comments on commit 2055e7c

Please sign in to comment.