Define what "machine-readable" means for the `name` fields

[gadomski]

Background

Currently, the name attribute of the class object is defined as

REQUIRED. Short name of the class for machine readibility

There is no additional guidance around what "machine readibility" [sic] means. This is true for the name field of the bit field object as well.

(aside) I've opened a PR to fix the spelling of readibility here:

• https://github.com/stac-extensions/classification/pull/36

Previous discussion

This issue has been discussed in two spots:

• https://github.com/stac-extensions/classification/issues/28#issuecomment-1151639912
• https://github.com/stac-extensions/classification/pull/35#issuecomment-1185762981

We have identified at least three ways the name field is used in the wild (so far):

• as a query parameter in an API call, e.g. GET /api/stats/landcover?class=snow
• as a legend for a map, e.g.
• as a attribute name in a dynamically-generated software API, e.g. if not tile.land_cover.snow

These each indicate that name should be short, and that it should be ready for simple string manipulation operations that convert it from (e.g.) snake_case to Legend case (a nice, human readable version for map legends).

Proposal

While I personally prefer kebab-case, STAC prefers snake_case, so I propose that name is restricted to snake_case and checked in the schema w/ a regex, per @m-mohr's suggestion here (but changing - to _): https://github.com/stac-extensions/classification/pull/35#issuecomment-1185762981. Thoughts?

[m-mohr]

_ is included in \w in the regex, so users have the option to choose - or _.

A related question is: Should there be a human-readable title for e.g. legens?

[drwelby]

Adding an optional title to classes seems useful.

Is there a better name for name that hints that it's machine-readable? Maybe classname?

[m-mohr]

I think name is fine for this.