This document is a review draft. Readers are invited to submit comments to the Taxonomy Architecture Guidance Task Force.


  • Revathy Ramanan, XBRL International Inc.
  • Erwin Kaats, Logius
  • Ben Russell, CoreFiling


  • Paul Hulst, De Nederlandsche Bank
  • David Shaw, Financial Accounting Standards Board
  • Joel Vicente, CoreFiling
  • Paul Warren, XBRL International Inc.

Table of Contents

1 Introduction

Taxonomy change information is useful for stakeholders to understand the impact of changes and plan required actions. This guidance discusses different methods of communicating taxonomy change information and the scenarios in which these are most effective. The guide recommends approaches to communicating taxonomy changes to a diverse range of stakeholders. This guidance is targeted towards taxonomy authors and architects who are looking to communicate taxonomy change information or may be looking for additional feedback while implementing changes. Note that published taxonomy change information may be considered as a permanent feature by stakeholders and may become a dependency for their business processes such as the running or updating of software. The intention to publish taxonomy change information consistently or otherwise should be declared and committed by the taxonomy owners. Taxonomy re-use guidance covers considerations for communicating changes in the case of reusing an existing taxonomy.

2 Types of changes

Taxonomy change information covers different types of changes such as architectural, content or filing rules. The audience to consider for communications of these changes range from those requiring a general understanding of the scope of the change to those requiring exact details of every change. The rest of this section addresses each type of change in terms of the audience and options available.

2.1 Architecture Changes

Architectural changes often have a large impact, but are infrequent in nature. They have an impact on the taxonomy itself and may also have an effect on how the taxonomy is used. Examples of taxonomy architecture changes include:
  • Introduction of new technology (e.g. Extensible Enumerations 2.0, Table Linkbase, Inline XBRL);
  • Removing of old solutions (e.g. tuples);
  • File/directory structure changes; and
  • Changes in use cases (process changes)
Removing or adding new technological solutions are the most disruptive type of change and can have a high impact on the entire reporting chain. Reports may change drastically, for example by switching from tuples to dimensions or by adopting Inline XBRL. Changes in architecture can be made for different reasons, and are often a process rather than a one-off change. Whereas a content change must be taken up by all stakeholders to continue to produce valid reports, a new architectural feature such as the addition of a XBRL reporting template may not be required to continue to produce valid reports. It is impractical to note when the new feature is fully implemented by all taxonomy consumers and so it may never be considered “complete”. It is useful therefore to consider the communication of architectural changes as a process with a preparation, implementation and aftercare phase.

2.1.1 Preparation phase

In the first phase, it is important to allow for bi-directional communication. Stakeholders should be able to give their opinion on changes, and often have a unique perspective that helps shape the project. Consider organising taskforces, sending out requests for comments and providing whitepapers detailing the change from both a business and technical point of view.

2.1.2 Implementation phase

Within the implementation phase, communication moves to more one-directional forms of communication such as webinars, interviews and blogposts. This phase has a clear timeline, which allows using these time-specific options. It is helpful to plan this in advance so types of communication may be mixed. For example, launch a series of blogs and organise a webinar afterwards. This way, stakeholders are able to ask questions that may be raised from reading the blogposts beforehand. Along with timely outreach, this is also the phase in which specifications, formal rules and documentation should be made available.

2.1.3 Post-implementation phase

After organising the implementation outreach, architectural changes need to be implemented across the full reporting process. Depending on the type of change, this may cover an extended period. With this in mind, it is important to future-proof the communication. Make sure that in 5 years, stakeholders are able to read up on the changes, without having had the opportunity to participate in the webinars and taskforces. Documentation in narrative format is useful, as long as it does not refer to temporary sources. Instead of references to webinars or blog posts, refer to documents that contain the (historical) business context required to understand the contemporary decisions.

2.2 Content Changes

This type of change concerns where a change to the taxonomy impacts the contents of reports prepared. A few examples of such changes are:
  • Introduction of new entry-points due to inclusion of additional industry/sector;
  • Change to validation requirement resulting in addition / deletion / modification to XBRL Formula Rules;
  • Change in scope of reporting resulting in new reporting tables; and
  • Changes to underlying reporting requirements needing addition / deletion / modification of individual taxonomy elements or XBRL Dimensional Model.
Taxonomy content changes are generally of interest to report preparers and software vendors to update their products.

2.2.1 Methods of communicating content change information

This section discusses few common methods of communicating changes between taxonomy versions. Methods of communicating change information are usually characterised by target audience, visualisation of information, how well they can be consumed by automation and their ability to capture change reasons. Business-oriented (non-structured) document

This is where a taxonomy author publishes a non-technical document to explain taxonomy changes in a narrative format. Such narrative documents would typically cover topics such as:
  • High-level summary of taxonomy changes;
  • Business background of changes; and
  • Effective date of change
This type of document is useful for business users looking to gain a general understanding of the scope of the change. The document is generally unstructured and is not useful for automating change management in software products. It is a summary document that gives a reference to any additional detailed change information. Change information within the taxonomy

