Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
- JSON-schema file in the Point Cloud extension.

### Changes
- Clarification on null geometries, making bbox not required if a null geometry is used.
- Multiple extents (bounding boxes / intervals) are allowed per Collection

### Removed
Expand Down
40 changes: 40 additions & 0 deletions best-practices.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@
* [Field and ID formatting](#field-and-id-formatting)
* [Field selection and Metadata Linking](#field-selection-and-metadata-linking)
* [Datetime selection](#datetime-selection)
* [Unlocated Items](#unlocated-items)
* [Representing Vector Layers in STAC](#representing-vector-layers-in-stac)
* [Common Use Cases of Additional Fields for Assets](#common-use-cases-of-additional-fields-for-assets)
* [Static and Dynamic Catalogs](#static-and-dynamic-catalogs)
Expand Down Expand Up @@ -69,6 +70,45 @@ might choose to have `datetime` be the start. The key is to put in a date and ti
the focus of STAC. If `datetime` is set to `null` then it is strongly recommended to use it in conjunction with a content extension
that explains why it should not be set for that type of data.

## Unlocated Items

Though the [GeoJSON standard](https://tools.ietf.org/html/rfc7946) allows null geometries, in STAC we strongly recommend
that every item have a geometry, since the general expectation of someone using a SpatioTemporal Catalog is to be able to query
all data by space and time. But there are some use cases where it can make sense to create a STAC Item before it gets
a geometry. The most common of these is 'level 1' satellite data, where an image is downlinked and cataloged before it has
been geospatially located.

The recommendation for data that does not yet have a location is to follow the GeoJSON concept that it is an ['unlocated'
feature](https://tools.ietf.org/html/rfc7946#section-3.2). So if the catalog has data that is not located then it can follow
GeoJSON and set the geometry to null. Though normally required, in this case the `bbox` field should not be included.

Note that this recommendation is only for cases where data does not yet have a geometry and it cannot be estimated. There
are further details on the two most commonly requested desired use cases for setting geometry to null:

### Unrectified Satellite Data

Most satellite data is downlinked without information that precisely describes where it is located on earth. A satellite
imagery processing pipeline will always attempt to locate it, but often that process takes a number of hours, or never
quite completes (like when it is too cloudy). It can be useful to start to populate the Item before it has a geometry.
In this case the recommendation is to use the 'estimated' position from the satellite, to populate at least the bounding box,
and use the same broad bounds for the geometry (or leaving it null) until there is precise ground lock. This estimation is
usually done by onboard equipment, like GPS or star trackers, but can be off by kilometers or more. But it is very useful for
STAC users to be able to at least find approximate area in their searches. A commonly used field for communicating ground lock
is not yet established, but likely should be (an extension proposal would be appreciated). If there is no way to provide an
estimate then the data then a null geometry with no `bbox` can be used, as described above. But the data will likely not
show up in STAC API searches, as most will at least implicitly use a geometry. Though this section is written with
satellite data in mind, one can easily imagine other data types that start with a less precise geometry but have it
refined after processing.

### Data that is not spatial

The other case that often comes up is people who love STAC and want to use it to catalog everything they have, even if it is
not spatial. This use case is not currently supported by STAC, as we are focused on data that is both temporal and spatial
in nature. The [OGC API - Records](https://github.com/opengeospatial/ogcapi-records) is an emerging standard that likely
will be able to handle a wider range of data to catalog than STAC. It builds on [OGC API -
Features](https://github.com/opengeospatial/ogcapi-features) just like [STAC API](https://github.com/radiantearth/stac-api-spec/)
does. The [collection assets extension](extensions/collection-assets) may also provide an option for some use cases.

## Representing Vector Layers in STAC

Many implementors are tempted to try to use STAC for 'everything', using it as a universal catalog of all their 'stuff'.
Expand Down
4 changes: 2 additions & 2 deletions item-spec/item-spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,8 +33,8 @@ inherited from GeoJSON.
| 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. |
| 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) | **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.** Bounding Box of the asset represented by this item, formatted according to [RFC 7946, section 5](https://tools.ietf.org/html/rfc7946#section-5). |
| 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. |
| assets | Map<string, [Asset Object](#asset-object)> | **REQUIRED.** Dictionary of asset objects that can be downloaded, each with a unique key. |
Expand Down
63 changes: 46 additions & 17 deletions item-spec/json-schema/item.json
Original file line number Diff line number Diff line change
Expand Up @@ -34,14 +34,59 @@
{
"$ref": "https://geojson.org/schema/Feature.json"
},
{
"oneOf": [
{
"type": "object",
"required": [
"geometry",
"bbox"
],
"properties": {
"geometry": {
"$ref": "https://geojson.org/schema/Geometry.json"
},
"bbox": {
"type": "array",
"oneOf": [
{
"minItems": 4,
"maxItems": 4
},
{
"minItems": 6,
"maxItems": 6
}
],
"items": {
"type": "number"
}
}
}
},
{
"type": "object",
"required": [
"geometry"
],
"properties": {
"geometry": {
"type": "null"
},
"bbox": {
"not": {}
}
}
}
]
},
{
"type": "object",
"required": [
"stac_version",
"id",
"links",
"assets",
"bbox",
"properties"
],
"properties": {
Expand Down Expand Up @@ -73,22 +118,6 @@
"description": "Provider item ID",
"type": "string"
},
"bbox": {
"type": "array",
"oneOf": [
{
"minItems": 4,
"maxItems": 4
},
{
"minItems": 6,
"maxItems": 6
}
],
"items": {
"type": "number"
}
},
"links": {
"title": "Item links",
"description": "Links to item relations",
Expand Down