This document is a review draft. Readers are invited to submit comments to the Best Practices Board.
Table of Contents
1 Introduction
The International Organization for Standardization (ISO) maintains the standard for currency and country representations. These code lists are freely available in digital form and are an important set of lists used to avoid confusion when referring to currencies or countries.
ISO Currency and Country codes are commonly used in XBRL reports worldwide. These codes are used in reports for a variety of reasons, including to:
- qualify exposure breakdowns into currency or country buckets;
- identify the country of counterparties and related parties; and
- specify currency for monetary values.
The XBRL specification requires ISO 4217 currency codes to be used for reporting the units of monetary facts. The Currency Taxonomy enables ISO 4217 code to be used for other reporting purposes, but does not alter how the units for monetary facts should be reported.
XBRL International's Currency and Country Taxonomies represent ISO currency and country codes, which implementers can reference in their own taxonomies. This guidance primarily targets taxonomy architects and taxonomy authors wishing to use currency and country codes in an XBRL reporting framework.
Taxonomies importing the currency and country taxonomies can use the currency and country codes as domain members in a dimensional breakdown or as enumeration values; more on how to use the taxonomies is described in Section 3.
The currency and country taxonomies are published in two different variants: "dated" and "current". These two taxonomies have different versioning approaches. Points to consider when choosing between these variants are described in Section 5.1.
2 Why Use
The Currency and Country taxonomies provide a standard approach for incorporating ISO currency and country codes in XBRL reports. The use of the Currency and Country taxonomies promotes a consistent approach to using these ISO codes in between different reporting environments, thus increasing value for data consumers.
XBRL International has subscribed to the notifications about ISO code updates and has implemented a mechanism to automatically deploy these changes in the Currency and Country taxonomies. The ISO code updates1 in the taxonomies are put through a one-step XBRL Standards Board (XSB) governance review process, ensuring quicker delivery of updated taxonomies. Using the Currency and Country taxonomies lowers the risk of not using the most up-to-date code list. It also reduces the overall cost associated with the maintenance of the code list in an XBRL taxonomy.
3 How to use
This section explains how XBRL reports can use the Currency and Country taxonomies to incorporate codes as an enumeration or dimension values. The Currency and Country taxonomies define the ISO codes as domain members and each taxonomy has a single domain member hierarchy that includes all codes.
The domain members are associated with labels and references, which provide English language names and descriptions, and additional metadata such as the corresponding numeric ISO codes, and information on legacy codes. The architecture document describes the details of the labels and references used in the taxonomies.
3.1 Currency and Country codes as enumeration values
Currency and country codes can be reported as fact values. Depending on the requirements, such facts could take either a single code, or a set of codes. For example, a single currency code could be used to disclose the presentation currency of the report. Multiple country codes could be used to report significant countries of business operations.
Codes in the Currency and Country taxonomies can be used to define an allowed list of values for such facts using enumerations2. To capture a single currency or country code as a fact value, define a concept as a single-valued enumeration type. To capture multiple currency or country codes as a fact value, define a concept as a multi-valued enumeration type.
Where a fact can use any code from the relevant ISO code list, the standard domain member hierarchy defined in the corresponding taxonomy can be used as the domain for the enumeration concept. Where a fact needs to be constrained to a subset of the ISO code list, a custom domain hierarchy should be defined using the required currency or country codes.
3.2 Currency and Country codes as dimension values
Some disclosures may require reporting a fact breakdown by currency or country. For example, a disclosure may require reporting credit exposure by country or investment exposures by significant currencies. Codes in the Currency and Country taxonomies can be used as domain members to model such disclosures.
Modelling a disclosure breakdown by currency or country will require the definition of a dimensional structure that associates the relevant concepts with a dimension that defines the breakdown's meaning. The domain for the breakdown dimension should be defined as follows:
- To use the entire list of currency or country codes as domain members, re-use the standard domain member hierarchy provided by the taxonomy. At a technical level, this is done using "target role" on the dimension-domain relationship to point to hierarchy in the taxonomy.
- To use a subset of the full code list as domain members, create a domain member hierarchy selecting the required codes from the Currency or Country taxonomy.
4 Domains and Dimension Defaults
The Currency and Country taxonomies each define a domain-member hierarchy but they do not define any dimensions that use them. Dimensions should be defined in the reporting taxonomy based on the semantics of the breakdown required.
Reporting taxonomies may define dimension defaults for dimensions using the currency and country code lists. Where the meaning of an unqualified fact value is intended to mean “all currencies” or “all countries”, the relevant domain member element from the taxonomy (CurrencyDomain or CountryDomain) should be used as the default. Where a subset of the code list has been created using a custom domain element, as described in section Section 3.2, and an unqualified fact value is intended to mean all codes in that subset, the custom domain element should be used as the default.
In other cases, it is not generally recommended to use dimension defaults, as it will be applied to all facts in the report, regardless of whether the dimension is meaningful for the concept.
- For enumeration concepts that restrict allowed list to countries or currencies, use the codes from currency or country taxonomy as enumeration values.
- Use the codes from currency or country taxonomy as domain members for dimensional breakdown into countries or currencies.
- Use the domain item defined in the currency or country taxonomy when the dimension represents all currencies or countries.
5 Taxonomy variations and entry points
This section explains considerations for choosing between variants and entry points of the Currency and Country taxonomies.
5.1 Taxonomy Variations
The Currency and Country taxonomies are published in two different variants: "dated" and "current". These two taxonomies have different versioning approaches.
The "dated" taxonomy variation is versioned based on the ISO update issue date. The taxonomy file URLs and namespaces change with each update of the taxonomy. The "current" variant reflects the ISO codes at any point in time. The taxonomy file URLs and namespaces are constant for the "current" variant. Refer to the architecture document for further details on the versioning approach.
The historic codes are deprecated but never deleted and will always be available for reporting; hence, updates to the code list should not invalidate reports prepared against older versions of the "current" taxonomy. The deprecation status is indicated using a property reference on the code. Taxonomy authors can use this information in XBRL Formula rules to check if historic codes have been used, if necessary.
Though the code does not change, the meta-data can change; for example:
- On 2022-07-11, the short name for the country code "TUR" was changed from "Turkey" to "Türkiye". Such changes will result in a standard label change in the taxonomy.
- In 2006-10, the currency "Euro" association with "SERBIA AND MONTENEGRO" was removed, though the "Euro" remained valid for other countries. When this happens, the documentation label for the currency code will change in the taxonomy.
- ISO may reallocate codes. Codes that are no longer in active use go into a 50 year "transitionally reserved" phase, before becoming "formerly used" and eligible for reallocation. Users of the "current" taxonomy should be aware that codes may be reallocated to different countries in future updates to the taxonomy, following the ISO process.
Taxonomy architects and authors should consider the points explained in Table 1 when choosing between the "dated" and "current" variants of The Currency or Country taxonomies to use in their taxonomies.
|
Dated |
Current |
|
|
Reflection of code updates in imported taxonomy |
Taxonomy release required to reflect up-to-date codes in imported taxonomies |
Automatic up-to-date codes reflected in imported taxonomies |
|
Review updates |
Taxonomy authors can review the updates and consider the impact before reflecting the changes in their taxonomy. |
The updates cannot be reviewed to assess applicability and impact. |
|
Offline Copies / Cached Taxonomy |
Software can use offline copies of the taxonomy or a cached version without the risk of invalidating the reports. Reports prepared using the latest taxonomy cannot be processed with an old offline taxonomy copy or cache and would require an update. |
Software may invalidate reports prepared using the latest taxonomy when the offline taxonomy copy is not updated, or the taxonomy cache is not refreshed. |
5.2 Language Entry Point
The currency and country taxonomies have two entry points: one with standard English labels and the other without. Taxonomy architects and authors should consider the points explained in Table 2 when choosing between the entry points of the taxonomy.
|
|
Entry point with English labels |
Entry point without English labels |
|
Entry-points |
entry-en.xsd |
entry.xsd |
|
Use |
When "English" standard labels as provided by ISO can be used for currency or country codes |
When English labels as provided by ISO are not required |
|
Additional Language |
Additional language labels can be added if required |
Standard labels in other language(s) labels MUST be added |
Additional language labels for the Currency and Country taxonomies contributed by XBRL jurisdictions or regulators are planned to be made available as a modular taxonomy extensions. Taxonomy authors can use these additional language labels with both entry points3.
6 Taxonomy Link
The following taxonomies can be found in the XBRL Taxonomy Registry:
7 Sample XBRL Reports
A sample XBRL Report is provided to demonstrate how the Currency or Country Taxonomy codes can be used. The sample report contains the following list of facts:
- A single value enumeration fact to report ‘Reporting Currency’.
- A multi-value enumeration fact to report ‘Operating Countries’.
- Dimension facts reporting ‘Credit Exposure’, qualified by currency codes used as dimension value. The sample taxonomy allows any currency code from the entire list to be used as dimension value for ‘Credit Exposure’.
- Dimension facts reporting ‘Revenue’, qualified by country codes used as dimension value. The sample taxonomy restricts only a few country codes to be used as dimension value for ‘Revenue’.
The sample report can be accessed from this link.
- Use the “current” variant of currency or country taxonomy when up-to-date codes are to be automatically reflected in imported taxonomies.
- Use the “dated” variant of currency or country taxonomy when the changes in currency or country codes need to be reflected in imported taxonomies in a controlled manner.
- Use the ‘currency-en’ or ‘country-en’ entry point in order to include the “English” labels provided by ISO in the importing taxonomy.
-
The initial taxonomy and updates that propose structural change follows the governance and maturity cycle as applicable for technical specification development, or (later) taxonomy-specific governance as defined by the XBRL Standards Board from time to time. ↩
-
To read more about enumerations, refer to this guidance on Enumerations in XBRL. ↩
-
The taxonomy author can also add their version of English labels, if the English label provided by the ISO does not fit the purpose. ↩
This document was produced by the Best Practices Board.
Published on 2024-02-13.