Taxonomy authors may specify taxonomy change as additional structured metadata information using taxonomy components. Examples of such change include:
  • Using “Deprecation labels” to communicate the status of a taxonomy element;
  • Using references to indicate applicability date of concept;
  • Using label roles to explain changes at element level; and
  • Using references roles to specify alternate elements for the ones deprecated elements.
The structured change information can capture granular information at component level and is helpful to preparers and software vendors looking for detailed information. The structured information makes it possible to automate changes in a product and display change information to users. The business reasons for changes for each component can also be captured within the taxonomy. This approach is valuable when there is a strongly enforced lifecycle to taxonomy elements. Change information for relationship trees or dimensional modelling may be challenging to capture using the standard metadata in the taxonomy. Technically-oriented, structured or machine-readable documents

Taxonomy authors may provide change information in structured format. The document is external to the taxonomy. Examples of information that can be provide in such structured format are:
  • List of deprecated elements
  • Standard output for changes that can be derived from technical comparison of taxonomies
  • List of concepts renamed/mapping between old and new concepts
  • List of reporting tables that were added/modified
  • List of data type changes
If the format and content is stable over time, the structured change information helps software vendors to automate processes. This approach is more valuable when:
  • There is a large user community where this being provided will lead to an overall reduction in cost of the filing programme;
  • The user community needs to update applications to work with the new taxonomy; or
  • The user community is not expected to be able to carry out their own difference analysis on the taxonomies
Taxonomy authors may also choose to include business reasons in such documentation. Examples of such formats are:
  • Versioning Reports – The technical specification contains an extensive breakdown of how to document versions changes
  • Information in spreadsheet
  • HTML Files with tracked changes Implicit change information

Some taxonomy changes can be derived by comparing two versions of taxonomies in a piece of software1 to create lists of changes, commonly known as a difference report. Examples of such lists are: elements added, elements deleted or modifications to rules. A difference report is helpful for an audience wanting to understand detailed changes. The difference report can be used by tools to make changes to the products. The visualization of the changes can be intuitively displayed to users. Since two taxonomy files would be technically compared, a difference report cannot communicate the business reasons for changes. Interactive change applications

Taxonomy authors may publish an interactive application for users to understand changes. A range of change information and business reasons can be presented an intuitive manner. However, such applications may not be necessarily of help to software vendors to automate change management in products. Update processes for such applications should be automated to ensure that they are in sync with the taxonomy changes. Efficient maintenance and ensuring user benefits of such applications are crucial considerations to consider with this approach.

2.2.2 Timing of change communication

The time taken for the ecosystem to implement the changes is an essential consideration while planning for taxonomy release and communicating taxonomy content changes. Intimating the stakeholders in advance about the forthcoming changes is beneficial. The advance intimation of changes can be in terms of broad themes such as additions of new forms/disclosures. Publishing a draft taxonomy is one approach for communicating the proposed taxonomy changes. It would be helpful to release the detailed change document(s) (refer to methods of change communication) along with the taxonomy.

2.3 Filing Rules Changes

Filing rules are not part of a taxonomy but are closely related to taxonomy changes. A separate guidance discusses How to prepare and publish filing rules. Additions, modification, deletion to filing rules should be prominently indicated in the human-readable description of the rules. This will help software vendors and other users to focus on rules that have changed while making updates to the products /offerings.

3 Summary recommendations

  • Always provide documentation to explain the changes between taxonomy versions
  • For architectural changes
    • Always provide a narrative summary of business/technical rationale and impact on stakeholders
    • Consider engaging with the ecosystem before the taxonomy is updated
  • For content changes
    • Always provide a business-oriented (non-technical) document that:
      • Gives an idea of the amount of change that has happened
      • Includes business background of changes, rationale for high impact changes, at least in broad themes (e.g., a new reporting area has been included)
      • Explains changes that cannot be derived from a technical comparison of the two versions, for example, renaming of a concept or taxonomy effective dates
    • Consider including change information within the taxonomy as additional structured metadata where applicable
    • Consider including the changes between versions in structured or machine-readable documents facilitating software vendors to automate processes where applicable
  • Always release change information along with the taxonomy
  • Consider intimating in advance about proposed taxonomy changes
  • Always decide how you will communicate changes up front, not on a per-change basis
  • Always make clear the commitment to providing each piece of change documentation as it may be used to drive processes
  • Consider obtaining feedback from users as to whether the change documentation provided is useful
  • Provide documentation to explain the changes between taxonomy versions.
  • Select change communication methods as required for your ecosystems and which can be consistently followed.
  • Intimate in advance about proposed taxonomy changes.

  1. The difference report may assume that the local name of taxonomy elements remains the same. 
This document was produced by the Taxonomy Architecture Guidance Task Force. Published on 2022-06-07.

Was this article helpful?

Related Articles


Would you like
to learn more?

Join our Newsletter mailing list to
stay plugged in to the latest
information about XBRL around the world.

By clicking submit you agree to the XBRL International privacy policy which can be found at xbrl.org/privacy