Table of Contents

1 Introduction

In an XBRL reporting programme, new taxonomies are released to reflect business and technical requirements changes. Taxonomy releases are typically identified by their version. This guidance describes best practices for managing taxonomy versioning, including detail on information that should be provided. It is targeted towards taxonomy authors and taxonomy architects. The scope of this guidance is limited to taxonomy versioning mechanisms for public release.

2 Versioning taxonomy releases

Taxonomies are released as part of regular update cycles or on an ad-hoc basis to address business requirements, technical solutions, or fixes. No matter how small, any change, even a typo in a label, is considered a taxonomy release. There is the need to identify each release of the taxonomy to ensure uniquely so that:

• The XBRL reports refer to the correct version of taxonomy and thus can be correctly interpreted;
• The XBRL reports are evaluated against an appropriate set of validation rules defined in the taxonomy; for example, a change in the severity of a validation rule can alter the validation of the report; and
• Conflicts between definitions from different taxonomy versions are avoided; for example, the software may not be able to identify which version to use when not uniquely identified.

Taxonomies are identified using versioning schemes, which are discussed in detail below.

3 Versioning schemes

A taxonomy author can choose from different versioning schemes to uniquely identify each version of their taxonomy. Typical version schemes are based on:

3.1 Dates

Taxonomy versions are identified using a date or year – usually the publishing date.

• These simple versioning schemes generally easy to understand.
• The date of taxonomy version may differ from the date from which the taxonomy becomes applicable for reporting. The guidance on communicating taxonomy changes recommends including the effective date of a taxonomy the change document.
• Versioning based on dates may not be able to capture other semantics such as type of release (e.g. major or minor).

For example, the annual IFRS accounting taxonomy is identified by the year of release (e.g. "The IFRS Accounting Taxonomy 2022"). The taxonomy reflects the presentation and disclosure requirements of the IFRS Accounting Standards at 1 January of that year. The taxonomy file URL names reflect the publication date, for example https://xbrl.ifrs.org/taxonomy/2022-03-24/full_ifrs_entry_point_2022-03-24.xsd

3.2 Numbers

Taxonomy versions are identified using incremental numbers.

• Numbers are split into parts to identify major and minor releases, or other semantics.
• The German E-Bilanz/HGB taxonomy uses a version number mechanism. Each year the release of a new taxonomy represents a unique version number. For example, "E-Bilanz / HGB-Taxonomie Version 6.5".
• The Central Bank of Russia uses three parts numbers (e.g. 4.3.1) for taxonomy versions to identify versions for the development cycle, data model structure and business rules.

3.3 Combination

Taxonomy versions are identified using a combination of dates, numbers, or standard text (draft, consultation).

• FRC UK uses this scheme where a current taxonomy is identified as "2022 UKSEF 1.0.0". In this approach, there is a date and version number schemes.
• The EBA taxonomy contains frameworks, and each framework has one or more modules. The version scheme for these modules consists of a descriptive part that includes the owner, the framework, and the name and number of the legislation on which the data collection is based, followed by the publication date.
  • For example, the entry points for three versions of the COREP Large Exposures module published by the EBA based on the same legislation (cir-680-2014), once in 2018 and twice in 2019, are identified as follows
  • http://www.eba.europa.eu/eu/fr/xbrl/crr/fws/corep/cir-680-2014/2018-07-31/mod/corep_le_con.xsd
  • http://www.eba.europa.eu/eu/fr/xbrl/crr/fws/corep/cir-680-2014/2019-04-30/mod/corep_le_con.xsd
  • http://www.eba.europa.eu/eu/fr/xbrl/crr/fws/corep/cir-680-2014/2019-11-15/mod/corep_le_con.xsd

Considerations for choosing versioning schemes

• Choose a versioning scheme closely related to the taxonomy release cycle. For example, a taxonomy planned to be released annually may prefer date-based versioning. A taxonomy that does not have releases at set intervals may prefer number-based schemes.
• Choose a versioning scheme that can be consistently followed for all types of updates.
• Consider how to indicate consultation or draft version releases. For example, the IFRS Taxonomy released for consultation is identified as "Proposed IFRS Taxonomy 2021 Update 2", and the taxonomy file names reflect the draft publication date.
• Explain the semantics attached with versioning schemes in the taxonomy architecture document.

4 Where to display version numbers

The taxonomy versioning identifier chosen by the author is reflected in different taxonomy artefacts.

4.1 URL of the taxonomy files

