Add 'bands' as an alternative to 'bidx' and update documentation

[emmanuelmathot]

Introduce 'bands' as a name-based alternative to 'bidx', deprecating the latter. Update documentation, including CHANGELOG, README, and JSON schema, to reflect this change and provide a new Planet example demonstrating the use of 'bands'.

Fixes #18

[m-mohr]

I'm not a fan of naming it bands with a definition that conflicts the definition of the bands construct. All my tooling at least assumes that if you find bands it has the definition of the bands construct as it's in common metadata.

[vincentsarago]

I would still use bidx or indexes to differentiate with the stac band concept

[emmanuelmathot]

I'm not a fan of naming it bands with a definition that conflicts the definition of the bands construct.

Where does it conflict with the STAC spec?

[vincentsarago]

because I think a band can be an asset or and index within an asset, depending where the band object is 🤷

The bands array is used to describe the available bands in a STAC entity or Asset.

Only the best practices says bands (e.g. in combination with the [EO extension](https://github.com/stac-extensions/eo/)): Provide spectral band information, and order of bands, within an individual asset.

[vincentsarago]

just a side note, the more we add specification within the renders the more conflicts we can have.

We should also mention the links with the asset or assets array (would a band be applied to all the assets or the band array should match the length of the asset arrays?

E.g, in titiler we moved from {assets: ["asset1"], bidx: 1} to {assets: ["asset1|bidx=1"]} for the users to be able to pass per asset options (e.g band indexes or variables selection for Zarr Assets)

[m-mohr]

Where does it conflict with the STAC spec?

Here, bands is an array of strings. In STAC spec it's an array of (Band) objects.

[emmanuelmathot]

Here, bands is an array of strings. In STAC spec it's an array of (Band) objects.

Yes, the string is a reference to the band name. THe intent is not to specify the band again, just to select them.

[m-mohr]

Yeah, but it's not compliant to the common metadata model. We should choose a different name, otherwise tooling will be confused when it implement's this as it expects an object, not a string.

Also just as a clarification: #18 just asked for a clarification, not a new construct. I'm fine with bidx as long as it's well documented.

Additional thought: name is not required in bands.

[emmanuelmathot]

Good points. I think this converges if we fold the fix back into bidx instead of introducing bands as a separate field.

@vincentsarago you're right that we still need a way to select bands independently per asset and that's already what the array-of-arrays shape in this PR is for (one inner array per position in assets, e.g. [[], ["red", "nir"]] for assets: ["B04", "stacked"]). I'll document the equivalence with titiler's assets: ["asset1|bidx=1"]` move explicitly, since it's the same underlying need.

@m-mohr agreed. I always forgot that common metadata applies to all objects.

So: drop bands, and instead extend bidx itself to take either an index (int, 1-based as today) or a band name (string) per entry, keeping the same array-of-arrays/per-asset structure:

"assets": ["B04", "stacked"],
"bidx": [[], [3, "nir"]]

@m-mohr #18 only asked for bidx to be documented but the minimal addition needed to make a documented answer possible (1-based, per-asset, name-or-index). Let me know if that lines up with what you had in mind.

[m-mohr]

Fine for me. Makes it obviously a bit more difficult to implement.

1-based index will likely lead to some bugs when people don't realize it, but as long as it's documented fine for me.

Note that as-is, it's a breaking change. The array structure changed from array of integers to array of array of integers or strings. The old way (array of integers) is not supported via the schema and README any longer, but I think that is fine and makes it less prone to error.