RFC: A common construct to replace raster:bands and eo:bands

[m-mohr]

RFC: A common construct to replace raster:bands and eo:bands

Table of contents:

1. Context
2. Problem
   1. Example 1
   2. Example 2
   3. Example 3
3. Proposed solution
4. Naming
   2. Affected specification / extensions
   3. Changes to the STAC specification
   4. Changes to the raster extension
   5. Changes to the EO extension
   6. Changes to the extension template
5. Alternatives considered
6. Open questions
7. Procedure

Context

The EO extension in the very early days of STAC added the field eo:bands, which was meant to describe the spectral characteristics of a band. As it was first, it also defines some non-EO related fields like name and description. On the way to STAC 1.0, @emmanuelmathot proposed the raster extension. It had a construct for raster bands (or layers) in general: raster:bands. The raster extension doesn't define these common fields such as name and description. Other fields like nodata, data_type, statistics and unit also don't feel closely related to only rasters as they could also be used in the table or Datacube extensions.

Problem

Having both extensions around for quite a while now, we see broad adoption of both extensions. Implementations are using both extensions side-by-side or move fields from one extension to the other. Below you can find some examples for assets, which shows issues that have been identified in real world deployments / implementations.

Example 1

This is fully valid and implements the fields as defined:

{
	"visual": {
		"href": "rgb.tif",
		"type": "image/tiff; application=geotiff",
		"title": "4-band RGB",
		"gsd": 10,
		"eo:bands": [{
			"name": "B4",
			"common_name": "red",
			"description": "Red band",
			"center_wavelength": 0.665,
			"full_width_half_max": 0.038
		},{
			"name": "B3",
			"common_name": "green",
			"description": "Green band",
			"center_wavelength": 0.56,
			"full_width_half_max": 0.045
		},{
			"name": "B2",
			"common_name": "blue",
			"description": "Blue band",
			"center_wavelength": 0.49,
			"full_width_half_max": 0.098
		}],
		"raster:bands": [{
			"data_type": "float32",
			"nodata": "nan",
			"statistics": {"minimum": 0, "maximum": 1},
			"spatial_resolution": 10
		},{
			"data_type": "float32",
			"nodata": "nan",
			"statistics": {"minimum": 0, "maximum": 1},
			"spatial_resolution": 10
		},{
			"data_type": "float32",
			"nodata": "nan",
			"statistics": {"minimum": 0, "maximum": 1},
			"spatial_resolution": 10
		},{
			"data_type": "float32",
			"statistics": {"minimum": 0, "maximum": 1}
		}]
	}
}

The issues encountered here are the following:

1. You define a very similar array structure twice
2. For a human and long lists of bands it's not trivial to figure out which element of raster:bands corresponds to which element in eo:bands. Their relation is implicitly expressed by the array index, but that's not shown in JSON and as such you'd need to count the elements get the index.
3. If you have a quality band (the fourth element in raster:bands), it should - strictly speaking - not be in eo:bands as it is not a spectral band. This leads to a mismatch and it makes it less trivial to merge the bands. Also, the quality band (e.g. cloud cover probability) has no name or description, which you could solve in various ways but they lead to other issues:
4. You could just add it to the fourth raster band, but then you are using the same field in two different places and also use a field that is not defined in the raster extension so the tooling may not pick it up.
   2. You could add it to all raster band elements, but then you are duplicating data, use fields that are not defined and tooling may run into conflicts.

Example 2

What I've seen in openEO Platform is that people then merge the bands and use them more freely.

This leads to a couple of issues:

