Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Disallow GeometryCollection, reformatting #1294

Merged
merged 6 commits into from
Jul 4, 2024
Merged

Disallow GeometryCollection, reformatting #1294

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
a941824
Disallow GeometryCollection, reformat geometry, bbox, and collection …
m-mohr Jun 27, 2024
9855f21
Merge branch 'dev' into item-spec-bbox-geom
m-mohr Jun 29, 2024
1b488ae
Update item-spec/item-spec.md
m-mohr Jul 1, 2024
ae87c23
Update item-spec/item-spec.md
m-mohr Jul 1, 2024
37afbed
Merge branch 'dev' into item-spec-bbox-geom
m-mohr Jul 1, 2024
5b4c02d
Fix CI
m-mohr Jul 1, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
View file
Open in desktop
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
Open in desktop
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
Open in desktop
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