Integrate item_assets field from extension into core Collection spec

fixes #1275
radiantearth · Jun 27, 2024 · 9104ad6 · 9104ad6
1 parent 3961d47
commit 9104ad6
Show file tree

Hide file tree

Showing 6 changed files with 240 additions and 67 deletions.
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -0,0 +1,3 @@
+{
+    "jira-plugin.workingProject": ""
+}
diff --git a/CHANGELOG.md b/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))
 
 ### Changed
 

diff --git a/collection-spec/collection-spec.md b/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 Object](#item-asset-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 assets
+
+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 Collections 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.
@@ -302,6 +318,32 @@ or streamed. The definition provided here, at the Collection level, is the same
 | 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.                                                                                         |
 
+### Item Asset 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.
+
+| 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.

diff --git a/collection-spec/json-schema/collection.json b/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,45 @@
         "assets": {
           "$ref": "../../item-spec/json-schema/item.json#/definitions/assets"
         },
+        "item_assets": {
+          "allOf": [
+            {
+              "type": "object",
+              "required": [
+                "title",
+                "type"
+              ],
+              "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"
         },

diff --git a/examples/collection-only/collection-with-schemas.json b/examples/collection-only/collection-with-schemas.json
@@ -273,5 +273,6 @@
         "gsd": 20
       }
     ]
-  }
+  },
+  "item_assets": {}
 }
diff --git a/examples/collection-only/collection.json b/examples/collection-only/collection.json
@@ -148,69 +148,156 @@
       32658,
       32659,
       32660
-    ],
-    "eo:bands": [
-      {
-        "name": "B1",
-        "common_name": "coastal",
-        "center_wavelength": 0.4439
-      },
-      {
-        "name": "B2",
-        "common_name": "blue",
-        "center_wavelength": 0.4966
-      },
-      {
-        "name": "B3",
-        "common_name": "green",
-        "center_wavelength": 0.56
-      },
-      {
-        "name": "B4",
-        "common_name": "red",
-        "center_wavelength": 0.6645
-      },
-      {
-        "name": "B5",
-        "center_wavelength": 0.7039
-      },
-      {
-        "name": "B6",
-        "center_wavelength": 0.7402
-      },
-      {
-        "name": "B7",
-        "center_wavelength": 0.7825
-      },
-      {
-        "name": "B8",
-        "common_name": "nir",
-        "center_wavelength": 0.8351
-      },
-      {
-        "name": "B8A",
-        "center_wavelength": 0.8648
-      },
-      {
-        "name": "B9",
-        "center_wavelength": 0.945
-      },
-      {
-        "name": "B10",
-        "center_wavelength": 1.3735
-      },
-      {
-        "name": "B11",
-        "common_name": "swir16",
-        "center_wavelength": 1.6137
-      },
-      {
-        "name": "B12",
-        "common_name": "swir22",
-        "center_wavelength": 2.2024
-      }
     ]
   },
