Fixed value fields or enumerations

You can limit the possible values of a field by turning it into an enumeration.

You turn another base type into an enumeration by supplying the possible-values. The actual field value is still stored as the original base type.

Enumeration is support for the following field types:

Single value enumeration

A single value type with limited possible values will by default be visualized as a drop-down.

Example string enumeration, rendering a drop-down instead of textbox
document-definition:
  name: company
  content:
    - id: activities
      type: string
      possible-values: (1)
        - building-software (2)
        - selling-cars: "Selling cars" (2)
        - destroying-houses
1 Supply the possible values as a list of items.
2 A possible value can be specified in several ways, see the chapter on possible value specification.

Multi-value enumeration

If you want to store a collection of possible values, you can create a multi-value enumeration by applying an indexer ([]) to your base type. A multi-value enumeration will by default visualize as a checkbox group.

Example multi-value number field
document-definition:
  name: participant
  content:
    - id: name
      type: string
    - id: olympic-year-locations
      type: number[]
      possible-values:
        - 2014: 'Sochi (2014)'
        - 2016: 'Rio De Janeiro (2016)'
        - 2018: 'Pyeongchang (2018)'
        - 2020: 'Tokyo (2020)'
        - 2022: 'Beijing (2022)'
        - 2024: 'Paris (2024)'

Possible value specification

There are multiple ways to specify a possible value entry in YAML, depending on how much customization you wish to apply. The different specification types can be mixed in the same list of possible values.

Single value

When specifying an item as a single value, the value will be used as both the label and the actual persisted value.

- id: olympic-year-locations
  type: string
  possible-values:
    - myvalue
    - 'Another value'

Key/value pair

When specifying a possible value as a key/value pair:

  • the key represents the actual value of the item

  • the value represents the label that is displayed for that item

- id: olympic-year-locations
  type: number
  possible-values:
    - 2014: 'Sochi (2014)'
    - '2022': 'Beijing (2022)'

Map of settings

If you want to customize how an item is displayed, you can use a map to set more options.

- id: olympic-year-locations
  type: number
  possible-values:
    - value: 2014 (1)
      label: 'Sochi (2014)' (2)
      html-attributes: (3)
        class: past-event
        data-info:
          category: winter
          weather: cold
1 The required value key is used to set the actual value of the item.
2 The optional label key can be used to specify the display label for the item. When omitted, the value will be used instead.
3 The optional html-attributes key can represent a map of values that are HTML attributes that should be set on the control for that item. The keys of a html-attributes map are expected to be strings, the values can be any type of construct. Anything other than string values will usually be serialized to JSON on the generated HTML.

You can use html-attributes to apply per-item styling.

It is required that the actual value of an item can always be converted to the target type of the field it belongs to. For example a value of 'abc' will fail when you try to put it on a field that has a number type.