This document is a public draft. Readers are invited to submit comments to the Implementation Guidance Task Force.


  • Kathryn Dobinson, CoreFiling
  • Paul Warren, XBRL International Inc.
  • Revathy Ramanan, XBRL International Inc.


  • Carol Baskey, RPM International Inc.
  • Shilpa Dhobale, IRIS Business Services
  • Pierre Hamon, etXetera Solutions XBRL
  • Ian Hicks, CoreFiling

Table of Contents

1 Abstract

This guidance document explains the "Extensible Enumeration" features of XBRL that allows the definition of concepts with a list of allowed values. This document covers both Extensible Enumerations v1.0 and v2.0 specifications, and describing the differences between them and providing recommendations on choosing which to use. It is primarily targeted towards users seeking a basic understanding of the specifications, such as taxonomy architects and taxonomy authors. This document is not intended to explain the technical details of the Extensible Enumerations specifications.

2 What are Enumerations?

It is sometimes desirable for a fact in an XBRL report to have a value which is taken from a predefined list. Where this occurs, it is known as an enumeration. For example, a company may be required to report the country in which its head office is located. In the absence of an enumeration, different companies may use different values to represent the same country, for example "The Netherlands", "NL", "Netherlands" and "Nederland" might all be used to refer to The Netherlands. Using an enumeration ensures that all documents use the same value, improving consistency and comparability.

Figure 1 shows how the "Head Office" country enumeration could be set up, with country codes ordered alphabetically. A filer can choose one option from the list.

Figure 1: Example of an enumeration

3 What are Extensible Enumerations?

Extensible Enumerations is the XBRL standard way of defining concepts for facts that take a value, or set of values, from a taxonomy-defined list of values.

There are other mechanisms that may be appropriate in specific situations, for example, using XBRL Formula Rules, or using the Boolean data type where a simple true/false value is required. These options are discussed in a separate guidance document on how to define a list of allowed values.

Despite the name, extensibility is only one of the benefits provided by the Extensible Enumerations specifications. This document discusses the features of these specifications in more detail.

3.1 Associating labels and references

Extensible enumerations allow labels and references to be associated with the values of an enumeration, using the same mechanism as is used for concepts in a taxonomy. This includes providing labels in different languages, for localisation, or different types of label. For example, "documentation" labels could be used to provide additional guidance for the intended use of a particular value. Figure 2 shows an example labels and references attached to the enumeration value "NL".

Figure 2: Labels and references for an enumeration value

3.2 Re-use of enumerations

In the "Country of Head Office" example shown above, the country is used as a fact value, but in other cases, it may be desirable to use the same enumeration as a dimension value for an explicit taxonomy-defined dimension. For example, where a company is required to report its sales by country, this would typically be done by reporting values against a "Sales" concept qualified by a "Country" dimension.

The list of allowed values for an Extensible Enumeration is defined using the same mechanism as used for defining dimension members in a taxonomy. This allows the same enumeration to be used as a fact value or as a dimension value for an explicit taxonomy-defined dimension.

3.3 Tree hierarchies

Extensible Enumeration members can be organised in a hierarchical tree structure. For example, the countries in the example above could be arranged in a hierarchy according to region.

This can improve usability with filers seeing a tree structured drop-down list instead of a flat list in their filing software tools as shown in Figure 3.

Figure 3: Enumeration hierarchy

3.4 Unusable values

Individual values in an enumeration can be flagged as being "unusable", meaning that they cannot be reported. This allows values to be introduced purely for the purpose of adding structure to the list. For example, when requiring companies to report their "country of head office", it would not be appropriate for them to report "Africa" or "Asia". In this case, these values would be flagged as unusable.

3.5 Extending Extensible Enumerations

Like other parts of an XBRL taxonomy, extensible enumerations can be modified through the use of an extension taxonomy. This can add to the information associated with individual values, such as providing labels in additional languages, or it can modify the set of allowed values in the enumeration. For example, a European extension may provide labels and references in multiple European languages (as shown in Figure 4). The extension author may add or remove countries and re-organise the members into a different tree structure.

Figure 4: Country with multi-language labels and references

3.6 Multi-valued enumerations

Extensible Enumerations also enable reporting facts that can take multiple values from the list of allowed values. This is to cater to requirements analogous to a set of checkboxes in a form, where it is possible to choose multiple answers. An example of such a multi-valued enumeration is a disclosure that requires listing all countries where a company operates, requiring the fact value to accommodate more than one country.

Figure 5 shows an example of a possible user interface for selecting a multi-value enumeration for reporting all the types of banking arrangement that have been entered into between a bank and a borrower.

Figure 5: Multi-valued enumeration example

4 Extensible Enumeration specification versions

The feature of multi-valued enumerations was added in Extensible Enumeration version 2.0. The previous version, Extensible Enumerations v1.0, remains supported.

In order to cope with multi-valued enumerations, Extensible Enumerations v2.0 uses a different technical syntax for representing enumeration values in a report, and for consistency, this new syntax is also used for single-valued enumerations.

This change in syntax should have no impact on end users as XBRL tools will typically use labels to display enumeration values to users and will hide the technical details of how the value is represented in the report.

Table 1: Extensible Enumerations specification version
v1.0 v2.0
Single-valued enumerations

Multi-valued enumerations


Extensibility, reusability, tree hierarchies, flag Unusable Value

Technical Representation in of fact value in XBRL report1

QName Expanded name URI

4.1 Considerations for selecting specification version

  • Use v2.0 unless there is a need to interoperate with taxonomies that are currently using v1.0. v2.0 should be used even if multi-valued enumerations are not an immediate requirement, as this will make it easier to adopt multi-valued enumerations in the future should then become required.
  • Taxonomies currently using v1.0 should have a migration plan for moving to v2.0. This will enable collection of multi-valued enumerations and ensure that taxonomy uses the latest supported specification version.
  • Although there is no technical issue with mixing v1.0 and v2.0 in the same taxonomy, it is not recommended. If a taxonomy needs to support multi-valued enumerations, it is recommended to migrate all single-valued enumerations to v2.0.

  1. Software developers wanting more information should refer to the technical specification, and the corresponding conformance suites for v1.0 and v2.0

This document was produced by the Implementation Guidance Task Force.

Published on 2020-03-24.

Was this article helpful?

Related Articles


Would you like
to learn more?

Join our Newsletter mailing list to
stay plugged in to the latest
information about XBRL around the world.

By clicking submit you agree to the XBRL International privacy policy which can be found at xbrl.org/privacy