1. A quality band (the fourth band) is declared to be a spectral band without providing any fields that define spectral properties.
2. Fields from the raster extension are used without declaring the raster extension in stac_extensions so they won't be validated. As such the invalid data_type values in this example would not be reported by a validator (they must be lower-cased).
3. Clients will likely not pick up on the additional details as they don't expect them there.
4. Some fields may be duplicated and could also be declared on the asset level, for example spatial_resolution and data_type. But right now these fields are not defined on the asset level (and gsd doesn't always apply or is not correct).

{
	"visual": {
		"href": "rgb.tif",
		"type": "image/tiff; application=geotiff",
		"title": "4-band RGB",
		"eo:bands": [{
			"name": "B4",
			"common_name": "red",
			"description": "Red band",
			"center_wavelength": 0.665,
			"statistics": {"minimum": 0, "maximum": 1},
			"data_type": "FLOAT32",
			"spatial_resolution": 10
		},{
			"name": "B3",
			"common_name": "green",
			"description": "Green band",
			"center_wavelength": 0.56,
			"statistics": {"minimum": 0, "maximum": 1},
			"data_type": "FLOAT32",
			"spatial_resolution": 10
		},{
			"name": "B2",
			"common_name": "blue",
			"description": "Blue band",
			"center_wavelength": 0.49,
			"statistics": {"minimum": 0, "maximum": 1},
			"data_type": "FLOAT32",
			"spatial_resolution": 10
		},{
			"name": "clouds",
			"description": "Blue band",
			"statistics": {"minimum": 0, "maximum": 1},
			"data_type": "FLOAT32",
			"spatial_resolution": 10
		}]
	}
}

Example 3:

Here's another example how the eo:bands construct was used (1) to describe non-spectral (i.e. SAR) "bands" and
(2) to add additional fields that would've been defined in other extensions,
but instead new provider specific fields (gee:units, gee:polarization) were defined:

{
  "eo:bands":[
      {
        "description":"Single co-polarization, horizontal transmit/horizontal receive",
        "gee:polarization":"HH",
        "gee:units":"dB",
        "gsd":10,
        "name":"HH"
      },
      {
        "description":"Dual-band cross-polarization, horizontal transmit/vertical receive",
        "gee:polarization":"HV",
        "gee:units":"dB",
        "gsd":10,
        "name":"HV"
      },
      {
        "description":"Single co-polarization, vertical transmit/vertical receive",
        "gee:polarization":"VV",
        "gee:units":"dB",
        "gsd":10,
        "name":"VV"
      },
      {
        "description":"Dual-band cross-polarization, vertical transmit/horizontal receive",
        "gee:polarization":"VH",
        "gee:units":"dB",
        "gsd":10,
        "name":"VH"
      },
      {
        "description":"Approximate incidence angle from ellipsoid",
        "gee:units":"Degrees",
        "gsd":20000,
        "name":"angle"
      }
  ]
}

Proposed solution

The general idea is to add a new field to the common metadata, which is an array of objects that allows to host fields from various extensions.
The objects would be yet another place where STAC can add all kinds of fields as in Item Properties or Assets, e.g. from common metadata itself.

• This means you could add all fields from common metadata to Band Objects, e.g. title, description, gsd and datetime.
• We would also add the band specific name field for the identifier again.
• Fields that describe actual data (measurement) values such as nodata, data_type, statistics and unit we could also add to common metadata.
• All other fields that are define per band in the EO and raster extensions get the extension prefix prepended (e.g. center_wavelength will be eo:center_wavelength) and get defined as "top-level" fields in the respective extension so that they could also be used in other places such as assets or the Item properties.

Naming

The name of this new field is still to be defined and we are looking for feedback here. It could simply be bands and the object could again be called "Band Object" like it is already in the EO and raster extensions.
On the other hand, a construct such as bands that basically defines "sub datasets" could also be made more general and as such have a different and more general name such as layers, groups, subdatasets, subassets etc. We'd hope that other domains could also use this construct, such as point clouds, data cubes or tabular data.

Affected specification / extensions

The changes proposed will require collaboration between multiple different specifications and also new versions.
The affected specifications are at least:

• The STAC specification (primarily the common metadata, requires a v1.1 of STAC)
• raster extension
• EO extension
• extension template

In general, other extensions could also be broadened up to support adding their fields to the new construct in a backward compatible way (requires a new minor version), for example:

• classification extension
• timestamps extension
• processing extension
• SAR extension

Some extensions could reuse the newly defined fields in common metadata:

• table extension could at least reuse data_type (breaking change, requires v2.0)
• datacube extension could at least reuse statistics and unit (already aligned) in the Dimension and Variable Objects (requires v2.2.0)
• pointcloud extension has a similar Stats Object, which might be aligned with statistics (breaking change, requires v2.0)

Changes to the STAC specification

Please keep in mind that in the following I've used the terminology "band" for the new construct, but we'd like to get feedback regarding the terminology. Depending on the feedback we may change "band" to something else.

The following new sections could be added to the common metadata:

...

Bands

Field Name	Type	Description
bands	[Band Object]	An array of available bands where each object is a Band Object. If given, requires at least one band.

The bands array is used to describe the available bands in an Asset.
This fields describes the general construct of a band or layer, which doesn't necessarily need to be a spectral band.
By adding fields from extensions you can indicate that a band, for example, is

• a spectral band (EO extension),
• a band with classification results (classification extension), or
• a band with quality information such as cloud cover probabilities.

Each Asset should specify its own band object. If the individual bands are repeated in different assets they should all use the same values and
include the optional name field to enable clients to easily combine and summarize the bands.

The bands array may optionally be used in the Item Properties to summarize the available bands in the assets. This should
be a 'union' of all the possible bands represented in assets. It should be considered merely informative - clients should rely
on the bands of each asset.

Note: This property is the successor of the eo:bands and raster:bands fields, which has been present in previous versions of these extensions.
The behavior is very similar and they can be migrated easily. Usually, you can simply merge the each object on a by-index basis.
For some fields you need to add the extension prefix of the eo or raster extension to the property name though. Example:

Before:

{
	"eo:bands": [{
		"name": "B4",
		"description": "Red band",
		"common_name": "red",
		"center_wavelength": 0.665,
		"full_width_half_max": 0.038
	}],
	"raster:bands": [{
		"data_type": "float32",
		"nodata": "nan",
		"statistics": {"minimum": 0, "maximum": 1},
		"spatial_resolution": 10
	}]
}

After:

{
	"bands": [{
		"name": "B4",
		"description": "Red band",
		"data_type": "float32",
		"nodata": "nan",
		"statistics": {"minimum": 0, "maximum": 1},
		"eo:common_name": "red",
		"eo:center_wavelength": 0.665,
		"eo:full_width_half_max": 0.038,
		"raster:spatial_resolution": 10
	}]
}

Band Object

Specifically defined for the Band Object is just a single property name, which serves as a unique identifier.
You can add additional fields from the common metadata such as a description or the value-related properties.

Field Name	Type	Description
name	string	The name of the band (e.g., "B01", "B8", "band2", "red"), which should be unique across all bands defined in the list of bands. This is typically the name the data provider uses for the band.
description	string	Description to fully explain the band. CommonMark 0.29 syntax MAY be used for rich text representation.

A Band Object must contain at least one property, which is not necessarily one of the properties defined here and can be a property from an extension or common metadata.

Data Values

Adds metadata about the data values or measurement values contained in the entity that is described by the object these fields get added to (e.g., an asset or a band).
These fields will often be combined with extensions that group data values into a "unit" or "chunk",
e.g., a band or layer in a file (raster and eo extensions), a column in a table (table extension), or dimensions in a datacube (datacube extension).

Field Name	Type	Description
nodata	number|string	Values used to identify values that are nodata, either by the value as a number or as one of the following strings: nan, inf or -inf.
data_type	string	The data type of the values. One of the data types as described below.
statistics	Statistics Object	Statistics of all the values.
unit	string	Unit of measurement of the value, preferably compliant to UDUNITS-2 units (singular).

Statistics Object

Field Name	Type	Description
mean	number	mean value of all the pixels in the band
minimum	number	minimum value of the pixels in the band
maximum	number	maximum value of the pixels in the band
stddev	number	standard deviation value of the pixels in the band
valid_percent	number	percentage of valid (not nodata) pixel

Data Types

The data type gives information about the values.
This can be used to indicate the (maximum) range of numerical values expected.
For example uint8 indicates that the numbers are in a range between 0 and 255,
they can never be smaller or larger. This can help to pick the optimal numerical
data type when reading the files to keep memory consumption low.
Nevertheless, it doesn't necessarily mean that the expected values fill the whole range.
For example, there can be use cases for uint8 that just use the numbers 0 to 10 for example.
Through the Statistics Object it is possible to specify an exact value range so
that visualizations can be optimized.
The allowed values for data_type are:

• int8: 8-bit integer
• int16: 16-bit integer
• int32: 32-bit integer
• int64: 64-bit integer
• uint8: unsigned 8-bit integer (common for 8-bit RGB PNG's)
• uint16: unsigned 16-bit integer
• uint32: unsigned 32-bit integer
• uint64: unsigned 64-bit integer
• float16: 16-bit float
• float32: 32-bit float
• float64: 64-big float
• cint16: 16-bit complex integer
• cint32: 32-bit complex integer
• cfloat32: 32-bit complex float
• cfloat64: 64-bit complex float
• other: Other data type than the ones listed above (e.g. boolean, string, higher precision numbers)

...

Changes to the raster extension

The extension will be restructured:
raster:bands gets deprecated and the fields in the Band Object that have not been migrated to the common metadata will be defined "top-level" with a raster: prefix.
Chapters for fields that have been migrated to common metadata will be moved ("Data Types" and "Statistics Object").

...

Fields

The fields in the table below can be used in these parts of STAC documents:

• Catalogs
• Collections
• Item Properties (incl. Summaries in Collections)
• Assets (for both Collections and Items, incl. Item Asset Definitions in Collections)
• Links
• Bands

When specifying a raster band object at asset level, it is recommended to use
the projection extension
to specify information about the raster projection, especially proj:shape to specify the height and width of the raster.

Field Name	Type	Description
raster:sampling	string	One of area or point. Indicates whether a pixel value should be assumed to represent a sampling over the region of the pixel or a point sample at the center of the pixel.
raster:bits_per_sample	number	The actual number of bits used. Normally only present when the number of bits is non-standard for the data_type, such as when a 1 bit TIFF is represented as byte.
raster:spatial_resolution	number	Average spatial resolution (in meters) of the pixels.
raster:scale	number	Multiplicator factor of the pixel value to transform into the value (i.e. translate digital number to reflectance).
raster:offset	number	Number to be added to the pixel value (after scaling) to transform into the value (i.e. translate digital number to reflectance).
raster:histogram	Histogram Object	Histogram distribution information of the pixels values.
raster:bands	Band Object	deprecated

raster:scale and raster:offset define parameters to compute another value. The following paragraphs describe some use cases.

...

Changes to the EO extension

The extension will be restructured:
eo:bands gets deprecated and the fields in the Band Object that have not been migrated to the common metadata will be defined "top-level" with a eo: prefix.
The chapter about the "name" will be removed. Most of it has been migrated to the definition in common metadata or is not relevant anymore (e.g., due to the availability of a tile field).
eo:cloud_cover doesn't change its definition, but can be used in a broader scope (before only Item Properties and Assets).

...

General Fields

The fields in the table below can be used in these parts of STAC documents:

• Catalogs
• Collections
• Item Properties (incl. Summaries in Collections)
• Assets (for both Collections and Items, incl. Item Asset Definitions in Collections)
• Links
• Bands

Field Name	Type	Description
eo:cloud_cover	number	Estimate of cloud cover
eo:snow_cover	number	Estimate of snow and ice cover
eo:bands	Band Object	deprecated

Fields for the Band Object

The fields in the table below can only be used in the "Band Object" of a STAC document.
The presence of one of the fields in a band makes the band "spectral".

Field Name	Type	Description
eo:common_name	string	The name commonly used to refer to the band to make it easier to search for bands across instruments. See the list of accepted common names.
eo:center_wavelength	number	The center wavelength of the band, in micrometers (μm).
eo:full_width_half_max	number	Full width at half maximum (FWHM). The width of the band, as measured at half the maximum transmission, in micrometers (μm).
eo:solar_illumination	number	The solar illumination, as measured at half the maximum transmission, in W/m2/micrometers.

...

Changes to the extension template

The extension template repository would be updated to allow adding fields to bands in the JSON Schema (by default?) and also list the bands as a potential scope for the fields:

The fields in the table below can be used in these parts of STAC documents:

• Catalogs
• Collections
• Item Properties (incl. Summaries in Collections)
• Assets (for both Collections and Items, incl. Item Asset Definitions in Collections)
• Links
• Bands

Alternative considered

Keep raster:bands instead of defining a new construct

An alternative that was also discussed in the STAC PSC is that it could be "less breaking" if we keep raster:bands as it is.
The EO extension would be changed as proposed above, but instead of a new construct in common metadata raster:bands would be extended by other extensions such as EO.

The drawback is that it's specific to raster data although such a concept could also be useful in other domains.

Also, the general definition would be a bit more complex as other extensions would extend an extension.
STAC is meant to be extended, but extensions are not primarily meant to be extended.
We already see this with the "Item Assets Definition" extension where we are in the weird spot that common metadata fields can't be validated directly
in the Item Assets Definition as that would lead to a "circular" schema (Item Assets Definition extends STAC and STAC extends Item Asset Definitions).

The extensions also evolve faster than STAC does and as such more downstream changes in the extensions would be anticipated once the raster extension changes.

Keep everything as it is but define new fields in raster:bands

We could also keep the EO and raster extension as they are and only add missing fields such as name and description to the Raster Band Object. This would not solve most of the issues explained above so it was not considered any further.

Implement the proposed changes but directly remove eo:bands and raster:bands

Instead of deprecating eo:bands and raster:bands we could also directly remove them and release new major versions instead of minor versions. While this is very clean, it can lead to downstream issues.
For backward compatibility we assume that many implementations want to keep eo:bands and raster:bands for some time to
let people migrate to the new definitions. During that period validators may report these fields as invalid as they schemas are defined in a way that then undefined fields (eo:bands and raster:bands) with the prefix of the extension are reported as invalid.
This could hurt adoption of the new extension versions.

Open questions

• What name do we choose? See Naming for details.
• Some fields from raster seem to be useful for other extensions as proposed above. I'm not 100% sure whether more fields should be migrated to common metadata, too. raster:scale, raster:offset and raster:histogram may also be relevant for non-rasters. This would result in a very slim raster extension, which only contains the fields raster:spatial_resolution, raster:sampling and raster:bits_per_sample.

Procedure

We'd like to get feedback from the STAC community and are open for any feedback. Please provide the feedback preferrably in this thread or alternatively directly to the STAC PSC. The RFC is open at least until end of March.

Disclaimer: This RFC was written by me with funding from Planet Labs. An earlier version of this RFC was discussed in the STAC PSC and a STAC community meeting.

[m-mohr]

do we plan to include a complex band object inside the properties field, or do we plan it to be within the assets field or both?

It would be available "everywhere". Common metadata fields are applicable in Catalogs, Collections, Item Properties, Links, and all kinds of Assets. It could even be re-used in other extensions. The "summary" behavior of eo:bands between Item Assets and Item Properties would be gone.

[emmanuelmathot]

Thank you @m-mohr for this very detailed proposal.
Here are my amendments and answers to open questions:

1. General: The new structure is intended to be abstract enough to fit to many purposes wider than only bands and rasters. That's a good point. We probably need to examplify this purpose with the potential usages: e.g. rasters, vectors, shapefiles, flatgeobuf, GMLs, databases, sub-collections, ...
2. Naming: Since the proposed new object is something quite abstract, I would name with a generic term that would fit in the several places it would be used. groups is a good candidate
3. Semantic: In order to characterize the kind of object in those groups, I would propose to add an optional groupingor group_type field with a enumeration value specifying it : band, layer, table, feature, ...
4. Extensions: I would keep specific extensions for specific usage. Even if many fields would be migrated for common usage. Raster band is quite specific and I expect more fields and best practices in the raster extension after this change. And probably a reorganization of some fields such as scale and offset for a more specific purpose (e.g. calibration)
5. Deprecation: Since the current specs are already very much adopted and this proposal brings a lot of non trivial changes, we need a smooth phase in/out with transitory versions of the extensions allowing the adaptation of the tools especially for transforming existing catalogs.

[m-mohr]

Thank you for the feedback.

Regarding examples of potential usages: This would need to be provided by the community. While we have common use-cases for bands and rasters, I only know about a potential other use in data cubes and maybe point clouds, but would not have a specific example for the latter.

Regarding point 3 I'm not fully convinced. In principle the type is implicitly clear by the presence of a field with e.g. eo: or table: prefix. The possible value could also not be validated as we don't know the potential values in advance and they could be mixed. There's no way to enforce that e.g. for eo the "band" applies. So in theory people could put everything in there and this makes it less useful.

Just to clarify wrt point 4: We are aligned there. I don't plan to remove any extensions.

[nkleinbaer]

I tend to agree with @emmanuelmathot that using a generic term is preferable, but my vote is for subassets (i think it fits intuitively into the existing nomenclature). But that's assuming that the goal here is for this construct to be extensible to a variety of datatypes besides rasters. As noted, the trade off of using a generic term is the loss of semantic meaning. I'm still somewhat new to STAC but my impression is STAC has it's "roots" in cataloging raster data (most often EO raster data), that that is still the most common use-case by far, and there is some precedent for targeting/favoring that use case when developing the spec (e.g. the decision to move the various "Instruments" fields out of extensions and into the core metadata). So there may be a counter argument to be made that just using bands would make the most sense in the most cases, at the expense of making it a bit "akward" to use the spec for other datatypes.

[nkleinbaer]

On point 3 I was thinking of something similar, but instead of having a separate field indicating the type just making alternative names "aliases" for the same field. So the "canonical" name of the field could be something generic, but users could also choose to use more specific terms like bands or layers when that conveys a more appropriate semantic meaning.

Doing something like that (or the method proposed in point 3) would allow the possibility of some extensions applying to one type of subasset object but not others. For example a hypothetical vector extensions may extend layer objects with fields for geometry type or feature count, without also making those fields available band object (where they don't really make sense). @m-mohr is that type of idea what you were thinking of when you said "There's no way to enforce that e.g. for eo the "band" applies."? Couldn't that just be enforced with some conditionals in the extension schema? Or am I totally misunderstanding your comment?

[m-mohr]

As we are also currently discussing the "archive" extension (see https://github.com/constantinius/archive), the "subassets" seem to be a natural and good choice as you can easily also use it for this usecase. I think this extension is indeed meant to be generic enough so that you can not only use it for raster imagery as otherwise, we could have just used raster:bands as a baseline.

@nkleinbaer You could indeed mix these types, although I don't really see a lot of use cases for it. Maybe the archive extension, but otherwise most file formats are either X or Y, not both.

It will indeed be hard to fully validate subassets, we don't even validate assets properly right now as it's very complex in JSON Schema to enforce things like "object contains Z". What exactly we can do depends on how the extensions itself work. We can certainly validate the fields itself, but requiring fields is always pretty tricky or check for dependencies.

[constantinius]

A very good and detailed proposal!

One small note that might be related: in the composite extension, it is possible to make virtual compound assets, referencing other assets, for example NDVI calculations. This is however only possible if each asset only consists of a single "band" (which seems to be the rule, to be fair, but exceptions exist). Maybe we can address this issue somehow to make references to this new "bands" structure.

[m-mohr]

Interesting use case, I had not looked at composite yet as it is not released yet, but we should make sure that this is aligned. Please let me know if there's anything that you think is missing or should be changed.

[chiarch84]

I liked a lot the very detailed proposal @m-mohr Thanks!
I think the idea to merge the 2 objects together and make it more generic and adaptable to various use cases is a great idea.
Sometimes the risk with STAC modularity is the proliferation of extensions that in fact could very well fit together in one single extension, and I think this example was exactly one of these risky drifts.
From my side i don't like the name "groups" which sounds even too generic to me, while I would prefer the name "subassets".

I though have one question since this point was not too clear to me.
Here follows an example of band taken from a S2 raster example

"assets": {
    "thumbnail": {
      ...
    },
   ...
   "B01": {
      "title": "Band 1 (coastal) BOA reflectance",
      "type": "image/tiff; application=geotiff; profile=cloud-optimized",
      "roles": [
        "data"
      ],
      "gsd": 60,
      "eo:bands": [
        {
          "name": "B01",
          "common_name": "coastal",
          "center_wavelength": 0.4439,
          "full_width_half_max": 0.027
        }
      ],
      "href": "https://sentinel-cogs.s3.us-west-2.amazonaws.com/sentinel-s2-l2a-cogs/33/S/VB/2021/2/S2B_33SVB_20210221_0_L2A/B01.tif",
      "proj:shape": [
        1830,
        1830
      ],
      "proj:transform": [
        60,
        0,
        399960,
        0,
        -60,
        4200000,
        0,
        0,
        1
      ],
      "raster:bands": [
        {
          "data_type": "uint16",
          "spatial_resolution": 60,
          "nodata": 0,
          "statistics": {
            "minimum": 1,
            "maximum": 20567,
            "mean": 2339.4759595597,
            "stddev": 3026.6973619954,
            "valid_percent": 99.83
          },
          "unit": "W/m²/sr/μm"
        }
      ]
    }
}

How would this become? Like the following?

"assets": {
    "thumbnail": {
      ...
    },
   ...
   "B01": {
      "title": "Band 1 (coastal) BOA reflectance",
      "type": "image/tiff; application=geotiff; profile=cloud-optimized",
      "roles": [
        "data"
      ],
      "gsd": 60,
      "subassets": [
        {
          "name": "B01",
          "eo:common_name": "coastal",
          "eo:center_wavelength": 0.4439,
          "eo:full_width_half_max": 0.027,
          "data_type": "uint16",
          "spatial_resolution": 60,
          "nodata": 0,
          "statistics": {
            "minimum": 1,
            "maximum": 20567,
            "mean": 2339.4759595597,
            "stddev": 3026.6973619954,
            "valid_percent": 99.83
          },
          "unit": "W/m²/sr/μm"
        }
      ],
      "href": "https://sentinel-cogs.s3.us-west-2.amazonaws.com/sentinel-s2-l2a-cogs/33/S/VB/2021/2/S2B_33SVB_20210221_0_L2A/B01.tif",
      "proj:shape": [
        1830,
        1830
      ],
      "proj:transform": [
        60,
        0,
        399960,
        0,
        -60,
        4200000,
        0,
        0,
        1
      ]
      ]
    }
}

If what I understood is correct, then why would we even need the "subassets" field? couldn't we directly put all the properties at "B01" level next to "title" etc.?

[chiarch84]

So just to make it clearer, you would accept something like the following json where all the properties are directly under the asset? Would this be valid already now? Or now it is not possible to set fields such as nodata, scale, offset etc. directly under an asset?

"assets": {
    "thumbnail": {
      ...
    },
   ...
   "B01": {
      "title": "Band 1 (coastal) BOA reflectance",
      "type": "image/tiff; application=geotiff; profile=cloud-optimized",
      "roles": [
        "data"
      ],
      "gsd": 60,
      "eo:common_name": "coastal",
      "eo:center_wavelength": 0.4439,
      "eo:full_width_half_max": 0.027,
      "data_type": "uint16",
      "nodata": 0,
       "offset":-1000,
       "scale": 10000,
       "unit": "W/m²/sr/μm"
       "statistics": {
            "minimum": 1,
            "maximum": 20567,
            "mean": 2339.4759595597,
            "stddev": 3026.6973619954,
            "valid_percent": 99.83
       },
      "subassets": [
        {
          "name": "B01"        
        }
      ],
      "href": "https://sentinel-cogs.s3.us-west-2.amazonaws.com/sentinel-s2-l2a-cogs/33/S/VB/2021/2/S2B_33SVB_20210221_0_L2A/B01.tif",
      "proj:shape": [
        1830,
        1830
      ],
      "proj:transform": [
        60,
        0,
        399960,
        0,
        -60,
        4200000,
        0,
        0,
        1
      ]
      ]
    }
}

[m-mohr]

you would accept something like the following json where all the properties are directly under the asset?

Yes, that's the intention right now. Some properties may get a raster prefix, but that's not decided yet. But I'm not so sure why you'd put the things in the asset if you use subassets anyway?

Would this be valid already now?

I'm not sure whether the validators would reject it as asset validation is not so easy in JSON Schema draft-07, but technically it would be invalid at least for the eo: fields.

Or now it is not possible to set fields such as nodata, scale, offset etc. directly under an asset?

All non-prefixed fields you can add. They are then "undefined", "unvalidated" and as such custom extensions, but due to the extensibility of STAC it would not be rejected...

[chiarch84]

Thanks! At that point I might end up not using subassets anyhow.

[Geosynopsis]

For single-band assets you could indeed place the fields

Wouldn't it hurt consistency and interoperability if one implementation can put those fields in root asset level while multi-banded assets would need subassets grouping?

[m-mohr]

If the common metadata model is implemented properly in the client, I don't think it hurts. It's already a multi-level approach (e.g. item <- assets) and then it is (item <- assets <- subassets [or whatever it's called]).

[chiarch84]

Again on the name topic. If it is correct to say that this new "object" can be placed either inside an asset but also inside the "properties" object, at that point the "subassets" name wouldn't fit that much. Maybe in that case "layers" could be better.
Is it correct though that the idea could be also to place the object inside "properties"?

[m-mohr]

That's a good question. I'm not sure. I don't like the "summarizing" behavior of "eo:bands" in Item properties, because it makes it less useful and may even lead to issues in some implementations, because it's not clear whether you can use the index for adressing bands in assets or not. As such I'd at least remove the summarizing behavior, but then the question from #1213 (comment) occurs... what does subasset or group in Item Properties mean? Would it even somewhat conflict with assets?

[emmanuelmathot]

I will advocate again for a very generic and abstract term.

Indeed, as @chiarch84 noted, this new object can be placed at different levels and define a "subset" of the object where it is placed.

Every following term proposed is actually associated to the data model of the asset:

• bands is very specific to raster data
• layers is a term associated to vectors in gdal or in maps UI.
• subassets would be only valid for asset
• subdaatsest only for an Item

That is why I find groups abstract and generic enough to define the grouping of data with a common attribute from a object.
For instance:

• band in EO product the grouping of pixels in the same wavelength range or polarization for SAR
• layer in shapefile is the grouping of vectors of the same objects (e.g. roads, river, ...)
• groups are the container mechanism by which HDF5 files are organized

This term is often used in many IT implementation:

• https://realpython.com/pandas-groupby/
• https://www.w3schools.com/sql/sql_groupby.asp

Since group does not carry any information about the data structure, I also proposed a field to define it's type (e.g. "band", "layer", "database") and would also allow hybrid grouping (multi type assets)

[m-mohr]

Thanks. I'm wondering about where the new construct would apply, e.g. would it be okay to have it in Item Properties and Collections? Or is it just an asset construct? What would "groups" mean in a Item Properties context? Would it have the same behavior as eo:bands before (some kind of a summary?) Would it somewhat clash with assets?

[m-mohr]

In the proposal above I recycled the behavior of eo:bands which means that eo:bands summarizes (i.e. merges to a set) the bands in Item properties. I think that is not a good idea as then it's not clear how the relation between the array index and the band position is. Thus we have basically two different behavior in one file for the same field. Thus, I'd propose to define it more like proj:epsg for example is used:
Item properties give the baseline and you can override it at the asset level. This allows for something like this:

function getBands() {
  if (asset.bands) return asset.bands
  else return item.properties.bands
}

[Geosynopsis]

Thanks a lot, @m-mohr, for an excellent RFC! I like the idea of generalising the definitions for the subset of data. Mainly the fact that the object itself is extensible. So, great work!

• Nomenclature: Regarding the terminology, a heavy plus for the group, as @emmanuelmathot suggested or contents would be another option as we describe the asset's contents.
• As @emmanuelmathot suggested, having such a generic object could induce confusion, so having a type is a nice idea. But discrimination of data models based on the type may not be suitable for adaptability. However, having type for the characterisation purpose only could be a great idea. Types or preferably modalities, in this case, could be raster, vector, point cloud, datacube etc.
• Regarding your question here, it's better to be strict before and relax later. So, I recommend allowing this field only for assets and the semantics make sense within the context of assets anyways.

[cholmes]

I'm -1 on using a generic object with types, at least for now. We have a very clear use case with raster bands, with lots of data that would benefit. I think the case for the others is much less clear. And I'd much prefer we 'generalize' based on real usage, where we have lots of examples where things are similar and then we decide to combine them. So I'm all for similar 'subasset' type definitions / extensions, and if they all get widely used then we could combine them down the road into a more generic structure. I fear that if we make things too generic at this level then interoperability will suffer. And we have a great extension mechanism, so let's use that, with nice, precise definitions for each. And then we can leverage extension maturity to help guide people on them.

The specific ideas of 'layer, table, feature' as alternate 'types' all seem similar to me. I'm sure part of this relates to my belief that they really belong at the 'item' level - conceptually they should go at the 'collection' level. Yes, we need collection level search - I know people put them in at the item level because there's item search. But I think a 'collection' is the right abstraction level, and it could have individual 'items' (one for each row in a vector data set) as a feature service, or it could just be a vector data file.

I suppose you can use the subasset/group construct at the collection level. But I'd much prefer to have a well-defined 'vector' collection extension, that defines its fields, instead of a super generic 'group'.

So please, let's start with this modest improvement of 'bands', so that raster:bands and eo:bands work better together. And then we can continue to evolve to be more generic & meet the proposed use cases.