Currency and Country Taxonomy Architecture Guide 1.0

Working Group Note 14 June 2024

This version
https://www.xbrl.org/WGN/currency-country-taxonomy-architecture/WGN-2024-06-14/currency-country-taxonomy-architecture-2024-06-14.html
Editors
Revathy Ramanan, XBRL International <revathy.ramanan@xbrl.org>
Paul Warren, XBRL International <pdw@xbrl.org>

Table of Contents

1 Introduction

XBRL International's Currency and Country Taxonomies represent ISO currency and country codes which implementers can reference in their taxonomies.

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:

This taxonomy guide discusses the following aspects of the currency and country taxonomies, including:

2 ISO Currency and Country Codes

The International Organization for Standardization (ISO) maintains the standard for currency and country representations. ISO, in turn, appoints a Maintenance Authority (MA) to maintain the resulting code lists. 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. The ISO code lists are particularly focused on ISO2022 messages and similar transactional uses of the codes. They are updated promptly by the MA.

2.1 ISO Currency Code

ISO 4217 specifies the structure for a three-letter alphabetic code and an equivalent three-digit numeric code to represent currencies. SIX Financial Information AG is the official Maintenance Agency of currency codes under ISO 4217. SIX maintains the currency code lists, updates them, and makes them available online. The codes in ISO 4217 can be accessed here.

2.2 ISO Country Code

ISO 3166 provides universally applicable coded representations of names of countries (current and non-current), dependencies, and other areas of geopolitical interest and their subdivisions. The ISO central secretariat itself is the Maintenance Agency (ISO 3166/MA) for this standard and updates, maintains, and publishes changes to the country codes. The codes in ISO 3166 can be accessed on their Online Browsing Platform.

3 Taxonomy Content

The taxonomies define currency and country ISO codes as domain members. The domain members are associated with labels and references.

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.

4 Taxonomy Structure

4.1 Currency Taxonomy Structure

The currency taxonomy contains the following two entry points:

Figure 1 sets out the logical structure of the currency taxonomy.

Figure 1: Currency Taxonomy Structure

4.2 Country Taxonomy Structure

The country taxonomy contains the following two entry points:

Figure 2 sets out the logical structure of the country taxonomy.

Figure 2: Country Taxonomy Structure

4.3 ISO code list common definitions taxonomy

The taxonomy defines custom label roles and property parts used by country and currency ISO code list taxonomies.

Figure 3 sets out the logical structure of the ISO code list common definitions taxonomy.

Figure 3: ISO code list common definitions taxonomy structure

5 Deprecation

5.1 Currency Codes Deprecation

Historical currencies are available in list three of the ISO 4217 standard. The currency taxonomy will also include historical codes to facilitate reporting using historical codes (if required). For such historical currency codes:

5.2 Country Codes Deprecation

Country codes that are no longer in active use go into a 50 year "transitionally reserved" phase, before becoming "formerly used" and eligible for reallocation. Such transitionally reserved codes will be included in the country taxonomy to facilitate historical reporting.

For such transitionally reserved country codes:

6 Versioning

The currency and country taxonomies are published in two different formats: “dated” and “current”. These two taxonomies have different versioning approaches.

6.1 Dated version

6.1.1 Currency Taxonomy Dated Version

The currency taxonomy will be versioned based on the ISO issue date of the currency update. For example, the taxonomy reflecting the changes for currency code updated by ISO on '2023-01-01' and will be versioned as '2023-01-01’.

The ISO currency code is published as two lists: list one and list three. 'List one' has valid currency codes, and 'list three' has historic codes. The two lists are combined into a single list in the currency taxonomy. It is possible that these lists could be independently updated. In this case, the version date of the currency taxonomy will reflect the latest date of update of either list.

The versioning information will be reflected in the URL of the taxonomy files and taxonomy package metadata. Examples of URLs for the currency taxonomy based on ISO currency update date '2023-01-01' would be:

6.1.2 Country Taxonomy Dated Version

The country taxonomy will be versioned based on the ISO issue date of the country update. For example, the taxonomy reflecting the changes for country code updated by ISO on '2023-04-04' and will be versioned as '2023-04-04’.

The versioning information is reflected in the URL of the taxonomy files and taxonomy package metadata. Examples of URLs for the country taxonomy based on ISO country update date '2023-04-04' ' would be:

6.1.3 Public consultation release versioning

Taxonomy releases containing structural changes for public review are identified by their status (PWD/CR/PR) and release date. For example, the URL of the country taxonomy file released on 31 March 2023 as a public working draft (PWD) based on the ISO issue date '2022-11-29’ would be:

http://www.xbrl.org/taxonomy/int/country/2022-11-29/PWD/2023-03-31/entry.xsd

6.2 'Current' version

The country and currency taxonomies will also be provided as current/up-to-date versions reflecting ISO codes at any point in time. 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 taxonomy. ISO may reallocate codes after 50 years of transitional reservation. 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.

The URLs of the up-to-date taxonomy files are:

6.3 ISO code list common definitions taxonomy

The ISO code list common definitions taxonomy will be published as a separate taxonomy package and versioned independent of the currency and country taxonomy. The versioning will be based on taxonomy update date. The versioning information is reflected in the URL of the taxonomy files and taxonomy package metadata.

The URL of the ISO code list common definitions taxonomy reflects the year in which it was finalised:

Public drafts of the taxonomy will include the status and full date of publication, for example:

7 Taxonomy Components

7.1 Custom Label Roles

The currency and country taxonomies use the following custom label roles defined in role-label-code.xsd in the ISO code list common definitions taxonomy:

7.2 Custom Reference Parts

The currency and country taxonomies use the following custom reference parts defined in property-part.xsd in the ISO code list common definitions taxonomy 3:

7.3 Namespaces

The currency taxonomy uses following namespaces, where YYYY-MM-DD are the ISO update date on which the taxonomy is based:

Dated Variant - Currency Taxonomy

Current Variant - Currency Taxonomy

The country taxonomy uses following namespaces, where YYYY-MM-DD are the ISO update date on which the taxonomy is based:

Dated Variant - Country Taxonomy

Current Variant - Country Taxonomy

The ISO code list common definitions taxonomy uses the following namespace:

7.4 Taxonomy Entry Point Absolute URLs

The following table shows the absolute URLs for taxonomy entry points where YYYY-MM-DD is the ISO update date on which the taxonomy is based:

Entry Point Description Absolute URL
Currency List with English Labels Currency codes as domain members for use as dimension values or enumeration values, with ISO 4217 code labels and English language labels (as provided by ISO). Dated Variant - https://www.xbrl.org/taxonomy/int/currency/YYYY-MM-DD/entry-en.xsd
Current Variant - https://www.xbrl.org/taxonomy/int/currency/current/entry-en.xsd
Currency List Currency codes as domain members for use as dimension values or enumeration values. Includes ISO 4217 code labels only. Dated Variant - https://www.xbrl.org/taxonomy/int/currency/YYYY-MM-DD/entry.xsd
Current Variant - https://www.xbrl.org/taxonomy/int/currency/current/entry.xsd
Country List with English Labels Country codes as domain members for use as dimension values or enumeration values, with ISO 3166 code labels, and English language labels (as provided by ISO). Dated Variant - https://www.xbrl.org/taxonomy/int/country/YYYY-MM-DD/entry-en.xsd
Current Variant - https://www.xbrl.org/taxonomy/int/country/current/entry-en.xsd
Country List Country codes as domain members for use as dimension values or as enumeration values. Includes ISO 3166 code labels only. Dated Variant - https://www.xbrl.org/taxonomy/int/country/YYYY-MM-DD/entry.xsd
Current Variant - https://www.xbrl.org/taxonomy/int/country/current/entry.xsd

7.5 Data Types Registry

The ‘dated’ and ‘current’ version of the taxonomy uses the data type “domainItemType” from the 2022 Data Type Registry (DTR) for domain and domain members. Both variants of the taxonomy will continue to use the 2022 DTR version in future updates.

8 Taxonomy Maintenance Plan

XBRL International subscribes to the notifications about updates from the ISO, Maintenance Authority (MA) and has implemented a mechanism to automatically deploy these changes, together with relevant supporting metadata in an XBRL Taxonomy. An example of ISO code update notification can be seen in these links – currency code and country code.

The ISO currency and country code update notification will initiate the currency or country taxonomies update process. The update to the taxonomies will be carried out by XBRL International staff. The updated taxonomy is expected to be published within 30 days of the ISO update notification.

