Copyright © XBRL International Inc., All Rights Reserved.
Circulation of this Public Working Draft is unrestricted. This document is normative. 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.
This specification defines a standard format and location for a manifest file that can be included in such ZIP files that allows compliant tools to identify the entry points automatically. It provides for inclusion of URL remapping, which can provide public locations (URLs) for files within the package.
1 Introduction
1.1 Relationship to other work
1.2 Namespaces
1.3 Conventions used in this document
2 Taxonomy Package
2.1 Package Structure
2.2 The taxonomyPackage.xml file
2.2.1 Taxonomy metadata
2.2.1.1 The tp:identifier element
2.2.1.2 The tp:name element
2.2.1.3 The tp:description element
2.2.1.4 The tp:version element
2.2.1.5 The tp:publisher element
2.2.1.6 The tp:publisherURL element
2.2.1.7 The tp:publicationDate element
2.2.2 Entry points
2.2.2.1 The tp:entryPoint element
2.2.2.2 The tp:name element
2.2.2.3 The tp:description element
2.2.2.4 The tp:version element
2.2.2.5 The tp:entryPointDocument element
2.2.3 Superseded taxonomy packages
2.2.3.1 The tp:supersedesTaxonomyPackages/tp:taxonomyPackage element
2.2.4 Versioning Reports
2.2.4.1 The tp:versioningReport element
2.3 The catalog.xml file
2.3.1 Applying remappings
2.4 Multi-lingual elements
A References
B Schemas (normative)
B.1 taxonomy-package.xsd
B.2 taxonomy-package-catalog.xsd
C Intellectual property status (non-normative)
D Acknowledgements
E Document History (non-normative)
F Errata Corrections incorporated in this document
1 Namespaces and namespace prefixes
1 Example file structure
2 Example of superseded taxonomies
eXtensible Business Reporting Language [XBRL 2.1] defines a standard XML-based syntax for business reports. This syntax is based around reporting concepts which are defined in an XBRL taxonomy. Due to the nature of the domains to which XBRL is typically applied, these taxonomies are often very complex, and made up of many constituent XML files. Typically, the majority of these files can be considered internal to the definition of the taxonomy, whilst a small number are intended to be used as "entry points" by XBRL tools.
For convenience XBRL taxonomies are typically distributed as ZIP files, with accompanying human-readable documentation describing which of the component files should be considered entry points. This specification defines a standard format and location for a manifest file that can be included in such ZIP files that allows compliant tools to identify the entry points automatically.
The specification also allows the inclusion of remappings, which provide public locations for the files within the package. This allows XBRL tools to treat the contents of the package as an offline copy of taxonomies published at an Internet location, without the need for additional configuration.
This specification depends upon the XML Specification [XML]. In the event of any conflicts between this specification and the specifications upon which it depends, this specification does not prevail.
This Specification uses a number of namespace prefixes when describing elements and attributes. These are:
| Prefix | Namespace URI |
|---|---|
tp | http://xbrl.org/PWD/2015-01-14/taxonomy-package |
tpe | http://xbrl.org/PWD/2015-01-14/taxonomy-package/errors |
er | urn:oasis:names:tc:entity:xmlns:xml:catalog |
xs
|
http://www.w3.org/2001/XMLSchema
|
Where this Specification identifies an element or attribute which includes a
prefix described above, for example, <tp:taxonomyPackage> ,
this should be interpretted as a qualified name [XML Names], and as such, implementers MAY use any
prefix (or no prefix) which resolves to the correct namespace.
The key words discoverable taxonomy set or DTS, taxonomy schema and linkbase in this document are to be interpreted as described in the [XBRL 2.1] specification.
The key words XBRL Versioning Report in this document are to be interpreted as described in the [VERSIONING] specification.
The Taxonomy Package is an archive file that contains an XBRL taxonomy and additional metadata, conforming to the format and constraints defined in this specification..
A Taxonomy Package MUST conform to the .ZIP File Format Specification [ZIP].
A Taxonomy Package MUST contain a single top-level directory, with all other files being contained within that directory or descendant subdirectories. The name of the top-level directory MUST be the same as the name of the Taxonomy Package with the .zip file extension removed.
The top-level directory MUST contain a sub directory named META-INF, which in turn MUST contain a taxonomyPackage.xml file. The META-INF directory MAY contain a catalog.xml file (see Section 2.3). The META-INF directory MAY also contain other files, but no syntax or semantics are prescribed for such files by this specification.
All filenames prescribed by this specification MUST be treated as being case-sensitive.
In a ZIP file named SampleTaxonomyPackage-v1.0.zip, all content would be contained within a directory called SampleTaxonomyPackage-v1.0, or descendant subdirectories.
SampleTaxonomyPackage-v1.0/
META-INF/
taxonomyPackage.xml
catalog.xml
file1.xsd
file2.xml
directory1/
file3.xsd
file4.xml
directory2/
file5.xsd
file6.xml
The taxonomyPackage.xml file MUST be an XML file [XML] with a root element of <tp:taxonomyPackage> , and MUST conform to the taxonomy-package.xsd schema (Appendix B.1).
A Taxonomy Package can provide metadata about the taxonomy. Certain items of metadata MAY be provided in multiple languages. References to elements in this section refer only to those elements present as children of the <tp:taxonomyPackage> element.
The Taxonomy Package Schema has an open content model, allowing the inclusion of additional elements and attributes from other namespaces. This is deliberate, and is intended to allow the inclusion of additional meta-data defined either as part of future XBRL International specifications, or project-specific extensions. It should be noted that custom extensions to any specification risks the creation of interoperability issues, and as such, implementers should seek to minimise such extensions, and are encouraged to provide requirements for extensions that are likely to be of general use to the feedback address noted above.
The <tp:identifier> provides a URI that uniquely identifies the package.
The <tp:name> element provides a human-readable name for the taxonomy. The <tp:name> element is a Multi-lingual Element.
The <tp:description> element provides a human-readable name for the taxonomy. The <tp:name> element is a Multi-lingual Element.
The <tp:version> element provides a version identifier for the taxonomy as a whole.
The <tp:publisher> element describes the entity responsible for publishing the taxonomy. The <tp:publisher> element is a Multi-lingual Element.
The <tp:publisherURL> element provides a URL for the entity publishing
the taxonomy. This element SHOULD be used to provide the
primary website of the publishing entity. The URL used
SHOULD be the same as that used in other Taxonomy Package published by the same
entity.
A Taxonomy Package MAY provide an ordered list of entry points. An entry point is a set of URLs that define a logical starting point for the DTS discovery process, as defined in [XBRL 2.1]. Each entry point can be documented with name, description and version number. If more than one entry point is defined, the document order in which they are defined SHOULD be used to provide a default ordering when presenting the contents of the Taxonomy Package.
The <tp:entryPoint> element defines an entry point. References to elements in the following sections refer only to those elements present as children of the <tp:entryPoint> element.
The <tp:name> element provides a human-readable name for the entry point. The <tp:name> element is a Multi-lingual Element.
The <tp:description> element provides a human-readable name for the entry point. The <tp:name> element is a Multi-lingual Element.
The <tp:version> element provides a version identifier for the entry point.
The <tp:entryPointDocument> element defines a document that forms part of this entry point. The @href attribute provides a URL to the document. This URL is subject to remappings, and as such the URL SHOULD be the canonical, published location of the document rather than a relative reference to a file within the package.
Relative URLs MUST undergo XML Base resolution [XML Base].
The URL MUST resolve to a taxonomy schema or a linkbase.
After applying remappings, the <tp:entryPointDocument> will typically resolve to a document within the taxonomy package, but this is not required.
More than one <tp:entryPointDocument> element may appear within a <tp:entryPoint> element. In this case, the combined set of URLs provided will be used for the starting point for the DTS discovery process [XBRL 2.1]. This allows a Taxonomy Package to provide DTSs that are obtained from discovery starting at multiple documents without introducing additional schema files into the ZIP file to provide the necessary grouping.
A Taxonomy Package MAY optionally provide a list of identifiers (see Section 2.2.1.1) for other Taxonomy Packages which are superseded by the current package. This information is intended to be used by software to provide structure to an index of taxonomies, or to direct users to older or newer versions of a taxonomy. It is not intended to convey any information about whether or not superseded taxonomies may be used for the preparation of new XBRL reports within a given reporting environment.
The tp:supersedesTaxonomyPackage/tp:taxonomyPackage element provides the identifer
of a Taxonomy
Package which is superseded by the current taxonomy.
The superseding relationship should be considered to be transitive.
Taxonomy Package A declares that it supersedes Taxonomy Package B. In turn Taxonomy Package B supersedes Taxonomy Package C. In this case, Taxonomy Package A should be considered to supersede Taxonomy Package C, and as such it is not necessary to declare this directly in Taxonomy Package A.
In general, a Taxonomy Package need only list the most recent Taxonomy Package
which it supersedes. The <tp:taxonomyPackage> element is allowed to occur
multiple times, primarily in order to cope with a scenario where multiple
taxonomies are merged into a single taxonomy.
A Taxonomy Package MAY optionally provide a list of references to XBRL Versioning Reports, which provide information about the differences between the current taxonomy and other taxonomies.
The <tp:versioningReport> element identifies an XBRL Versioning Report that is relevant to this Taxonomy Package. The @href attribute provides a URL to the document. This URL is subject to remappings, and as such the URL SHOULD be the canonical, published location of the document rather than a relative reference to a file within the package.
Relative URLs MUST undergo XML Base resolution [XML Base].
The URL MUST resolve to an XBRL Versioning
Report. After applying remappings, the <tp:entryPointDocument>
will typically resolve to a document within the Taxonomy Package , but this is
not required.
A Taxonomy Package can provide remappings that allow one URL to be substituted for another during URL resolution. The typical usage for this is to allow a public, absolute URL (typically using the "http" scheme [URI]) to be resolved to a file within a Taxonomy Package. This allows processors to use copies of published taxonomies provided by a Taxonomy Package, rather than retrieving the taxonomy files from the Internet.
Remappings are specified by the inclusion of the optional catalog.xml file within the META-INF directory of a Taxonomy Package, conforming to a restricted subset of the XML Catalog specification [XML Catalogs].
If present, the catalog.xml file MUST be a valid XML Catalog file, as defined by the XML Catalog specification [XML Catalogs] and MUST also conform to the restricted schema defined by this specification (see Appendix B.2).
A processor SHOULD apply remappings to any URL that needs to be resolved in the course of processing XBRL files. Remappings are applied by following the process defined for Rewrite Entries (specifically, the rewriteURI entries allowed by the restricted schema) in the XML Catalog specification [XML Catalogs].
The XML Catalog specification allows for remappings specified within a single catalog file to overlap, that is, for one prefix to be the same as the first part of another. In this case, the longest matching prefix is to be used.
A Taxonomy Package MUST NOT include a catalog file which
includes more than one rewriteURI element with the same value
(after performing URI Normalization, as prescribed by the XML Catalog
Specification) for the @rewritePrefix attribute.
This is an additional restriction, not specified by the XML Catalog
Specification, as the behaviour in this case is undefined.
Neither the XML Catalog specification nor this specification prescribe behaviour for overlapping remappings obtained from different files. Processors SHOULD signal a warning when configured with multiple Taxonomy Packages that provide overlapping remappings.
Taxonomy Packages are intended to provide a convenient, local copy of files that are published on the internet. They are not intended to support overloading of URLs, such that a single URL can resolve to different documents in different contexts. As such, remappings provided by a Taxonomy Packages are expected to be globally applicable and Taxonomy Packages cannot be used to be used to provide alternative versions of a file at a single URL based on where that file is referenced from.
Taxonomy Packages should provide remappings that are sufficiently specific that they avoid the risk of overlapping with other packages. Similarly, the file for any given URL should appear in at most one Taxonomy Package; where taxonomy files are re-used by multiple other taxonomies, they should be included in a separate, common Taxonomy Package, rather than bundled with each Taxonomy Package that uses them. This reduces the possibility of different taxonomies relying on different versions of the same URL.
A Multi-lingual Element is an element that can be repeated in order to provide translations of the text content in different languages. Where an element is specified as being a Multi-lingual Element, the following additional constraints are applicable:
@xml:lang attribute MAY appear on an ancestor element.
@xml:lang declaration MUST be unique across sibling occurrences of the same Multi-lingual element.
The following is the XML schema provided as part of this specification. It is normative. A non-normative version (which should be identical to this except for appropriate comments indicating its non-normative status) is also provided as a separate file for convenience of users of the specification.
NOTE: (non-normative) Following the schema maintenance policy of XBRL International, it is the intent (but is not guaranteed) that the location of a non-normative version of this schema on the web will be http://www.xbrl.org/PWD/2015-01-14/taxonomy-package.xsd.
NOTE: (non-normative) Following the schema maintenance policy of XBRL International, it is the intent (but is not guaranteed) that the location of a non-normative version of this schema on the web will be http://www.xbrl.org/PWD/2015-01-14/taxonomy-package-catalog.xsd.
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).
| Date | Author | Details |
|---|---|---|
| 12 February 2013 | Herm Fischer |
First XBRL International draft created, based on Appendix D. |
| 19 April 2014 | Paul Warren |
Support for additional meta-data (publisher, versioning reports, date, superseded taxonomies) and more prescriptive file structure. |
| 21 October 2014 | Paul Warren |
Introduce META-INF directory. Require that top-level directory matches name of ZIP file. |
| 09 December 2014 | Paul Warren |
Switch to use of restricted catalog files for remappings. Updated name of supersededTaxonomies element to supsersededTaxonomyPackages, and corresponding changes. |
| 14 January 2015 | Paul Warren |
Updated for new PWD. |
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 Specification Maintenance Working Group (SWG) up to and including 14 January 2015. 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.