What is the role of 'item_assets' in STAC Collections?

We appreciate you taking the time to post your question here. 
The “item_assets” field in a STAC Collection JSON is a crucial metadata component that provides a schema describing the assets (data files) that exist within the collection’s items. It serves as a catalog of what types of data assets users can expect to find in the collection without having to examine individual items. 

This field is implemented through the STAC Item Assets Extension and is required for visualization in Microsoft Planetary Computer Pro’s Explorer interface. 

The “item_assets” field is an object where: 

Each key represents an asset name (like “image”, “B04”, “elevation”) 

• Each value is an object describing that asset’s properties The “item_assets” field is an object where: 
  • Each key represents an asset name (like “image”, “B04”, “elevation”) 
  • Each value is an object describing that asset’s properties 

To create an accurate “item_assets” field: 

Inventory Your Data Assets: Identify all the different types of assets that will be included in your STAC items. 

Examine Sample Items: Look at a few representative STAC items to identify the common asset keys and their properties. 

Include All Possible Assets: The “item_assets” field should represent the union of all possible assets across items, not just those that appear in every item. 

Match Your Data Type: 

For multi-band imagery: Include the eo:bands property with information about each band 

• For single-band data (like elevation): Include properties that describe the data values To create an accurate “item_assets” field: 
  1. Inventory Your Data Assets: Identify all the different types of assets that will be included in your STAC items. 
  2. Examine Sample Items: Look at a few representative STAC items to identify the common asset keys and their properties. 
  3. Include All Possible Assets: The “item_assets” field should represent the union of all possible assets across items, not just those that appear in every item. 
  4. Match Your Data Type: 
  • For multi-band imagery: Include the eo:bands property with information about each band 
  • For single-band data (like elevation): Include properties that describe the data values 
  • For data cubes (NetCDF/GRIB): Include information about variables and dimensions 
  1. Consider Visualization Requirements: Think about how you want to visualize this data in Explorer when determining which properties to include. 
  2. Reference Existing Collections: Study similar collections in the public Microsoft Planetary Computer for examples of well-structured “item_assets” fields. 
     • For data cubes (NetCDF/GRIB): Include information about variables and dimensions 
     1. Consider Visualization Requirements: Think about how you want to visualize this data in Explorer when determining which properties to include. 
     2. Reference Existing Collections: Study similar collections in the public Microsoft Planetary Computer for examples of well-structured “item_assets” fields. 

The relationship between “item_assets” and the Tiler API is critical for visualization: 

Asset Discovery: The Tiler API uses the “item_assets” field to understand what assets are available without having to scan through individual items. 

1. Reference by Key: In render configurations, you reference assets using the exact keys defined in “item_assets”.  The relationship between “item_assets” and the Tiler API is critical for visualization: 
   1. Asset Discovery: The Tiler API uses the “item_assets” field to understand what assets are available without having to scan through individual items. 
   2. Reference by Key: In render configurations, you reference assets using the exact keys defined in “item_assets”.  

For example: 

assets=image&asset_bidx=image|1,2,3 

This tells the Tiler API to use the “image” asset (defined in “item_assets”) and select bands 1, 2, and 3. 

Band Information: For multi-band assets, the Tiler uses the eo:bands information to understand what bands are available and their properties. 

Render Configuration Options: When you create a render configuration like: 

assets=B04&assets=B03&assets=B02 

The Tiler verifies these keys exist in “item_assets” before processing the request. 

Explorer UI Integration: The Explorer interface uses “item_assets” to populate dropdown menus and provide options for visualization. 

1. Asset Validation: When new items are ingested, their asset keys are validated against the “item_assets” schema. For example:  assets=image&asset_bidx=image|1,2,3  This tells the Tiler API to use the “image” asset (defined in “item_assets”) and select bands 1, 2, and 3. 
   1. Band Information: For multi-band assets, the Tiler uses the eo:bands information to understand what bands are available and their properties. 
   2. Render Configuration Options: When you create a render configuration like: 
   assets=B04&assets=B03&assets=B02  The Tiler verifies these keys exist in “item_assets” before processing the request. 
   1. Explorer UI Integration: The Explorer interface uses “item_assets” to populate dropdown menus and provide options for visualization. 
   2. Asset Validation: When new items are ingested, their asset keys are validated against the “item_assets” schema. 

Without a properly defined “item_assets” field, the Tiler API cannot correctly interpret what assets are available or how they should be processed for visualization, resulting in failed render attempts or incomplete Explorer functionality. 

Remember that the “item_assets” field is a schema or template - it doesn’t mean every item has all these assets, but rather describes all possible assets that may exist across the collection