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.
It has been suggested that Oasis XML Catalogs might be used instead of the remapping feature defined here. This is an open topic for discussion in the Base Specification Working Group, and feedback on this topic from reviewers of this PWD is actively sought.
Taxonomy publishers who are currently using Catalog files and are considering adopting this Public Working Draft are encouraged to continue to provide Catalog files in addition to the .taxonomyPackage.xml meta-data file. The information provided in the two mechanisms should be consistent, specifically, the corresponding entry of a remapping element in the XML Catalog is a rewriteURI element with the following attributes:
- @uriStartString: same value as the @prefix attribute in the tp:remapping element
- @rewritePrefix: same value as the @replaceWith attribute in the tp:remapping element
1 Introduction
1.1 Relationship to other work
1.2 Namespaces
2 Taxonomy Package
2.1 Package Structure
2.2 The .taxonomyPackage.xml file
2.3 Taxonomy metadata
2.3.1 The tp:name element
2.3.2 The tp:description element
2.3.3 The tp:version element
2.4 Remappings
2.4.1 The tp:remapping element
2.4.2 Applying remappings
2.5 Entry points
2.5.1 The tp:entryPoint element
2.5.2 The tp:name element
2.5.3 The tp:description element
2.5.4 The tp:version element
2.5.5 The tp:document element
2.6 Multi-lingual elements
A References
B Schemas (normative)
B.1 taxonomy-package.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 Preferred file structure - single top level directory
2 Preferred file structure - no single top level directory
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.
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 exactly one file named .taxonomyPackage.xml. This file MAY appear within any directory within the ZIP file. It is recommended that if the ZIP file contains a single top level directory then the .taxonomyPackage.xml file SHOULD appear in that directory (see Example 2.1), otherwise the .taxonomyPackage.xml file SHOULD appear at the top level within the ZIP file (see 2.1).
It is considered good practice for ZIP files to contain a single top-level directory with a name that mirrors the ZIP file name. For example, in a ZIP file named SampleTaxonomyPackage-v1.0.zip, all content would be contained within a directory called SampleTaxonomyPackage-v1.0. Where this approach is taken, it is recommended that the .taxonomyPackage.xml appear within that top level directory, as shown below:
SampleTaxonomyPackage-v1.0/
.taxonomyPackage.xml
file1.xsd
file2.xml
directory1/
file3.xsd
file4.xml
directory2/
file5.xsd
file6.xml
Where the approach described in Example 2.1 is not taken, it is recommended that the .taxonomyPackage.xml file appears at the top level within the ZIP file, as shown below:
.taxonomyPackage.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 Schema.
A Taxonomy Package can provide metadata about the taxonomy, comprising of a name, a description and a version number. The name and description 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 <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.
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.
[Mark Goodhand:It has been suggested that Oasis XML Catalogs might be used instead of the remapping feature defined here. This is an open topic for discussion in the Base Specification Working Group, and feedback on this topic from reviewers of this PWD is actively sought.
Taxonomy publishers who are currently using Catalog files and are considering adopting this Public Working Draft are encouraged to continue to provide Catalog files in addition to the .taxonomyPackage.xml meta-data file. The information provided in the two mechanisms should be consistent, specifically, the corresponding entry of a remapping element in the XML Catalog is a rewriteURI element with the following attributes:
- @uriStartString: same value as the @prefix attribute in the tp:remapping element
- @rewritePrefix: same value as the @replaceWith attribute in the tp:remapping element
]
The <tp:remapping element> defines an individual remapping. The @prefix attribute defines a string which is matched against a URL, and the @replaceWith attribute defines a URI that replaces the prefix if it matches. Note that the @prefix is a string, and not a URI [URI]. As such, it does not need to be valid a URI, does not undergo normalization, and is not subject to XML Base [XML Base] processing.
The @replaceWith is a URI, and if relative, it MUST undergo XML Base resolution [XML Base].
A processor SHOULD apply remappings to any URL that needs to be resolved in the course of processing XBRL files. Remappings are applied to a URL as follows:
Remappings are considered in turn, in the order that they are defined in the .taxonomyPackage.xml file. If the prefix matches the URL, then the matching portion of the URL is replaced with the value of the @replaceWith attribute (after it has undergone XML Base resolution), and no further remappings are considered for that URL.
A prefix is considered to match a URL if the URL begins with the prefix string in its entirety. When performing this comparison, the URL MUST undergo Syntax-Based Normalization, Case Normalization, Percent-Encoding Normalization, Path Segment Normalization, and Scheme-Based Normalization, as defined in [URI].
Note that as the URL resulting from a remapping will typically resolve to a file within the Taxonomy Package, the URL will typically be relative. Therefore, if an @xml:base attribute is to be used to simplify URLs appearing on the <tp:entryPointDocument> element (see Section 2.5.5) then it must be placed at an appropriate level in the document, for example, on the <tp:entryPoints> element, in order to avoid affecting the relative resolution of the URIs specified by @replaceWith attributes.
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> 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].
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 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/2014-01-15/taxonomy-package.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. |
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 15 January 2014. 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.