Option Sets¶

The CLI can help you manage option sets by downloading, iterating, and uploading option sets via CSV and YAML.

Download All Option Sets¶

To download all option sets for a specific organization, use getOptionSets like below.

contrail types getOptionSets --format <YAML or CSV>

Upload Option Sets¶

To load multiple option sets YML files from a folder, use uploadOptionSets. This will update existing option sets if they exist and create new ones if they're not already in the system.

contrail types uploadOptionSets <Directory Path>

Merge Option Sets¶

To combine the option sets from an existing organization with the OptionSets in a file, use this command. The option sets file must be a .yml file. This will combine the option sets in the YML file with the ones already in the system and give you a single YML file with all of them.

Run this CLI command

contrail types mergeOptionSets <File Path>

Parse Option Sets Local File¶

To parse CSV files into OptionSets, you can use the parseOptionSetsLocalFiles command. The style parameter specifies the format of the CSV file, which can be either "NameAndLabelAndKey" or "LabelsInColumn".

If the CSV file has separate columns for option set name, option key, and option label, you should use the "NameAndLabelAndKey" style.

Example file for NameAndLabelAndKey would be

Gender,g_men,Men
Gender,g_women,Women
Gender,g_uni,Unisex
Countries,co_spain,Spain
Countries,co_france,France
Countries,co_aus,Australia
Countries,co_usa,United States of America,
Countries,co_egypt,Egypt

If the CSV file has one column for each option set, with the rows representing the label values, you should use the "LabelsInColumn" style. In this case, the option keys will be automatically generated.

Example file for LabelsInColumn would be

Gender,Countries,Brands
men,spain,prada
women,france,converse
unisex,australia
,usa
,egypt

Run this CLI command

contrail types parseOptionSetsLocalFiles <File Path> <style>

Option Set Structure¶

An Option Set is a list of values used by single-select and multi-select properties. Each entry inside the optionSet array describes one selectable value.

Field	Type	Required	Description
`value`	`string`	yes	The stored key. This is what the property's value will be on every entity. Immutable in practice — renaming orphans existing data.
`display`	`string`	yes	The user-facing label shown in dropdowns.
`disabled`	`boolean`	no	When `true`, the value is hidden from new pickers but pre-existing data keeps it. Use this to retire a value without losing history.
`color`	`string`	no	Hex color used by the UI to render the value as a colored chip.
`additionalValues`	`object`	no	Free-form metadata attached to the option (e.g. an upstream ID, a category code). Not hydrated into formulas / validations.
`localizedDisplays`	`object`	no	Map of locale → translated display label, e.g. `{ "fr-FR": "Hommes", "es-ES": "Hombres" }`.

At the option-set level (not per-option):

Field	Type	Required	Description
`name`	`string`	yes	The display name of the Option Set.
`slug`	`string`	yes	The Option Set's key.
`isSorted`	`boolean`	no	When `true`, options are rendered sorted by `sortKey` (or by `display`) instead of in array order.
`sortKey`	`string`	no	Field name on each option to sort by when `isSorted` is `true`.
`isArchived`	`boolean`	no	Marks the Option Set as archived. Archived sets aren't offered for new property assignments.
`disabled`	`boolean`	no	Disables the entire Option Set (different from disabling individual values).

Example YAML¶

name: Status
slug: status
isSorted: false
optionSet:
  - value: draft
    display: Draft
    color: '#9aa0a6'
  - value: in_review
    display: In Review
    color: '#fbbc04'
    localizedDisplays:
      fr-FR: En revue
  - value: approved
    display: Approved
    color: '#34a853'
  - value: retired
    display: Retired
    disabled: true   # hidden from new pickers; pre-existing rows keep the value

Multi-select storage¶

A multi-select property stores an array of values on the entity (e.g. ["draft", "in_review"]), not a single string. Rule Set filterConditionType for multi-select fields uses is_any_of / is_none_of, not equals.

Conventions and Gotchas¶

value is forever. The value is the key stored on every entity that has selected it. Changing a value does not rewrite existing data — it orphans it, and the old key becomes an unmapped string. To "rename" a value, add the new value, migrate the data with a script, then disable (don't delete) the old one. To change only the user-facing text, edit display and leave value alone.
Case-sensitive matching. value is compared case-sensitively in formulas, rule sets, and the database. Red and red are different values.
Disable, don't delete. Removing a value that is referenced by existing data breaks downstream rule sets, option-set hierarchies, formulas, and validations that allow-list against it. Prefer disabled: true to retire a value.
Downstream impact. A change to an Option Set can affect any Rule Set's optionSetValues allow-list, any Option Set Hierarchy that lists it as a parent or child value, any formula/validation that branches on the value, and any upstream/downstream integration that maps to it (FlexPLM, ODS, Shopify). When removing or renaming, scan these references first.
Localization fallback. If a localizedDisplays[locale] entry is missing, the UI falls back to display. Provide translations for the locales the customer uses; missing entries do not error.
additionalValues isn't visible to formulas / validations. It's metadata for integrations and reporting only. Don't try to read it from obj.