Integrate item_assets field from extension into core Collection spec

CHANGELOG.md

@@ -12,6 +12,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 - The `keywords` field known from Collections is available in common metadata. ([#1187](https://github.com/radiantearth/stac-spec/issues/1187))
 - 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 `item_assets` field in Collections are integrated from extension into the core Collection spec. ([#1275](https://github.com/radiantearth/stac-spec/issues/1275))
 - Best practice: Link titles should exactly reflect the title of the corresponding entity ([#1168](https://github.com/radiantearth/stac-spec/issues/1168))
 
 ### Changed

collection-spec/collection-spec.md

@@ -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
 
@@ -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.
@@ -316,6 +332,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-role-types) 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.

collection-spec/json-schema/collection.json

@@ -83,12 +83,12 @@
                     "type": "array",
                     "oneOf": [
                       {
-                        "minItems":4,
-                        "maxItems":4
+                        "minItems": 4,
+                        "maxItems": 4
                       },
                       {
-                        "minItems":6,
-                        "maxItems":6
+                        "minItems": 6,
+                        "maxItems": 6
                       }
                     ],
                     "items": {
@@ -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"
         },

examples/collection-only/collection-with-schemas.json

@@ -273,5 +273,6 @@
         "gsd": 20
       }
     ]
-  }
+  },
+  "item_assets": {}
 }

examples/collection-only/collection.json

@@ -230,4 +230,4 @@
       "title": "Legal notice on the use of Copernicus Sentinel Data and Service Information"
     }
   ]
-}
+}