Skip to main content

Codelists

Codelists are controlled vocabularies — flat lists of allowed values with their descriptions. They are used throughout message models to constrain the values that a data element can take. Common examples include country codes, currency codes, document type codes and status codes.

info

Unlike other specification types, codelists are not versioned. A codelist is a single entity whose entries can be updated over time. The entry-level fields Date added and Date removed track the lifecycle of individual codes.

Permissions

The Codelists page is visible to all users, including the ability to view, search, and export codelists. Creating, editing, and deleting codelists requires the Maintainer role. Importing codelists requires the Administrator role.

Creating a codelist​

To create a codelist:

  1. Navigate to Codelists in the left menu bar.
  2. Click the '+ Add codelist' button in the top right corner.
  3. Fill in the codelist properties on the Codelist tab.
  4. Switch to the Entries tab to add code values.

Codelist properties​

The Codelist tab holds the general information about the codelist:

  • Name: the name of the codelist (e.g. "Invoice Type Codes").
  • Url: a hyperlink to the original external codelist, if applicable.
  • Note: additional information about the usage or origin of the codelist (supports rich text).
  • Maintained by: the organization responsible for maintaining this codelist. Only existing organizations can be selected.
  • Is external: toggle indicating whether this codelist is maintained by an external party and reused, or defined internally by your organization.
  • Is subset: toggle indicating whether this codelist contains only a subset of the codes from the original external list. This only applies to external codelists.
  • Last updated: the date on which the codelist entries were last updated.

Managing entries​

The Entries tab shows all code values in the codelist. Each entry has the following fields:

  • Code: the code value itself (e.g. 380, NL, EUR).
  • Description: a human-readable description of what the code means.
  • Date added: when this code was introduced.
  • Date removed: when this code was deprecated or removed. Entries with a removal date are shown with strikethrough styling.
  • Status: the current status of the entry.
  • Reported by: who requested the addition or change of this entry.

To add a new entry, use the 'Add entry' button on the Entries tab. To edit an existing entry, click the pencil icon next to it. To remove an entry, use the delete button on the edit entry page.

Codelist unioning​

A codelist can be defined as a union of other codelists. When a codelist has union components, it automatically includes all entries from the referenced codelists in addition to its own entries.

This is useful when a standard reuses codes from multiple external sources and wants to present them as a single combined list.

To configure unioning, use the Unioning section on the Codelist tab:

  1. Use the Add union component picker to search for and add existing codelists.
  2. Added codelists appear in the "Union of" list.
  3. Remove a union component using the remove button next to it.

The Used by tab also shows an Other codelists section listing any codelists that include this codelist as a union component.

Importing codelists​

Codelists can be bulk-imported from OASIS Genericode XML files (.gc or .xml).

To import a codelist:

  1. Navigate to the codelist import page.
  2. Upload your Genericode XML file.
  3. Click the Import button and the importer creates a new codelist or updates an existing one (matched by name).

The importer extracts the following from the Genericode file:

  • LongName (or ShortName as fallback) → codelist name
  • LocationUri → external URL
  • CanonicalUri and Version → stored in the note field
  • SimpleCodeList rows → codelist entries (only columns with ColumnRef values code, name, or description are recognized; other columns are ignored)
info

Importing codelists requires the Administrator role. If an existing codelist with the same name is found, its entries are replaced with the imported entries.

caution

The Genericode importer format is subject to change in future versions.

Using codelists in message models​

The Used by tab on the codelist edit screen shows all message model elements that reference this codelist. Each entry shows the full path to the element and clicking it navigates directly to the element in its specification.

This helps maintainers understand the impact of changing a codelist — any modification affects all linked message model elements.

For information about how codelists appear to end users, see View codelists.