Including XBRL Reports in Taxonomy Packages 1.0

Working Group Note 14 August 2018

Copyright © 2018 XBRL International Inc., All Rights Reserved.

This version:
Paul Warren, XBRL International <>
David Bell, UBPartner <>
Herm Fischer, Mark V Systems <>
Mark Goodhand, CoreFiling <>


Circulation of this Working Group Note is unrestricted. Other documents may supersede this document. Recipients are invited to submit comments to, and to submit notification of any relevant patent rights of which they are aware and provide supporting documentation.


The XBRL Taxonomy Packages specification defines a standard for distributing XBRL taxonomies within ZIP files. The specification was originally intended to be used only for the distribution of taxonomies, and not for iXBRL and XBRL reports (instance documents), but it is now recognised that this may be a useful application of the specification. This Working Group Note addresses some of the issues around doing this, and suggests a preferred approach for how XBRL and iXBRL reports should be included within taxonomy packages.

Table of Contents

1 Introduction
1.1 Data vs metadata
2 XBRL report discovery
2.1 File extensions
2.2 Multiple reports
3 Taxonomy references
4 URL remappings
5 Taxonomy package metadata


A References
B Intellectual property status (non-normative)
C Acknowledgements (non-normative)
D Document history
E Errata corrections in this document


1 Example file structure
2 Example remappings

1 Introduction

The XBRL Taxonomy Packages specification [Taxonomy Package] defines a standard way for distributing an XBRL taxonomy as a ZIP file, with additional metadata that can ease the automated consumption of the taxonomy. This metadata includes:

  1. Remappings, that allow absolute, public URLs to be mapped onto files within the ZIP file.
  2. Descriptive metadata about the package itself, including name, version and date of publication.
  3. A list of taxonomy entry points that can be used as the starting point for DTS discovery within the package.

The specification neither endorses nor prohibits the inclusion of files other than XBRL taxonomy files within the package. In reporting environments where preparers may provide an extension taxonomy to support an XBRL [XBRL 2.1] or iXBRL [Inline XBRL Specification] report, a similar packaging issue may arise, as the report will contain references to the report which need to be resolved to files within the extension taxonomy. This can be by relative references, in which case it is important to preserve the relative locations of the report and its taxonomy, or absolute references, in which case it is convenient to be able to re-map them to a local copy of the taxonomy.

1.1 Data vs metadata

The Specification Working Group opted to exclude explicit support for XBRL or iXBRL reports from the Taxonomy Packages specification for a number of reasons. One of these was a desire to avoid reinforcing the notion that reports and extension taxonomies should be published as part of the same publication cycle. Reports are typically prepared on a regular basis (e.g. monthly, quarterly or annually) and contain the data being reported. The taxonomy, including any extension taxonomy, defines the structure of the report, and need not necessarily change from one reporting period to the next.

Comparability of reports is improved if there is consistency of the report structure between subsequent reports, and so there is an argument that extension taxonomies should be published separately from the report, and only updated if a change is needed to the report structure.

The Working Group recognises that the infrastructure required to support separation of extension taxonomies from XBRL and iXBRL reports adds complexity to a filing system, and that combining the XBRL report and extension taxonomy into a single package can simplify the task of maintaining references from the report to the taxonomy.

2 XBRL report discovery

In order to allow software to automatically locate XBRL and iXBRL reports contained within a taxonomy package, this note defines a convention for their location and naming.

The Taxonomy Packages specification requires that the package contains a single, top-level directory named consistently with the ZIP file itself. This note recommends that XBRL and iXBRL reports are placed within a subdirectory of this top-level directory named reports. Taxonomy files may be placed in any other directory. It is common practice to place taxonomy files within a directory structure that reflects the absolute URL from which they are remapped, with the first level of the structure reflecting the hostname part of the URL.

Example 1: Example file structure

The example below shows the file structure for a taxonomy package containing a report (myreport.html) and a taxonomy.