+  "item_assets": {
+    "thumbnail": {
+      "type": "image/jpeg",
+      "title": "Thumbnail",
+      "description": "A medium sized thumbnail",
+      "roles": [
+        "thumbnail"
+      ]
+    },
+    "metadata": {
+      "type": "mtl",
+      "roles": [
+        "metadata"
+      ],
+      "title": "Original Metadata",
+      "description": "The original MTL metadata file provided for each Landsat scene"
+    },
+    "B1": {
+      "type": "image/tiff; application=geotiff",
+      "name": "B1",
+      "title": "Coastal Band (B1)",
+      "description": "Coastal Band Top Of the Atmosphere",
+      "eo:common_name": "coastal",
+      "eo:center_wavelength": 0.443,
+      "eo:full_width_half_max": 0.027,
+      "raster:spatial_resolution": 60
+    },
+    "B2": {
+      "type": "image/tiff; application=geotiff",
+      "name": "B2",
+      "title": "Blue Band (B2)",
+      "description": "Blue Band Top Of the Atmosphere",
+      "eo:common_name": "blue",
+      "eo:center_wavelength": 0.49,
+      "eo:full_width_half_max": 0.098,
+      "raster:spatial_resolution": 10
+    },
+    "B3": {
+      "type": "image/tiff; application=geotiff",
+      "name": "B3",
+      "title": "Green Band (B3)",
+      "description": "Green Band (B3) Top Of the Atmosphere",
+      "eo:common_name": "green",
+      "eo:center_wavelength": 0.56,
+      "eo:full_width_half_max": 0.045,
+      "raster:spatial_resolution": 10
+    },
+    "B4": {
+      "type": "image/tiff; application=geotiff",
+      "name": "B4",
+      "title": "Red Band (B4)",
+      "description": "Red Band (B4) Top Of the Atmosphere",
+      "eo:common_name": "red",
+      "eo:center_wavelength": 0.665,
+      "eo:full_width_half_max": 0.038,
+      "raster:spatial_resolution": 10
+    },
+    "B5": {
+      "type": "image/tiff; application=geotiff",
+      "name": "B5",
+      "title": "Red Edge 1 Band (B5)",
+      "description": "Red Edge 1 Band (B5) Top Of the Atmosphere",
+      "eo:common_name": "rededge1",
+      "eo:center_wavelength": 0.704,
+      "eo:full_width_half_max": 0.019,
+      "raster:spatial_resolution": 20
+    },
+    "B6": {
+      "type": "image/tiff; application=geotiff",
+      "name": "B6",
+      "title": "Red Edge 2 Band (B6)",
+      "description": "Red Edge 2 Band (B6) Top Of the Atmosphere",
+      "eo:common_name": "rededge2",
+      "eo:center_wavelength": 0.74,
+      "eo:full_width_half_max": 0.018,
+      "raster:spatial_resolution": 20
+    },
+    "B7": {
+      "type": "image/tiff; application=geotiff",
+      "name": "B7",
+      "title": "Red Edge 3 Band (B7)",
+      "description": "Red Edge 3 Band (B7) Top Of the Atmosphere",
+      "eo:common_name": "rededge3",
+      "eo:center_wavelength": 0.783,
+      "eo:full_width_half_max": 0.028,
+      "raster:spatial_resolution": 20
+    },
+    "B8": {
+      "type": "image/tiff; application=geotiff",
+      "name": "B8",
+      "title": "NIR Band (B8)",
+      "description": "NIR Band (B8) Top Of the Atmosphere",
+      "eo:common_name": "nir",
+      "eo:center_wavelength": 0.842,
+      "eo:full_width_half_max": 0.145,
+      "raster:spatial_resolution": 10
+    },
+    "B8A": {
+      "type": "image/tiff; application=geotiff",
+      "name": "B8A",
+      "title": "NIR08 Band (B8A)",
+      "description": "NIR08 Band (B8A) Top Of the Atmosphere",
+      "eo:common_name": "nir08",
+      "eo:center_wavelength": 0.865,
+      "eo:full_width_half_max": 0.033,
+      "raster:spatial_resolution": 20
+    },
+    "B9": {
+      "type": "image/tiff; application=geotiff",
+      "name": "B9",
+      "title": "Near-IR Band (B9)",
+      "description": "Near-IR Band at 0.945um (B9) Top Of the Atmosphere",
+      "eo:common_name": "nir09",
+      "eo:center_wavelength": 0.945,
+      "eo:full_width_half_max": 0.026,
+      "raster:spatial_resolution": 60
+    },
+    "B10": {
+      "type": "image/tiff; application=geotiff",
+      "name": "B10",
+      "title": "Cirrus Band (B10)",
+      "description": "Cirrus Band at 1.3735um (B10) Top Of the Atmosphere",
+      "eo:common_name": "cirrus",
+      "eo:center_wavelength": 1.3735,
+      "eo:full_width_half_max": 0.075,
+      "raster:spatial_resolution": 60
+    },
+    "B11": {
+      "type": "image/tiff; application=geotiff",
+      "name": "B11",
+      "title": "SWIR 1 Band (B11)",
+      "description": "SWIR 1 Band at 1.6um (B11) Top Of the Atmosphere",
+      "eo:common_name": "swir16",
+      "eo:center_wavelength": 1.61,
+      "eo:full_width_half_max": 0.143,
+      "raster:spatial_resolution": 20
+    },
+    "B12": {
+      "type": "image/tiff; application=geotiff",
+      "name": "B12",
+      "title": "SWIR 2 Band (B12)",
+      "description": "SWIR 2 Band at 2.2um (B12) Top Of the Atmosphere",
+      "eo:common_name": "swir22",
+      "eo:center_wavelength": 2.19,
+      "eo:full_width_half_max": 0.242,
+      "raster:spatial_resolution": 20
+    }
+  },
   "links": [
     {
       "rel": "parent",
@@ -230,4 +317,4 @@
       "title": "Legal notice on the use of Copernicus Sentinel Data and Service Information"
     }
   ]
-}
+}