Copyright © 2018 XBRL International Inc., All Rights Reserved.
Circulation of this Working Group Note is unrestricted. Other documents may supersede this document. Recipients are invited to submit comments to spec@xbrl.org, 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.
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
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:
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.
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.
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.
The example below shows the file structure for a taxonomy package containing a report (myreport.html) and a taxonomy.
SampleTaxonomyPackage-v1.0/
META-INF/
taxonomyPackage.xml
catalog.xml
xbrl.example.com/
v1/
taxonomy.xsd
taxonomy-linkbase.xml
reports/
myreport.html
XBRL reports should have a .xbrl extension, and iXBRL (Inline
XBRL) reports should have a .html extension.
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.
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.
In the example above, the catalog.xml file could include a
remapping from:
https://xbrl.example.com/v1/
to:
../xbrl.example.com/v1/
This will remap all URLs starting with
https://xbrl.example.com/v1/ to the corresponding location within
the xbrl.example.com/v1/ directory.
This allows the XBRL report
to include a taxonomy reference (using the <xbrli:schemaRef> element)
to the absolute URL:
https://xbrl.example.com/v1/taxonomy.xsd
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].
Remapped URLs for taxonomy files within the package should be unique, and should not be redefined in other packages. This can be achieved by:
acme.tld, the host part of the URL could be xbrl.acme.tld.The remapped prefix should include the version identifier.
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.
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 (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 (www.xbrl.org/legal).
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.