Table of Contents

1 Introduction

This document considers the case where there is a requirement to collect a fact whose value must be one of a list of more than one possible values. Examples of this include:

• Where values are inherently fixed, e.g. a response to a "Yes" or "No" question.
• Where there is a list of valid codes.

For these cases, it is desirable for the taxonomy to constrain the list of allowed values in order to ensure consistency (and thus comparability) across filings, and to help preparers to enter, select or display the value, possibly in a local language.

Appropriate taxonomy architecture can ensure that the allowed values are defined in a taxonomy such that these constraints are enforced by XBRL validation and can be understood by a preparer.

In order to select the best architecture, the list and the architectural options should be characterised. Once these are defined, it is possible to evaluate the suitability of the options for the list. This document presents this approach to selecting the best taxonomy architecture and gives overall guidance that can be followed in most cases. The guidance is targeted towards taxonomy authors and taxonomy architects.

2 Categorising your list

This section shows how a list can be characterised in order to refine the architecture requirements.

2.1 Extensibility

This is the extent to which the list is expected to be changed by preparers or other taxonomy authors. These changes may include:

• Adding or removing items from the list.
• Adding metadata to the items in the list (e.g. translations).

It is also important to recognise if lists should be able to be changed despite the architecture otherwise not explicitly being chosen to support extension taxonomies.

2.2 How values in the list will be understood

This is the extent to which the values in the list need additional explanation in order to be understood. To characterise this aspect of the list, the taxonomy architect should have in mind how they expect items to be viewed or selected:

• No additional explanation may be required if the allowed values are self- explanatory. For example, long names of countries are required - "France", "Australia".
• List-level explanation might be required if the allowed values match some existing code list. For example, "Use ISO 3166-1 alpha-2 codes".
• Item-level explanation might be required if the allowed values match a proprietary or abstract code list. For example, "01" for France, "02" for Australia¹.
• If translations of items or associated explanatory information in the list are required, then this is also a characteristic that should be noted in this category.

2.3 Timing of changes

This characteristic considers the impact of the timing of list updates with reference to the desired taxonomy update schedule. The characteristic is one of the below:

• Changes to the list can happen as part of the desired taxonomy release schedule.
• Changes to the list need to be able to happen independently of the desired taxonomy release schedule.

2.4 Length of the list

Characteristics related to the length of the list are:

• Special case of 2 items where they might be represented by true/false, applicable/not applicable, yes/no or similar.
• A long list, which is a value judgement, can be defined as being a list where it would be impractical to include as part of the taxonomy. For example, postal codes are technically drawn from a finite list of possible values, but enumerating all options is impractical.
• A regular length list which is any list that does not fall into the above categories.

2.5 Other considerations

When considering the list, these are some characteristics that will help inform the decision as to which option to choose:

• Whether the allowed values can reasonably or legally be included in the taxonomy, for example, this may not be allowed if the list is:
  • Commercially sensitive such as the names of organisations.
  • Controversial such as lists of geographical locations including ones where there are territorial disputes.
  • Copyrighted data.
  • Held in an external data source such as an up-to-date list of company registration numbers.
• Whether there are more general restrictions on values, such as a generated identifier.
• Whether the value is used in conjunction with other facts in order to fully understand each fact.
• Whether multiple values are required to be selected from the allowed list of values. For example, a disclosure that requires listing all countries where a company operates requires the fact value to accommodate more than one country.
• Whether the value should be strictly validated against a list of all possible values or whether it is sufficient to validate that the format of the value is correct. For example, there is a finite number of phone numbers, but given the size of such a list, it may be acceptable to check that the number of digits is correct.
• Whether an extension or other taxonomy author will want to reuse the list for different reportable concepts.

3 Options available

This section describes some of the taxonomy architecture options available to represent lists of values. In order to overcome specific challenges, other options have been tried, however, we consider that the options presented are flexible enough to cover any list.

A second constraint on the options presented in this document is that, in all cases, it is possible to strictly define the exact list of allowed values. In other cases, for example the postal code example mentioned above, other approaches to constraining allowed values should be used, but these approaches are not discussed here.

3.1 Boolean

This option uses the XML Boolean data type to allow a true/false enumeration. As well as providing the allowed values, users of the taxonomy are able to understand more about the nature of this list. The allowed values for an XML Schema Boolean are "true" (or "1") and "false" (or "0").

Characteristics and consequences:

• Boolean types reuse an XML Schema type that is a fully defined data type for suitable lists. This may simplify the design of the taxonomy.
• As for reportable concepts of other data types, Boolean values can be considered to an additional possible state, in that they may not be reported at all. Taxonomy authors should consider if there is a distinction between reporting the concept with a value of "false", and not reporting it at all, and provide appropriate guidance to preparers².
• The values accepted by a Boolean field are “true” and “false”. As such, the definition of a reportable concept should make sense if responded to in this manner (as opposed to, e.g. “yes” and “no”). For example asking for a "true" or "false" response to a statement “Company is trading” is correct while the alternative label for this reportable concept “Is the company trading?” would not be.
• The approach of using the XML Boolean data type cannot be extended to include other options. If any more selections are required (e.g. “it depends”) one of the other approaches described in this document must be used.
• Specifications state that incorrect values result in schema validation errors which may require special handling to be understandable by end users.
• Boolean types use English words as their values (or a 0/1). This means that software may need localisation or other translation to make the value understandable by a user of the taxonomy.

3.2 XML Schema Enumerations

