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 updates¹ 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 enumerations². 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.

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.

3.3 Use codes “as-is” or define custom structures

Codes in the Currency and Country taxonomies can be used either directly (“as-is”) or incorporated into custom hierarchies to be used as enumeration values or dimension values.

3.3.1 Use the standard hierarchy

Where the full list of ISO currency or country codes is required without modification, the standard domain member hierarchy provided in the Currency and Country taxonomy can be reused. At a technical level, this is achieved by referencing the existing hierarchy using the target role on the dimension–domain relationship. This approach ensures consistency with the source taxonomy and avoids duplication.

3.3.2 Define a custom hierarchy

Where only a subset of codes is required, or where a different grouping or structure is needed, taxonomy authors can define a custom domain member hierarchy. This involves selecting the relevant codes from the Currency or Country taxonomy and organising them into a structure that reflects the specific disclosure requirements.

3.3.3 Add custom codes

Where appropriate, taxonomy authors can define additional jurisdiction-specific or custom geographic codes alongside standard country codes, and create a hierarchy that combines domain members from the Country taxonomy with additional taxonomy-defined members. This may be useful, for example, where disclosures need to distinguish sub-national regions, economic zones, reporting groupings, or other geographic categories not represented in the Country taxonomy. Such domain members are taxonomy-specific and should be interpreted according to the meaning and scope defined by the taxonomy or the underlying regulation.

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 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.

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.

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.

Additional language labels for the Currency and Country taxonomies contributed by XBRL jurisdictions or regulators are planned to be made available as modular taxonomy extensions. Taxonomy authors can use these additional language labels with both entry points.

5.2.1 Labels in Other Languages

Taxonomy authors may define additional standard labels in other languages where required by the reporting programme or regulatory framework. These may be used alongside the English labels provided in the taxonomy. Where English labels are not required, taxonomy authors may instead import entry.xsd, as described in Section 5.2.

5.2.2 Alternate English Labels

Taxonomy authors may also define their own English labels where the standard English labels provided by the Currency and Country taxonomies (adopted from the ISO standards) do not fit the intended purpose. This may be useful where taxonomy authors requires local terminology, commonly used abbreviations, alternative spellings, or wording that is more familiar to preparers and users. The following approaches may be used to define alternative labels:

5.2.2.1 Define additional labels using a different label role

Alternative labels (for some or all codes) may be defined using a separate label role³. This role can be referenced as the preferred label role in the presentation tree where required.

5.2.2.2 Define additional labels using regional language variants

Alternative labels (for some or all codes) may be provided using language tags with regional variants (for example, "en-US" or "en-GB") where local conventions differ.

5.2.2.3 Redefine standard labels for all codes

Taxonomy authors may redefine the standard labels for all codes. In this approach 'entry.xsd' should be used, as described in Section 5.2, which does not include the labels from the Currency and Country taxonomies.

5.2.2.4 Provide alternative standard labels and prohibit base labels

Alternative labels may be defined as standard labels overriding the labels from the Currency and Country taxonomies (technically, by prohibiting the base taxonomy label relationships). This approach may be appropriate where changes are only required for a limited number of codes.

5.2.3 Labeling Considerations

Standard labels for deprecated country and currency codes include a date in parentheses to indicate that a code has been withdrawn, or that it was valid only before a specified date.

For example:

• AFA is labelled “Afghani (before 2003-01)”
• AN is labelled “Netherlands Antilles (before 2010-12-15)”

This approach helps users understand from the label itself that the code is no longer current, without needing to inspect references or external code lists. When creating alternate labels, taxonomy authors should use a similar pattern to clearly indicate withdrawn or historical codes.

6 Taxonomy Link

• Currency Taxonomy Current
• Country Taxonomy Current
• The latest "dated" variant of currency and country taxonomy 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.