The URL of the taxonomy files hosted at their "official" location typically reflects the taxonomy version. An example is the URL of an IFRS 2021 taxonomy entry point:

http://xbrl.ifrs.org/taxonomy/2021-03-24/full_ifrs_entry_point_2021-03-24.xsd

This includes the date of publication as its version identifier. The URL uniquely identifies the taxonomy, so the version identifier should be included in the URL.

How URLs are remapped in taxonomy packages should also be considered. The version identifier should be at the highest-level directory possible so that remappings across taxonomy packages do not clash. For modular taxonomies where modules are independently versioned, the version identifier should not be at a higher-level directory than the module identifier. Read more about remapping in the Taxonomy Package guidance.

4.2 Taxonomy Package metadata

The Taxonomy Package version element is used to identify the taxonomy version.

The Taxonomy Package identifier element provides a URI that should uniquely identify the package and therefore should also incorporate the taxonomy version.

Both these elements should be used, so a user can easily understand to which version of the taxonomy a package relates.

4.3 The namespace of taxonomy schemas

In XBRL, namespaces are used to disambiguate the taxonomy element names defined in taxonomies. This should be achieved through inclusion of a version identifier in the taxonomy schema namespace.

4.4 Taxonomy filename

In some taxonomies, the file names may also contain a taxonomy version. For example, the filename of one of the label files of the IFRS 2021 taxonomy is lab_full_ifrs-en_2021-03-24.xml. Including the version number in the filename is not necessary to uniquely identify the file, as the version number is also included in the URL hierarchy, but repeating it in the filename may help users working with the taxonomy.

5 Managing versioning of files in a modular taxonomy

A taxonomy can be visualised as a set of modular building blocks. Not all building blocks change in every taxonomy release, so it becomes important to understand which modules need to be assigned a different version. The most straightforward approach is to version taxonomy at the package level, ensuring all taxonomy modules have the same version identifier. In this approach, the URLs of all taxonomy files are updated to reflect the new version for every taxonomy release.

A more sophisticated approach would be to version the taxonomy at the module level. This approach requires detailed analysis and is probably only worthwhile if the lifecycle of the modules is significantly different. For example, EBA and EIOPA taxonomies contain frameworks that are versioned independently. Each released taxonomy package contains only frameworks which have changed.

6 Planning taxonomy releases

Taxonomy maintenance includes planning the taxonomy change cycle and managing releases. A taxonomy author needs to consider the following aspects:

• The taxonomy change cycle can be periodic (taxonomies released at regular periodic time intervals) or agile (taxonomies are released as and when the changes happen).
• An important consideration in deciding the taxonomy change cycle is how often the underlying reporting requirements change, how often those changes affect the users and if the changes can be pooled together to reflect periodic changes.
• Periodic changes may be preferable as the stakeholder can better plan taxonomy change activities.
• The taxonomy author needs to consider the consultation duration, flow of change through the ecosystem and how long this takes.
  • This understanding will help time the taxonomy release adequately ahead of when required for report submission.

6.1 Bug fix releases

There are scenarios in which taxonomies need to be released for bug fixes. These could be in between the planned releases. Bug fixes in the taxonomies are easier and cheaper to implement before the taxonomy is being used.Bug fixes in taxonomies in production need to consider the reports already submitted to the data collector and plan if any corrective action in relation to already submitted reports is required.

Bug fixes are sometimes released as a 'hotfix' in which the taxonomy's official location is unchanged, the taxonomy files hosted at their official are replaced, and a new taxonomy package is released. These are typically done to limit the effort of undergoing a full taxonomy release update. Care must be taken when doing such a 'hotfix' release because:

• Reports prepared using prior taxonomy versions may be invalidated by changes made in the hotfix.
• Taxonomy users may continue to use the offline copies of the previous taxonomy version and may attempt to consume newer reports that rely on a newer package, leading to unexpected errors being reported.

Where hotfix releases are used, they should always be assigned a unique taxonomy version number. For example, a 3-part version number major.minor.patch (e.g. 1.2.3) can be used. The last part should be the "patch" (hotfix) and can be omitted from the taxonomy file URLs and namespaces. Include the complete hotfix version number in the taxonomy package identifier and version elements and accompanying documentation.

Taxonomy release communication should explicitly indicate the need to update software and systems to the latest version of the XBRL taxonomy. There should be a change log for the hotfix to explain the reason for the change and its impact. For detailed guidance on how to communicate the changes between taxonomy versions, refer to the Communicating Taxonomy Changes guidance document.