The initial taxonomy and updates that propose structural change will follow 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. Non-structural update to taxonomy will be reviewed and approved by XBRL Standards Board.

Structural changes include changes to taxonomy logical and physical modelling or technical specification updates. Examples of non-structural changes include code updates as per ISO code changes or label updates.

9 Additional Language Labels

While the default currency and country taxonomies include English labels, additional language labels can be contributed by XBRL jurisdictions or regulators. The additional language labels will be made available as a modular taxonomy file and taxonomy package to be referenced in the taxonomy wanting to use them.

The French label file (country-label-fr.xml) for country taxonomy 2022-11-29 would be available at the official location - http://www.xbrl.org/taxonomy/int/country/2022-11-29/fr/country-label-fr.xml and as a separate taxonomy package.

By default, two letter language codes will be used to identify additional language label, but adding sub-codes will be considered if requested. The regional codes will be reflected in the taxonomy file URL and the taxonomy file name as seen above exmaple.

10 Mapping codes to taxonomy

ISO publishes Currency and Country codes in XML formats, which are used to generate taxonomy. The mapping between the source ISO XML and taxonomy artefacts is provided in the section

This section describes mapping of ISO Currency and Country code XML to XBRL taxonomy artefacts. The XML element indicates the element in the ISO code XML file.

10.1 Currency Code - Mapping

ISO currency code XML can be accessed from the links below:

Fund codes is not included (where <CcyNm IsFund="true"> the code is omitted). Precious metal and other non-currency codes that start with "ZZ**_" are also excluded from the currency taxonomy.

List one of the currency codes, includes the following special currency which are excluded from the currency taxonomy.

The mapping for ISO code XML fields to taxonomy artefacts for each currency domain member is as follows:

10.1.1 Reference Information

For all codes:

Withdrawn codes details in property reference (custom parts):

When <WthdrwlDt> is not in YYYY-MM format the month is assumed to be December of the end period. For example, ‘ARY’ was withdrawn during the period ‘1989 to 1990’, the Deprecated Date is this case in specified in the taxonomy as 1990-12. For such cases withdrawal period is captured as an additional reference part in ‘Deprecated Date Description’

10.2 Country Code - Mapping

A sample of ISO country code XML can be accessed from this link - Sample Country Code XML. Country taxonomy includes country codes which has <status> = ‘officially-assigned’ or ‘transitionally-reserved’.

The mapping for ISO code XML fields to taxonomy artefacts for each country domain member is as follows:

10.2.1 Reference Information

For all codes:

Transitionally reserved code details in property reference (custom parts). This will be only for codes with <status> = 'transitionally-reserved'.

Appendix A Intellectual property status (non-normative)

This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to XBRL International or XBRL organizations, except as required to translate it into languages other than English. Members of XBRL International agree to grant certain licenses under the XBRL International Intellectual Property Policy (https://www.xbrl.org/legal).

This document and the information contained herein is provided on an "AS IS" basis and XBRL INTERNATIONAL DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

The attention of users of this document is directed to the possibility that compliance with or adoption of XBRL International specifications may require use of an invention covered by patent rights. XBRL International shall not be responsible for identifying patents for which a license may be required by any XBRL International specification, or for conducting legal inquiries into the legal validity or scope of those patents that are brought to its attention. XBRL International specifications are prospective and advisory only. Prospective users are responsible for protecting themselves against liability for infringement of patents. XBRL International takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Members of XBRL International agree to grant certain licenses under the XBRL International Intellectual Property Policy (https://www.xbrl.org/legal).

  1. There are a small number of English labels where the MA appends “(the)” to the country label – for example “United States of America (the)”. These definite articles are removed programmatically. ↩

  2. A few currency codes have multiple withdrawal dates, for example, ‘VEF’, in which case the latest withdrawn date is used in standard label and property reference. ↩

  3. The term 'withdrawal date' and 'validity end date' are drawn from the ISO currency and country XML formats and are used in the respective contexts. The ISO currency XML uses ‘withdrawal date’ for historical currencies, and the ISO country XML uses the term validity-end-date for transitionally-reserved codes. ↩

  4. The full name is available only if different from the short form, so it makes sense to have the short name as the standard label and full name as verbose. ↩