2.1 File extensions

XBRL reports should have a .xbrl extension, and iXBRL (Inline XBRL) reports should have a .html extension.

2.2 Multiple reports

Multiple .html or .xbrl files within the reports directory will be considered to be separate reports.

Multiple .html files within a subdirectory of the reports directory will be treated as a single Inline XBRL Document Set.

Multiple Inline XBRL Document Sets can be provided by including multiple subdirectories of the reports directory.

.xbrl files should not be placed within subdirectories of the reports directory.

In order to avoid the possibility of providing conflicting or inconsistent data, if the package includes an iXBRL report, it should not also include a copy of the XBRL data which can be extracted from it. Consumers of the iXBRL report can perform this extraction using standard software, if required.

3 Taxonomy references

Taxonomy packages provide a mechanism for remapping absolute, public URLs to files within the package. This can be used to give the taxonomy files within the package an absolute URL, even if they are not actually published at that location. This URL can then be used to reference the taxonomy from the report.

Example 2: Example remappings

In the example above, the catalog.xml file could include a remapping from:



This will remap all URLs starting with to the corresponding location within the directory.

This allows the XBRL report to include a taxonomy reference (using the <xbrli:schemaRef> element) to the absolute URL:

which will be resolved to the taxonomy.xsd file within the package.

Absolute URLs, resolved via remappings, as shown in the example above, are the preferred way to reference an extension taxonomy from an XBRL or iXBRL report included within a taxonomy package, and should be used if the taxonomy package provides remappings for the taxonomy.

If the package does not provide remappings then it is acceptable to use a relative reference from the report to the taxonomy files.

The taxonomy file or files referenced by the report should match an entry point defined in the taxonomy package metadata. If the entry point includes multiple entry point documents then the report should include references to all of them (using <xbrli:schemaRef> and <xbrli:linkbaseRef> elements). It should be noted that use of <xbrli:linkbaseRef> is discouraged, and is not expected to be supported by future drafts of the XBRL Open Information Model specification [OIM].

4 URL remappings

Remapped URLs for taxonomy files within the package should be unique, and should not be redefined in other packages. This can be achieved by:

  1. Choosing a hostname part for the URL that is within a domain owned by the entity that is the subject for the report. For example, if Acme Corporation ownes the domain acme.tld, the host part of the URL could be xbrl.acme.tld.
  2. The path component of the URL should include a version identifier. This could be a date, or could use other versioning scheme.

The remapped prefix should include the version identifier.

5 Taxonomy package metadata

XBRL and iXBRL reports must not be included as entry points in the taxonomyPackage.xml file.  The Taxonomy Packages specification [Taxonomy Package] requires that entry points include only taxonomy schema or linkbase files.

Appendix A References

Inline XBRL Specification
XBRL International Inc.. "Inline XBRL Part 1: Specification 1.1"
Philip Allen.

XBRL International Inc.. "XBRL Open Information Model"
Paul Warren.

Taxonomy Package
XBRL International Inc.. "Taxonomy Packages 1.0"
Paul Warren
, and Herm Fischer.
XBRL 2.1
XBRL International Inc.. "Extensible Business Reporting Language (XBRL) 2.1 Includes Corrected Errata Up To 2013-02-20"
Phillip Engel
, Walter Hamscher, Geoff Shuetrim, David vun Kannon, and Hugh Wallis.

Appendix B 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 (


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 (

Appendix C Acknowledgements (non-normative)

Appendix D Document history

14 August 2018Paul Warren

Initial public release.

Appendix E Errata corrections in this document

This appendix contains a list of the errata that have been incorporated into this document. This represents all those errata corrections that have been approved by the XBRL International Base Specification and Maintenance Working Group up to and including 14 August 2018. Hyperlinks to relevant e-mail threads may only be followed by those who have access to the relevant mailing lists. Access to internal XBRL mailing lists is restricted to members of XBRL International Inc.

No errata have been incorporated into this document.