Skip to content

Commit

Permalink
Merge branch 'dev' into nomultiparents
Browse files Browse the repository at this point in the history
  • Loading branch information
@emmanuelmathot
emmanuelmathot authored Jul 17, 2024
2 parents 8f16ded + 8976aed commit 06445ab
Show file tree
Hide file tree
Showing 13 changed files with 199 additions and 49 deletions.
4 changes: 4 additions & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,9 +10,12 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
### Added

- The `keywords` field known from Collections is available in common metadata. ([#1187](https://github.com/radiantearth/stac-spec/issues/1187))
- New fields `method`, `headers` and `body` in the Link Object. ([#1198](https://github.com/radiantearth/stac-spec/issues/1198))
- The `license` field additionally supports SPDX expressions and the value `other`.
- The `roles` field known from Assets and Providers is available in common metadata. ([#1267](https://github.com/radiantearth/stac-spec/issues/1267))
- The `collection` relation type is added to the list of known relation types. ([#1236](https://github.com/radiantearth/stac-spec/issues/1236))
- The `item_assets` field in Collections are integrated from extension into the core Collection spec. ([#1275](https://github.com/radiantearth/stac-spec/issues/1275))
- Validation for absolute self link in item schema. ([#1281](https://github.com/radiantearth/stac-spec/issues/1281))
- Best practice: Link titles should exactly reflect the title of the corresponding entity ([#1168](https://github.com/radiantearth/stac-spec/issues/1168))

### Changed
Expand Down Expand Up @@ -40,6 +43,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
- Several typos and minor language changes
- Clarification on unique parent link requirement ([#1279](https://github.com/radiantearth/stac-spec/pull/1279))
- Clarified that collection IDs should be unique across all collections in the corresponding root catalog
- Clarified that item IDs should be unique per collection
- 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))
Expand Down
7 changes: 4 additions & 3 deletions best-practices.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -182,9 +182,10 @@ The relative URLs `folder/item.json` and `./folder/item.json` are equivalent.

When defining one's STAC properties and fields there are many choices to make on how to name various aspects of one's
data. One of the key properties is the ID. The specification is quite flexible on ID's, primarily so that existing
providers can easily use their same ID when they translate their data into STAC - they just need to be sure it is globally
unique, so may need a prefix. But the use of URI or file path reserved characters such as `:` or `/` is discouraged since this will
result in [percented encoded](https://tools.ietf.org/html/rfc3986#section-2) [STAC API](https://github.com/radiantearth/stac-api-spec)
providers can easily use their same ID when they translate their data into STAC.
It is STRONGLY RECOMMENDED that an item ID is unique per collection.
The use of URI or file path reserved characters such as `:` or `/` is discouraged since this will
result in [percented encoded](https://tools.ietf.org/html/rfc3986#section-2) [STAC API](https://github.com/radiantearth/stac-api-spec)
endpoints and it prevents the use of IDs as file names as recommended in the [catalog layout](#catalog-layout) best practices.

### Searchable Identifiers
Expand Down
13 changes: 1 addition & 12 deletions catalog-spec/catalog-spec.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -68,18 +68,7 @@ This must **not** declare the extensions that are only implemented in child Coll

### Link Object

This object describes a relationship with another entity. Data providers are advised to be liberal
with links.

| Field Name | Type | Description |
| ---------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| href | string | **REQUIRED.** The actual link in the format of an URL. Relative and absolute links are both allowed. [Trailing slashes are significant.](../best-practices.md#consistent-uris) |
| rel | string | **REQUIRED.** Relationship between the current document and the linked document. See chapter ["Relation types"](#relation-types) for more information. |
| type | string | [Media type](#media-types) of the referenced entity. |
| title | string | A human readable title to be used in rendered displays of the link. |

For a full discussion of the situations where relative and absolute links are recommended see the
['Use of links'](../best-practices.md#use-of-links) section of the STAC best practices.
This object is described in the [STAC Common Metadata](../item-spec/common-metadata.md#link-object) section.

#### Relation types

Expand Down
4 changes: 4 additions & 0 deletions collection-spec/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -44,3 +44,7 @@ a collection and be able to adapt it to most any data model.

Implementors are encouraged to do what makes sense for them, and to check out the [examples](../examples/) and
[other implementations](https://stacindex.org/catalogs) for current best practices.
> \[!NOTE]
> In cases where a set of Collections is grouped together (e.g. for providing search results),
> the [CollectionCollection](https://github.com/radiantearth/stac-api-spec/blob/main/fragments/collectioncollection/README.md)
> object has been defined in the STAC API specification.
55 changes: 44 additions & 11 deletions collection-spec/collection-spec.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -58,6 +58,7 @@ specified in [*OGC API - Features*](https://ogcapi.ogc.org/features/), but they
| summaries | Map<string, \[\*]\|[Range Object](#range-object)\|[JSON Schema Object](#json-schema-object)> | STRONGLY RECOMMENDED. A map of property summaries, either a set of values, a range of values or a [JSON Schema](https://json-schema.org). |
| links | \[[Link Object](#link-object)] | **REQUIRED.** A list of references to other documents. |
| assets | Map<string, [Asset Object](#asset-object)> | Dictionary of asset objects that can be downloaded, each with a unique key. |
| item_assets | Map<string, [Item Asset Definition Object](#item-asset-definition-object)> | **REQUIRED.** A dictionary of assets that can be found in member Items. |

### Additional Field Information

Expand Down Expand Up @@ -161,6 +162,21 @@ Oftentimes it is possible to model data and assets with either a Collection or a
Items as much as is feasible, as they designed for assets. Using Collection-level assets should only be used if there is not another
option.

#### Item Asset Defintion

This serves two purposes:

1. Provide a human-readable definition of assets available in **any** Items
belonging to this Collection so that the user can determine the key(s)
of assets they are interested in.
2. Provide a way to programmatically determine what assets are available
in **any** member Item. Otherwise a random Item needs to be examined to
determine assets available, but a random Item may not be representative of the set.

An Item Asset Object defined at the Collection level is nearly the same as the
[Asset Object in Items](../item-spec/item-spec.md#asset-object), except for two differences.
The `href` field is not required, because Item Asset Definitions don't point to any data by themselves, but at least two other fields must be present.

### Extent Object

The object describes the spatio-temporal extents of the Collection. Both spatial and temporal extents are required to be specified.
Expand Down Expand Up @@ -249,17 +265,7 @@ May also include information about the final storage provider hosting the data.

### Link Object

This object describes a relationship with another entity. Data providers are advised to be liberal with links.

| Field Name | Type | Description |
| ---------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| href | string | **REQUIRED.** The actual link in the format of an URL. Relative and absolute links are both allowed. [Trailing slashes are significant.](../best-practices.md#consistent-uris) |
| rel | string | **REQUIRED.** Relationship between the current document and the linked document. See chapter "[Relation types](#relation-types)" for more information. |
| type | string | [Media type](../catalog-spec/catalog-spec.md#media-types) of the referenced entity. |
| title | string | A human readable title to be used in rendered displays of the link. |

For a full discussion of the situations where relative and absolute links are recommended see the
['Use of links'](../best-practices.md#use-of-links) section of the STAC best practices.
This object is described in the [STAC Common Metadata](../item-spec/common-metadata.md#link-object) section.

#### Relation types

Expand Down Expand Up @@ -300,6 +306,33 @@ Commonly used are `thumbnail` and `overview`.
Note that multiple roles per asset are encouraged: pick all the ones that apply.
For more information on how to use roles see the [Asset Roles](../best-practices.md#asset-roles) section of the Best Practices document.

### Item Asset Definition Object

An item asset is an object that contains details about the datafiles that will be included in member Items.
Assets included at the Collection level do not imply that all assets are available from all Items.
However, it is recommended that the Asset Definition is a complete set of **all** assets that may be available from **any** member Items.
So this should be the union of the available assets, not just the intersection of the available assets.

| Field Name | Type | Description |
| ----------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| title | string | The displayed title for clients and users. |
| description | string | A description of the Asset providing additional details, such as how it was processed or created. [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for rich text representation. |
| type | string | [Media type](../catalog-spec/catalog-spec.md#media-types) of the asset. |
| roles | \[string] | The [semantic roles](../item-spec/item-spec.md#asset-roles) of the asset, similar to the use of `rel` in links. |

Other custom fields, or fields from other extensions may also be included in the Asset object.

Any property that exists for a Collection-level asset object must also exist in the corresponding assets object in
each Item. If a collection's asset object contains properties that are not explicitly stated in the Item's asset
object then that property does not apply to the item's asset. Item asset objects at the Collection-level can
describe any of the properties of an asset, but those assets properties and values must also reside in the item's
asset object. To consolidate item-level asset object properties in an API setting, consider storing the STAC Item
objects without the larger properties internally as 'invalid' STAC items, and merge in the desired properties at
serving time from the Collection-level.

At least two fields (e.g. `title` and `type`) are required to be provided, in order for it to adequately describe Item assets.
The two fields must not necessarily be taken from the list above and may include any custom field.

### Range Object

For summaries that would normally consist of a lot of continuous values, statistics can be added instead.
Expand Down
44 changes: 40 additions & 4 deletions collection-spec/json-schema/collection.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -83,12 +83,12 @@
"type": "array",
"oneOf": [
{
"minItems":4,
"maxItems":4
"minItems": 4,
"maxItems": 4
},
{
"minItems":6,
"maxItems":6
"minItems": 6,
"maxItems": 6
}
],
"items": {
Expand Down Expand Up @@ -131,6 +131,42 @@
"assets": {
"$ref": "../../item-spec/json-schema/item.json#/definitions/assets"
},
"item_assets": {
"allOf": [
{
"type": "object",
"minProperties": 2,
"properties": {
"href": {
"title": "Disallow href",
"not": {}
},
"title": {
"title": "Asset title",
"type": "string"
},
"description": {
"title": "Asset description",
"type": "string"
},
"type": {
"title": "Asset type",
"type": "string"
},
"roles": {
"title": "Asset roles",
"type": "array",
"items": {
"type": "string"
}
}
}
},
{
"$ref": "../../item-spec/json-schema/common.json"
}
]
},
"links": {
"$ref": "../../item-spec/json-schema/item.json#/definitions/links"
},
Expand Down
34 changes: 34 additions & 0 deletions examples/collection-only/collection-with-schemas.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -273,5 +273,39 @@
"gsd": 20
}
]
},
"item_assets": {
"B1": {
"title": "Band 1 (coastal)",
"type": "image/tiff; application=geotiff",
"roles": [
"data",
"visual"
]
},
"B2": {
"title": "Band 2 (blue)",
"type": "image/tiff; application=geotiff",
"roles": [
"data",
"visual"
]
},
"B3": {
"title": "Band 3 (green)",
"type": "image/tiff; application=geotiff",
"roles": [
"data",
"visual"
]
},
"B4": {
"title": "Band 4 (red)",
"type": "image/tiff; application=geotiff",
"roles": [
"data",
"visual"
]
}
}
}
2 changes: 1 addition & 1 deletion examples/collection-only/collection.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -230,4 +230,4 @@
"title": "Legal notice on the use of Copernicus Sentinel Data and Service Information"
}
]
}
}
9 changes: 9 additions & 0 deletions item-spec/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,3 +21,12 @@ schemas validate additional fields defined in *[Common Metadata](common-metadata

**Common Metadata:** A set of commonly-used fields for STAC Items is listed in
*[common-metadata.md](common-metadata.md)*.

> \[!NOTE]
> In cases where a set of Items is grouped together (e.g. for providing search results),
> the [ItemCollection](https://github.com/radiantearth/stac-api-spec/blob/main/fragments/itemcollection/README.md)
> object has been defined in the STAC API specification.
>
> Similarly to the relationship between a GeoJSON Feature and a STAC Item,
> a STAC ItemCollection should be a valid GeoJSON [FeatureCollection](https://tools.ietf.org/html/rfc7946#section-3.3)
> to allow interoperability with existing tools that support GeoJSON.
Loading

0 comments on commit 06445ab

Please sign in to comment.