The XBRL Taxonomy Packages 1.0 specification defines a standard for distributing XBRL taxonomies within ZIP files. This specification has now been widely adopted, and has significantly improved the user experience when working with XBRL Taxonomies.
XBRL Taxonomies are often modular in nature, and depend on other taxonomies either from the same publisher, or from a different publisher. One shortcoming of the Taxonomy Packages 1.0 specification is that it provides no mechanism for documenting such dependencies, forcing users to separately discover and install all packages necessary for a given report.
The complexity of managing taxonomy dependencies has resulted in some taxonomy publishers creating monolithic packages that incorporate all dependencies into a single package. This is contrary to best practice, and creates problems of its own, particularly when the dependencies are managed and published by another entity.
This document describes requirements for a new version of the Taxonomy Packages specification in order to support documentation of dependencies. Dependency tracking was considered during the development of Taxonomy Packages 1.0, but was de-scoped in order to expedite the finalisation of that specification, with the intention of revisiting it later.
XBRL Taxonomies are composed of a set of linked XML files. The links between files are made using URLs, and XBRL processors can download the required taxonomy files from these URLs during the processing of a report.
Fetching taxonomy files in this manner is neither performant nor reliable, and most XBRL tools provide a mechanism for working with offline copies of XBRL taxonomies. The Taxonomy Packages 1.0 specification standardises this approach by allowing taxonomy files to be distributed within a ZIP file package that contains metadata describing how the public URLs used in the links between taxonomy files can be resolved to files within the package. Taxonomy Packages can significantly improve the user experience when working with XBRL, but they introduce a new problem: locating the packages need to consume a report.
XBRL taxonomies often incorporate components published by different entities. These components should be packaged and published by their respective creators. Similarly, a single taxonomy publisher may separate their taxonomy components into multiple packages for ease of management. There is currently no mechanism for a taxonomy package to document other packages upon which it depends, so tools have to be externally configured with necessary taxonomy packages.
This document describes requirements for a taxonomy package dependency mechanism.
Taxonomies may rely on shared components. For example, XBRL International publishes taxonomies to support the use of ISO country and currency codes, and Legal Entity Identifiers (LEIs) in XBRL, and many reporting taxonomies make use of this.
It should be possible for XBRL report and taxonomy tools to automatically obtain taxonomy packages for these shared components when processing a taxonomy that depends on them.
Finding the XBRL taxonomy packages required for a report can be difficult. Experience has shown that taxonomy publishers may not maintain stable URLs from which packages can be downloaded, may replace them with updated packages that do not exactly match the previous version, or may remove them from their website altogether. One way to ensure that taxonomy packages are readily available is to maintain taxonomy package repositories that can provide a single source for all taxonomy packages. This approach is commonly use in software, with repositories such as PyPi (for Python packages) and NPM (for JavaScript packages).
It should be possible for software to obtain XBRL Taxonomy Packages from repositories, as well as directly from the publisher.
Taxonomy Packages are a fundamental, widely-supported building block of XBRL systems.
Breaking changes, even as simple as a change in XML namespace, present a barrier to adoption of Taxonomy Packges 1.1. During the transition period, taxonomy authors or third parties would be forced to convert 1.1 packages to 1.0 form, for use with existing systems, introducing the risk of errors and inconsistencies.
It is preferable to take advantage of the extensibility built in to Taxonomy Packages 1.0, so that every 1.1 package is also a valid 1.0 package, understandable by existing systems without modification.
New metadata elements should be placed in a new namespace, while existing 1.0 elements and package structure are left unchanged.
In general, new XBRL specifications have been adopting JSON in preference to XML.
In order to satisfy the preceding requirement for minimising changes, the syntax for Taxonomy Package metadata should remain in XML. A migration to JSON in the long term is desirable, but should not be tackled as part of satisfying these requirements.
A key requirement of the specification is to enable taxonomy packages to document any other taxonomy packages upon which the taxonomy depends.
It should be possible to identify dependencies based on content. Identification of packages based on their location (by URL) or based on metadata (such as the taxonomy identifier) may not be reliable, because:
By identifying dependencies based on content (via a cryptographic hash of the content), it is possible to reliably determine if a dependency exactly matches the version that was used when the dependent package was prepared.
The use of content addressing supports the use of third party taxonomy repositories, as repositories can maintain an index of packages by content hash, and reliably provide the correct version of the required package, provided that it is in the repository. For example, software vendors looking to provide a seamless experience may enable automated download of required packages from their own repository.
It should be possible to identify dependencies based on taxonomy identifiers.
Taxonomy identifiers are URI that will typically make the publisher and nature
of the taxonomy clear to a user, and may allow a different package to be
substituted if a package with the exact content hash cannot be found.
It should be possible to provide a location hint from which a taxonomy package dependency may be obtained. This will enable automated download of a package in the case that a package is not available from a repository.
Taxonomy Packages currently include a version field, but no structured information about the status of a taxonomy. This makes it difficult for users to distinguish between pre-release drafts and production taxonomies.
The specification should provide a metadata field to allow the status of a taxonomy to be captured. The status field need only capture the difference between "draft" and "final" taxonomies.
Reporting systems using the xBRL-CSV format typically include xBRL-CSV metadata as part of a taxonomy package. This is valid, but there is no standard way to document the xBRL-CSV metadata so that it can be discovered by tools.
The specification should provide a mechanism for associating xBRL-CSV metadata with the entry points in a taxonomy package.
The specification should provide a dedicated (not .zip) file extension for
taxonomy packages. This is intended to: