Copyright © XBRL International Inc., All Rights Reserved.
Circulation of this Proposed Recommendation 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 Conformant Processor
3 Taxonomy Package
3.1 Package Structure
3.2 The taxonomyPackage.xml file
3.2.1 Taxonomy metadata
3.2.1.1 The tp:identifier element
3.2.1.2 The tp:name element
3.2.1.3 The tp:description element
3.2.1.4 The tp:version element
3.2.1.5 The tp:license element
3.2.1.6 The tp:publisher element
3.2.1.7 The tp:publisherURL element
3.2.1.8 The tp:publisherCountry element
3.2.1.9 The tp:publicationDate element
3.2.2 Entry points
3.2.2.1 The tp:entryPoint element
3.2.2.2 The tp:name element
3.2.2.3 The tp:description element
3.2.2.4 The tp:version element
3.2.2.5 The tp:entryPointDocument element
3.2.2.6 The tp:language and tp:languages elements
3.2.3 Superseded taxonomy packages
3.2.3.1 The tp:supersededTaxonomyPackages/tp:taxonomyPackageRef element
3.2.4 Versioning Reports
3.2.4.1 The tp:versioningReports/tp:versioningReport element
3.3 The catalog.xml file
3.3.1 Applying remappings
3.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
3 Use of remappings
conformant processor
Multi-lingual Element
taxonomy package
tpe:duplicateLanguagesForElement
tpe:invalidArchiveFormat
tpe:invalidCatalogFile
tpe:invalidDirectoryStructure
tpe:invalidMetaDataFile
tpe:metadataDirectoryNotFound
tpe:metadataFileNotFound
tpe:missingLanguageAttribute
tpe:multipleRewriteURIsForStartString
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/PR/2015-12-09/taxonomy-package |
tpe | http://xbrl.org/PR/2015-12-09/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.
QNames in parenthetical red text after a "MUST" or "MUST NOT" statement prescribe standardised error codes to be used if the preceding condition is violated.
A Conformant Processor is a software application that takes a Taxonomy Package as input and implements all of the "MUST" and "MUST NOT" statements defined in this document for Conformant Processors.
A Conformant Processor MUST refuse to open or otherwise use a Taxonomy Package that violates any of the "MUST" and "MUST NOT" statements in this document defined for Taxonomy Packages, and MUST raise the prescribed error code for the statements that are violated.
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] (tpe:invalidArchiveFormat).
A Taxonomy Package
MUST contain a single top-level directory, with all other
files being contained within that directory or descendant subdirectories (tpe:invalidDirectoryStructure). It
is recommended, but not required, that the name of the top-level directory 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 (tpe:metadataDirectoryNotFound), which in turn MUST contain a taxonomyPackage.xml file (tpe:metadataFileNotFound). The META-INF directory MAY contain a catalog.xml file (see Section 3.3). The META-INF directory MAY also contain other files, but no syntax or semantics are prescribed for such files by this specification.
A Conformant Processor MUST treat all filenames prescribed by this specification 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) (tpe:invalidMetaDataFile).
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 description of the taxonomy. The <tp:description> element is a Multi-lingual Element.
The <tp:version> element provides a version identifier for the taxonomy as a whole.
The optional <tp:license> element provides a link to licensing terms for the taxonomy. The <tp:license> element has a @href attribute, which contains a link to the license documentation, and a @name attribute which should be used to provide a human-readable name for the license. A Conformant Processor SHOULD apply remappings when resolving the @href attribute.
This specification does not restrict the format of the license document referenced by the @href attribute.
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 Packages published by the same
entity.
The optional <tp:publisherCountry> element provides the country or region of the taxonomy publisher.
The value space of <tp:publisherCountry> is the list of alpha-2 codes defined by [ISO3166-1] as being either assignments or reservations in the standard, or made subsequently by the ISO 3166 maintenance agency or governing standardization bodies.
A Conformant Processor is not required to validate the country code beyond the schema validation required by Section 3.2.
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 description for the entry point. The <tp:description> element is a Multi-lingual Element.
The <tp:version> element provides a version identifier for the entry point.
The <tp:entryPointDocument> element defines a taxonomy schema or a linkbase 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].
After applying remappings, the <tp:entryPointDocument> will typically resolve to a document within the taxonomy package, but this is not required.
A Conformant Processor MUST refuse to open any entry point where one or more of its <tp:entryPointDocument> URLs resolve to anything other than a taxonomy schema or linkbase document.
Processors are not required to validate that the URL resolves to a taxonomy schema or a linkbase document when opening a Taxonomy Package, and it is noted that in some circumstances, the Taxonomy Package may have dependencies on other Taxonomy Packages which, if not present, will prevent this validation from succeeding. This does not invalidate the Taxonomy Package.
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.
The <tp:languages> element MAY be used to provide a list of languages available for an entry point. Each available language is indicated by inclusion of a <tp:language> element within the <tp:languages> container.
The content of the <tp:language> element is a natural
language identifier, as defined by the [XML Schema Datatypes]
language datatype. The corresponding taxonomy entry point
SHOULD provide labels in each listed language.
The <tp:languages> element MAY be
omitted entirely, in which case no inference should be made about
the languages available in the corresponding taxonomy entry point.
A Taxonomy Package MAY optionally provide a list of identifiers (see Section 3.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:supersededTaxonomyPackage/tp:taxonomyPackageRef 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:taxonomyPackageRef> 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].
A Conformant Processor
MUST refuse to open a <tp:versioningReport> URL
that does not resolve to a valid XBRL Versioning Report. After
applying remappings, the <tp:versioningReport> 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) (tpe:invalidCatalogFile).
A Conformant 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 @uriStartString attribute (tpe:multipleRewriteURIsForStartString).
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.
It follows from the above that remapped URLs should typically include some form of version identifier, to avoid conflicting with other taxonomy packages.
In the example below, a remapping has been provided for a number of individual
subdirectories. This is preferrable to providing a remapping for the whole of
http://www.example.com, as it means that the remappings will not
overlap with those for different taxonomy versions.
It should be noted that any relative URLs appearing a catalog file are resolved
relative to the location of that file. As the catalog.xml file in a Taxonomy
Package resides in the META-INF subdirectory, the relative URLs
that typically appear @rewritePrefix attributes will typically
need to start with ../ in order to get to the root of the Taxonomy
Package. An alternative approach is to use an @xml:base attribute
on the <catalog> element to alter the location relative to which
relative URLs are resolved:
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 (tpe:duplicateLanguagesForElement).
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/PR/2015-12-09/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/PR/2015-12-09/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. |
| 04 June 2015 | Paul Warren |
Updated for CR. |
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 09 December 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.