Code Lists

Code lists

Code lists are reusable sets of { code, label } values for controlled choices such as language, country, document type, or an organisation’s categories. The code is the stable value stored in data and sent by integrations; the label is the human-readable text shown to authors.

Choose the right value source

An attribute can use one of three value constraint models:

• Free format — Any value is accepted. Use this when the values are open-ended.
• Inline values — A short list maintained directly on the attribute. Use this for a small, attribute-specific set such as acme and rocket.
• Code list — A named list that can be shared by multiple attributes or maintained from an external source. Use this for larger or centrally managed lists, such as BCP-47 languages or ISO country codes.

Create a code list

Open Code Lists for the tenant and choose New code list. Select a source type:

• Inline — Enter each code and label in the entries editor. Entries appear in pickers in the order you add them.
• URL — Enter a URL that returns a JSON array of entries. Refresh the list from its detail page when the source changes; its optional sortOrder values control the order in pickers.

URL entries use this shape:

[
  { "code": "en-US", "label": "English (United States)", "sortOrder": 1 },
  { "code": "nl-NL", "label": "Dutch (Netherlands)", "sortOrder": 2 }
]

If a URL refresh fails, Epistola keeps the last successful entries and records the error, so existing pickers continue to work while the source is fixed.

Bind a code list to an attribute

Edit an attribute and choose the code list as its Value constraint. An attribute can use either a code list or inline values, never both. When the attribute is used on a variant, authors see the visible entries in a dropdown. The dropdown shows code — label when those values differ, while integrations continue to use the code.

Manage entries

Open a code list to review its entries. Inline entries keep the order in which you added them; URL-sourced lists can provide sortOrder values. Hiding an entry removes it from new selections but keeps the code valid for existing variants, which provides a safe way to phase out a value. Use Show hidden entries when you need to review or unhide one.

Catalogs and sharing

Code lists belong to a catalog within a tenant. Authored catalogs can release code lists together with templates, attributes, themes, fonts, and images. Code lists from subscribed catalogs are available for use but are read-only in the consuming tenant.

Epistola also provides system code lists, such as locale, language, and country lists, through the system catalog.