Merge pull request #1008 from radiantearth/collection-assets

Collection assets to core

.github/CODEOWNERS

@@ -13,7 +13,6 @@
 #
 # https://docs.github.com/en/free-pro-team@latest/github/creating-cloning-and-archiving-repositories/about-code-owners
 
-/extensions/collection-assets/ @m-mohr
 /extensions/datacube/ @m-mohr
 /extensions/eo/ @matthewhanson
 /extensions/file/ @m-mohr

CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 ### Added
 
 - 'via' and 'canonical' rel types as options in items.
+- Assets on Collections are now defined in the core Collection specification ([#1008](https://github.com/radiantearth/stac-spec/pull/1008))
 - Added clarification about how collection-level asset object properties do not remove the need for item-level asset object properties in the `item-assets` extension ([#880](https://github.com/radiantearth/stac-spec/pull/880))
 - Added [processing extension](extensions/processing/README.md)
 - Added [file info extension](extensions/file/README.md) ([#879](https://github.com/radiantearth/stac-spec/pull/879), [#921](https://github.com/radiantearth/stac-spec/issues/921))
@@ -33,6 +34,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 ### Removed
 
 - Checksum extension (field `checksum:multihash`). Use File Info extension (field `file:checksum`) instead for assets. There's no replacement for links.
+- Collection Assets extension, as the core construct of Assets in a Collection is now part of the core Collection spec. No change is required except removing `collection-assets` from the list of `stac_extensions`.
 
 ### Fixed
 

best-practices.md

@@ -126,7 +126,8 @@ not spatial. This use case is not currently supported by STAC, as we are focused
 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.
+does. Using [collection assets](collection-spec/collection-spec.md#asset-object) may also provide an option for some 
+use cases.
 
 ## Representing Vector Layers in STAC
 

collection-spec/collection-spec.md

@@ -17,19 +17,20 @@ STAC Collections are meant to be compatible with *OGC API - Features* Collection
 
 ## Collection fields
 
-| Element         | Type                                             | Description                                      |
-| --------------- | ------------------------------------------------ | ------------------------------------------------ |
+| Element         | Type                                             | Description                                                  |
+| --------------- | ------------------------------------------------ | ------------------------------------------------------------ |
 | stac_version    | string                                           | **REQUIRED.** The STAC version the Collection implements. STAC versions can be mixed, but please keep the [recommended best practices](../best-practices.md#mixing-stac-versions) in mind. |
-| stac_extensions | \[string]                                        | A list of extension identifiers the Collection implements. |
+| stac_extensions | \[string]                                        | A list of extension identifiers the Collection implements.   |
 | id              | string                                           | **REQUIRED.** Identifier for the collection that is unique across the provider. |
 | title           | string                                           | A short descriptive one-line title for the collection.       |
 | description     | string                                           | **REQUIRED.** Detailed multi-line description to fully explain the collection. [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for rich text representation. |
 | keywords        | \[string]                                        | List of keywords describing the collection.                  |
 | license         | string                                           | **REQUIRED.** Collection's license(s), either a SPDX [License identifier](https://spdx.org/licenses/), `various` if multiple licenses apply or `proprietary` for all other cases. |
 | providers       | \[[Provider Object](#provider-object)]           | A list of providers, which may include all organizations capturing or processing the data or the hosting provider. Providers should be listed in chronological order with the most recent provider being the last element of the list. |
-| extent          | [Extent Object](#extent-object)                  | **REQUIRED.** Spatial and temporal extents.    |
+| extent          | [Extent Object](#extent-object)                  | **REQUIRED.** Spatial and temporal extents.                  |
 | summaries       | Map<string, \[*]\|[Stats Object](#stats-object)> | STRONGLY RECOMMENDED. A map of property summaries, either a set of values or statistics such as a range. |
 | links           | \[[Link Object](#link-object)]                   | **REQUIRED.** A list of references to other documents.       |
+| assets          | Map<string, [Asset Object](#asset-object)>       | **REQUIRED.** Dictionary of asset objects that can be downloaded, each with a unique key. |
 
 ### Additional Field Information
 
@@ -60,6 +61,32 @@ It is recommended to list as many properties as reasonable so that consumers get
 
 See the examples folder for collections with summaries to get a sense of how to use them. 
 
+#### assets
+
+This provides an optional mechanism to expose assets that don't make sense at the Item level.
+It is a dictionary of [Asset Objects](#asset-object) associated with the Collection that can be
+downloaded or streamed, each with a unique key.
+In general, the keys don't have any meaning and are considered to be non-descriptive unique identifiers.
+Providers may assign any meaning to the keys for their respective use cases, but must not expect that clients understand them.
+To communicate the purpose of an asset better use the `roles` field in the [Asset Object](#asset-object).
+The definition provided here, at the Collection level, is the same as the
+[Asset Object in Items](../item-spec/item-spec.md#asset-object).
+
+There are a few guidelines for using the asset construct at the Collection level:
+
+* Collection-level assets SHOULD NOT list any files also available in items.
+* If possible, item-level assets are always the preferable way to expose assets.
+* To list what assets are available in items see the [Item Assets Definition Extension](../extensions/item-assets/README.md).
+
+Collection-level assets can be useful in some scenarios, for example:
+1. Exposing additional data that applies collection-wide and you don't want to expose it in each Item. This can be collection-level metadata or a thumbnail for visualization purposes.
+2. Individual items can't properly be distinguished for some data structures, e.g. [Zarr](https://zarr.readthedocs.io/) as it's a data structure not contained in single files.
+3. Exposing assets for "[Standalone Collections](https://github.com/radiantearth/stac-spec/blob/master/collection-spec/collection-spec.md#standalone-collections)".
+
+Oftentimes it is possible to model data and assets with either a Collection or an Item. In those scenarios we *recommend* to use
+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.
+
 ### Extent Object
 
 The object describes the spatio-temporal extents of the Collection. Both spatial and temporal extents are required to be specified.
@@ -150,6 +177,20 @@ A more complete list of possible `rel` types and their meaning in STAC can be fo
 
 **Note:** The [STAC Catalog specification](../catalog-spec/catalog-spec.md) requires a link to at least one `item` or `child` catalog. This is *not* a requirement for collections, but *recommended*. In contrast to catalogs, it is **REQUIRED** that items linked from a Collection MUST refer back to its Collection with the [`collection` relation type](../item-spec/item-spec.md#relation-types).
 
+### Asset Object
+
+An Asset is an object that contains a URI to data associated with the Collection that can be downloaded
+or streamed. The definition provided here, at the Collection level, is the same as the
+[Asset Object in Items](../item-spec/item-spec.md#asset-object). It is allowed to add additional fields.
+
+| Field Name  | Type      | Description |
+| ----------- | --------- | ----------- |
+| href        | string    | **REQUIRED.** URI to the asset object. Relative and absolute URI are both allowed. |
+| 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](../item-spec/item-spec.md#asset-media-type) of the asset. See the [common media types](../best-practices.md#common-media-types-in-stac) in the best practice doc for commonly used asset types. |
+| roles       | \[string] | The [semantic roles](../item-spec/item-spec.md#asset-role-types) of the asset, similar to the use of `rel` in links. |
+
 ### Stats Object
 
 For a good understanding of the summarized field, statistics can be added. By default, only ranges with a minimum and a maximum value can be specified.
@@ -179,7 +220,6 @@ The data provider is free to decide, which fields are reasonable to be used.
 
 Commonly used extensions for the STAC Collection specification:
 
-* [Collection Assets](../extensions/collection-assets/README.md): Adds downloadable assets to Collections.
 * [Item Assets Definition](../extensions/item-assets/README.md): Allows to indicate the structure of the Item assets.
 * [Scientific Citation extension](../extensions/scientific/README.md): Add fields to indicate citations and DOIs.
 * [Versioning Indicators extension](../extensions/version/README.md): Allows versioning by adding the fields `version` and `deprecated`.

collection-spec/json-schema/collection.json

@@ -155,6 +155,9 @@
               }
             }
           }
+        },
+        "assets": {
+          "$ref": "../../item-spec/json-schema/item.json#/definitions/assets"
         }
       }
     }

examples/collection-only/collection.json

@@ -43,6 +43,16 @@
       ]
     }
   },
+  "assets": {
+    "thumbnail": {
+      "href": "thumbnail.png",
+      "title": "Preview",
+      "type": "image/png",
+      "roles": [
+        "thumbnail"
+      ]
+    }
+  },
   "summaries": {
     "datetime": {
       "minimum": "2015-06-23T00:00:00Z",

extensions/README.md

@@ -56,7 +56,6 @@ These extensions add new fields or semantics to STAC objects.
 
 | Extension Title                                  | Identifier        | Field Name Prefix   | Scope                     | Maturity   | Description |
 | ------------------------------------------------ | ----------------- | ------------------- | ------------------------- | ---------- | ----------- |
-| [Collection Assets](collection-assets/README.md) | collection-assets | -                   | Collection                | *Proposal* | Provides a way to specify assets available on the collection-level. |
 | [Data Cube](datacube/README.md)                  | datacube          | cube                | Item, Collection          | *Proposal* | Data Cube related metadata, especially to describe their dimensions. |
 | [Electro-Optical](eo/README.md)                  | eo                | eo                  | Item                      | *Proposal* | Covers electro-optical data that represents a snapshot of the Earth for a single date and time. It could consist of multiple spectral bands, for example visible bands, infrared bands, red edge bands and panchromatic bands. The extension provides common fields like bands, cloud cover, gsd and more. |
 | [File Info](file/README.md)                      | file              | file                | Item, Catalog, Collection | *Proposal* | Provides a way to specify file details such as size, data type and checksum for assets and links in Items, Catalogs and Collections. |

extensions/file/README.md

@@ -7,7 +7,9 @@
 - **Extension [Maturity Classification](../README.md#extension-maturity): Proposal**
 - **Owner**: @m-mohr
 
-Provides a way to specify file related details such as checksum, data type and size for assets in [STAC Items](../../item-spec/item-spec.md) and [STAC Collections](../../collection-spec/collection-spec.md) implementing the [Collection Assets](../collection-assets/README.md) extension.
+Provides a way to specify file related details such as checksum, data type and size for assets in 
+[STAC Items](../../item-spec/item-spec.md) as well as [STAC Collections](../../collection-spec/collection-spec.md) 
+that implement [collection-level assets](../../collection-spec/collection-spec.md#asset-object).
 
 - Examples:
   - [Item Assets](examples/item.json)

extensions/file/examples/collection.json

@@ -1,7 +1,6 @@
 {
   "stac_version": "1.0.0-beta.2",
   "stac_extensions": [
-    "collection-assets",
     "file"
   ],
   "id": "example",