This option uses an XML Schema enumerated data type, which restricts the values that may be reported against the concept to one of a provided list of values.

Characteristics and consequences:

• Defines a new data type at the lowest level of XBRL enabling maximum reuse of the list for multiple concepts. In some circumstances, this can lead to version churn of taxonomies since the taxonomy will need to be changed every time the list changes.
• Does not allow selection of multiple values for a fact³.
• Allows the list of allowed values to be extracted from the schema files for display to users.
• Results in schema validation errors which may require special handling to be understandable by end users.

3.3 Enumerations

Enumerations is a mechanism for defining enumerated lists in an XBRL taxonomy, allowing the lists to be structured and labelled in a similar manner to other taxonomy components. More details can be found in the Enumerations in XBRL guidance document.

Characteristics and consequences:

• Validation of facts using Enumerations is implemented by any XBRL processor that supports the Enumerations module.
• XBRL processors have access to details of the valid values, including their labels, so can provide clear, localised error messages.
• Enumerations lets facts to take multiple values from the list of allowed values.
• Enumerations are not "baked in" at the XML level, meaning that it is possible to change the items in the list in extension taxonomies.
• Allows for allowed values to be extracted from the schema files for display to users.
• At a technical level, the list of allowed values for an enumeration are defined using the same mechanism as domain members. This allows the same domain members hierarchies to be re-used to define allowed values applied to both reportable concepts and dimensions.

3.4 XBRL Formula Rules

In this case, the type of the reportable concept would typically be a simple string type and XBRL formula rules are used to define the allowed values. The XBRL formula rules are evaluated against the report to verify that the value provided is valid.

Characteristics and consequences:

• The definition of XBRL formula rules is considerably more technically challenging than any of the other approaches listed here, although higher level abstractions of formula may be available.
• XBRL formula rules allows for the ability to apply more flexible definition than a fixed list of allowed values. For example an allowed value can be specified depending on other conditions.
• XBRL formula rules allows for customisable messages to be defined as part of the taxonomy for when an incorrect value is provided.
• XBRL formula rules can validate facts reporting multiple values from the list of allowed values.
• XBRL formula rules requires adjustment of the formula rule itself to bring additional allowed values into scope.
• It is difficult or impractical to process XBRL formula rules to derive the list of allowed values for presentation or reference to the user.
• XBRL formula rules operates on a report, meaning that an incorrect value can only be detected once a complete document is created and validated. Other approaches can operate at an individual fact level, and provide immediate feedback on the validity of values.
• XBRL formula rules are part of the XBRL specification allowing those looking for standards-only approaches to use a business rule level list of allowed values.
• Using the features of XPath, it is possible for XBRL formula rules to reference an externally defined list of allowed values that is defined in an XML file at any accessible URL. This means that the list can be defined outside the taxonomy files themselves, however it should be noted that the file in which they are defined will be pulled in as part of formula validation, so this approach is unlikely to help in cases where the list is very large, or the publisher wishes to keep the full list private.

3.5 External business rules

In this case, the allowed values are evaluated using a mechanism external to the XBRL specification. This may be a proprietary business rules language or bespoke code that is written for this purpose. In general, external business rules have the same characteristics and consequences as XBRL Formula.

Characteristics and consequences different to XBRL Formula:

• Unlike the other options, external business rules are not part of the XBRL specifications and will therefore not be enforced by a standard XBRL processor.
• There may be inconsistent or no tool support for validating the lists.
• The technology employed may or may not natively support XBRL. In the case where the tooling does not natively support XBRL, additional syntax restrictions on the XBRL reports may be required to be able to process reports.
• Additional features may be possible such as validating against external lists.
• Decouples the list from the XBRL taxonomy meaning that taxonomies can remain stable while the allowed values are changed.

4 Evaluation of options and identification of good practice

The table below shows a comparison in relative terms between the options identified for each of the list characteristics and requirements given in this section. Once the list characteristics have been understood, the most suitable approach can be derived from this table.

4.1 Comparison of list characteristics match to identified approaches

From the table, we find that we can separate the options into two groups:

• Group 1: Options where the list is in a usable form in the taxonomy (Boolean, XML Schema Enumerations and Enumerations).
• Group 2: It is impractical or not desired to define all allowed values in the taxonomy (XBRL formula rules, External rules).

Within Group 1, Enumerations show as being significantly more flexible in usage than Booleans or XML schema enumerations. The only case where these may be considered to be stronger is if there is a requirement that the list should be understandable by looking at the raw reported values. This is not usually a consideration for XBRL documents which are fundamentally linked to a taxonomy and therefore it is good practice is to use Enumerations when a list is fully given in the taxonomy.

Within Group 2, each option has different characteristics and judgement would be required to select the correct one for the taxonomy. This may include non-functional requirements specific to the filing programme that override other considerations. When this is not the case, areas of differentiation in this analysis are:

• External rules do not need the list to be included in the taxonomy.
• XBRL formula rules requires a taxonomy release for any changes to scope.

4.2 General good practice for lists

The main conclusion of this document is that Enumerations should be used when creating a list of allowed values unless there are specific reasons not to use this feature.

In addition, we note that whichever mechanism is used to define the list values, it is good practice to describe the list in a label attached to the concept.

Finally, in cases where lists are the same (or are intended to be the same) the same list definitions should be reused, i.e., one list should not use 2-letter codes while another uses full descriptions as in Figure 1.

Figure 1: Case where good practice would have been to define the list once.