Support scalar enumerated type attributes

[rly]

A schema writer may want to specify that a particular field can have values from only fixed set of values written in the schema. For example, in NWB, TimeSeries/data has an attribute continuity that allows only values "continuous", "instantaneous", or "step". This restriction should be formalized in the schema language.

This enum type is supported to a degree when validating constructor args using docval in HDMF, e.g., https://github.com/NeurodataWithoutBorders/pynwb/blob/dev/src/pynwb/base.py#L191.

Here is the implementation in HDMF:
https://github.com/hdmf-dev/hdmf/blob/edfab9e0f2f4cda610a44f7d15a775eaa3a2db78/src/hdmf/utils.py#L519-L533

I propose we add support for enumerated types in HDMF. To start, I propose we limit it to scalar attributes with dtypes: int, uint, float, string (bool is not useful).

If there is a strong use case, we can add support for arrays of enumerated types, but that is similar to data that is governed by a controlled vocabulary, for which systems like HERD and restrictions in the API (e.g., HDMF TermSets) could be a solution.

[rly]

Related: NeurodataWithoutBorders/nwb-schema#640

[rly]

Similar work:

• JSON Schema uses the enum key for a list of values. They can be different types, including null, if the dtype is not restricted.
• LinkML schema has an enums key at the root level of the schema. Enums are dictionaries with the name of the enum as the key and key-value pairs such as permissible_values: [list of dicts of values and their meanings] and other uncommon keys to describe dynamic mappings.

Proposal: Support new enum key for scalar attributes.

enum is allowed only if shape: scalar ("scalar" is introduced in hdmf-schema-language 3.0).

Example:

- neurodata_type_def: TimeSeries
  neurodata_type_inc: NWBDataInterface
  doc: General purpose time series.
  attributes:
  - name: example_float_enum
    dtype: float
    shape: scalar
    enum:
    - 1.0
    - 0.0
    - -1.0
    - .nan
    doc: example float enum
  datasets:
  - name: data
    doc: Data values.
    attributes:
    - name: continuity
      dtype: text
      shape: scalar
      enum:
      - continuous
      - instantaneous
      - step
      doc: Optionally describe the continuity of the data. Can be "continuous", "instantaneous", or
        "step". 
      required: false

[rly]

@oruebel @bendichter @ehennestad - what do you think?

[bendichter]

perfect. I didn't know about ".nan". Is that something we support already as a possible value? If not, I'd say let's not add that as a dependency of this feature. But the feature itself looks great. I like that we are borrowing from json schema syntax.

[rly]

I also didn't know about ".nan" until looking it up in the YAML spec. I'll remove it from the example when writing up the docs.

[rly]

I will have to test whether we support that already as a possible value. JSON Schema does not support nan as a possible value, so maybe we want to disallow it since 1) the schema is cached in the file as JSON and 2) we do schema validation in the schema repos with JSON Schema.

[oruebel]

we want to disallow it since 1) the schema is cached in the file as JSON and 2) we do schema validation in the schema repos with JSON Schema.

I think for now, not supporting nan is fine. Supporting nan is probably better dealt with as a separate issue/PR.