This specification defines a standard container structure for XBRL reports, allowing compliant tools to identify, process and present enclosed reports automatically.
The XBRL Standard encompasses a number of different report formats, including Inline XBRL, xBRL-XML, xBRL-JSON and xBRL-CSV. Reports may consist of multiple files, such as images and stylesheets supporting an Inline XBRL report, or the CSV tables in an xBRL-CSV report. In addition, XBRL reports depend on an XBRL taxonomy, which may include a report-specific "extension taxonomy". These dependencies can make XBRL reports awkward to work with, as multiple files must be exchanged, and the relative paths between them need to be preserved.
This specification defines a standard mechanism for packaging all such files into a container so that XBRL reports can conveniently exchanged, and will open reliably in different tools.
Whilst this specification provides a mechanism for reliably obtaining a report's extension taxonomy (if any), it does not attempt to improve the mechanism for resolving base taxonomy files. It is anticipated that this will be addressed a future version of this specification.
This specification is a formalisation of the previously-published Report Packages Working Group Note. Report Packages, as defined by this specification, MAY also be valid Taxonomy Packages, as defined by the Taxonomy Packages 1.0 Specification, which defines a standard format for distributing an XBRL taxonomy as a ZIP file.
This specification addresses some of the requirements published in Report Package Requirements 1.0 (see Appendix B).
It is anticipated that there will be future versions of this specification, and as such, this specification defines a mechanism for declaring the specification version that a report package is intended to conform to.
Readers are invited to provide their feedback on this working draft to firstname.lastname@example.org.
QNames in parenthetical red text after a "MUST" or "MUST NOT" statement prescribe standardised error codes to be used if the associated condition is violated.
This specification makes use of QNames to represent values, such as error codes. The following prefixes are used in this specification:
A report package is a zip file that contains one or more XBRL, Inline XBRL, xBRL-CSV, xBRL-JSON, or other OIM-based reports, and conforms to the format defined by this specification.
A report package MUST have one of the extensions listed in Section 3.1.1 (rpe:unsupportedFileExtension). This validation MUST be performed before attempting to open the report package.
A report package MUST conform to the .ZIP File Format Specification (rpe:invalidArchiveFormat or tpe:invalidArchiveFormat).
Section 4.4.17 specifies that entry names must not start with
/ and must not contain
The entry names in the ZIP file describe a tree of directories and files.
Each entry name contains a list of
/-delimited components, where the last component is the file name and other components are directory names.
Directories MAY be included explicitly as separate entries, or MAY be implied by the paths of files.
If the file name is the empty string, then the entry is a directory rather than a file, and its contents are ignored.
A processor MUST raise rpe:invalidDirectoryStructure or tpe:invalidDirectoryStructure if:
A report package MUST NOT make use of the encryption features of the .ZIP FIle Format (rpe:invalidArchiveFormat or tpe:invalidArchiveFormat).
This specification defines three types of report package:
The type of a report package is determined as described in Section 3.4.
The Inline XBRL report package and Non-Inline XBRL report package types are intended to provide users with a familiar "one document per file" user interface metaphor, and are the preferred way to package individual reports.
The following file extensions are prescribed based on the type of the report package (see Section 3.1):
|Report package type||File extension|
|Inline XBRL report package||
|Non-Inline XBRL report package||
|Unconstrained report package||
The report package file extension MUST match the report package type
specified by the report package document type URI
(rpe:documentTypeFileExtensionMismatch). The extensions
MUST be lowercase. The extension
.zip SHOULD be lowercase, but
permitted for backwards compatibility.
Future specifications may define additional document type URIs that may be used with these file extensions.
rpe:documentTypeFileExtensionMismatch is only raised if:
.xbrifile extension is used, and
reportPackage.jsonis absent; or
A report package conforming to this specification MUST contain a single top-level directory, with all other files contained within that directory or descendant sub-directories. This directory MUST NOT be called
META-INF. This directory is referred to as the STLD. If these constraints are not met, a processor MUST check if the package can be identified as a future report package, and handled as described in Section 7. Otherwise a processor MUST raise rpe:invalidDirectoryStructure or tpe:invalidDirectoryStructure.
A processor MAY be configured to determine if a file with a
extension is a taxonomy package or a report package by inspection.
In this case the file is considered to be a report package if either
of the following paths exist within the STLD:
If neither path exists, the file is treated as a taxonomy package, and further constraints and processing defined by this specification are not applied.
Otherwise, the file is treated as a report package, and is processed according to this specification, or a newer specification for report packages (see Section 3.4).
A report package SHOULD include a file called
reportPackage.json in the META-INF
directory. If present, the file MUST conform to the JSON syntax constraints in Section 8,
and the JSON Pointer
/documentInfo/documentType MUST resolve to a string
A document type URI is a URI that uniquely identifies the type and version of a document that conforms to an XBRL International specification.
The document type URI for a report package is the value of the
/documentInfo/documentType property, or, if
reportPackage.json is absent, the value
The report package document type URI is handled as follows:
This specification defines the following document type URIs:
|URI||Report package type|
||Inline XBRL report package|
||non-Inline XBRL report package|
||Unconstrained report package|
The document type URI specifies the type of the package (see Section 3.1). If
reportPackage.json is absent, then the report package is an unconstrained report package.
reportPackage.json is optional for files with a
extension in order to maintain compatibility with the existing Working Group Note,
but it is recommended that all new report packages include this file.
The package version identification file is mandatory for files using the
.xbri extensions (see Section 3.1.1). It is recommended that
these extensions are used in preference to
.zip if the package contains a
Future versions of this specification will define new functionality, and may relax or alter constraints prescribed by this specification.
It is expected that any future versions of this specification will make this
identifier mandatory, enabling processors to positively identify the version of
the specification that a package conforms to. This is intended to allow
processors to give a clear error message to users if they encounter a report
using a newer, unsupported report package format. It is also anticipated that
future versions of this specification will modify the expected location of the
META-INF directory (see Section 7).
Some taxonomy packages include reports for illustrative purposes. These packages SHOULD use the conventional
.zip extension, as expected by the Taxonomy Package specification, and will still be considered report packages provided they meet the definition of a report package.
If a report package contains the path
the STLD then it MUST be a valid taxonomy package.
The Taxonomy Package specification implies, but does not require, that the
package will have a file extension of
.zip. This specification permits a number
of alternative extensions, as described in Section 3.1.1.
References to the ".zip file extension" in the Taxonomy Package specification
should be read as any extension permitted by this specification.
A report package MUST contain a directory called
reports as a child of the STLD (rpe:missingReportsDirectory).
A report is a file, or in the case of an Inline XBRL Document Set, a set of files, with a recognised file extension.
The recognised file extensions are:
.xbrl– an XBRL v2.1 report.
.htm– an Inline XBRL v1.1 report (or part of an Inline XBRL Document Set).
.json– a JSON-rooted report (see Section 4.2.2).
reports directory contains any file with a recognised file extension,
then each such file is treated as a separate report, and any
sub-directories of the
reports directory are ignored for the purpose of
Otherwise, each sub-directory of the
reports directory is treated as follows:
.htmfile extensions, the set of such files is treated as an Inline XBRL Document Set;
reportsdirectory are considered.
reportsdirectory, and any sub-directories, but are ignored for the purpose of report discovery.
If no reports are found, rpe:missingReport MUST be raised.
A consequence of the above discovery rules is that an Inline XBRL Document Set
with more than one document must always be placed in a sub-directory of the
reports directory, even if there are no other reports in the package.
If a package uses a
.zip extension, and is intended to be a "pure"
taxonomy package (i.e. not a report package) then the
directory and the
META-INF/reportPackage.json must both be absent in order to avoid
rpe:missingReport and other report package-specific errors (see Section 3).
If the report package is an Inline XBRL report package or a non-Inline XBRL report package then there MUST NOT be more than one report in the report package (rpe:multipleReports).
If the report package is an Inline XBRL report package then the contained report MUST be an Inline XBRL Document Set (rpe:incorrectReportType).
If the report package is a non-Inline XBRL report package then the contained report MUST be either an XBRL v2.1 report or a JSON-rooted report (rpe:incorrectReportType).
A JSON-rooted report is a report with a
.json extension. JSON-rooted report
formats are typically built on the Open Information Model, and follow a
consistent approach of using a document type URI contained within a JSON
file to identify the format type. Examples of JSON-rooted reports include
xBRL-JSON and xBRL-CSV. The JSON file MAY reference other files that together
make up the report.
Reports with a
.json extension MUST conform to the JSON syntax constraints in Section 8.
The JSON Pointer
/documentInfo/documentType MUST resolve to a string, which
is treated as described in Open Information Model Common Definitions Section 2.
/documentInfo/documentType does not
resolve to a string, it should be treated as if a "document type is not
Processors of this specification MUST apply the above validation, but are not required to support any JSON-rooted report formats (see Section 4.3).
In the case of xBRL-CSV reports, the
.json file will reference
which will typically be within the same report package. As
.csv is not a recognised file extension
there are no constraints on where these files are placed within the package,
but it is recommended that they are placed in the same directory as the
file, or a sub-directory of that directory.
Processors of this specification are not required to validate reports within the package. Such validation is only required at the point that software attempts to open a report within the package, and is prescribed by the relevant specification for the report format.
Processors are not required to support all report formats. Where a processor does not support Inline XBRL v1.1 or XBRL v2.1, and attempts to open such a report from within a report package, the code rpe:unsupportedReportFormat SHOULD be used. Where a processor does not support a JSON-rooted report format, it MUST be handled as per Open Information Model Common Definitions Section 2.
A report package MAY contain remappings, as defined in the Taxonomy Package specification.
Remappings apply only to the resolution of taxonomy documents and other metadata files defined by XBRL International (such as xBRL-CSV metadata files). Images, styles and scripts referenced by any HTML documents within a report package are not subject to remappings.
Absolute URLs, resolved via remappings are the preferred way to reference an extension taxonomy from a report, even if the taxonomy is contained within the same report package.
Remappings are only applied if the report package is also a taxonomy package.
If there is no
META-INF/taxonomyPackage.xml file then
If a report package contains multiple reports, and an ordering of those reports is required for presentation to an end user, then the ordering is as follows:
reportsdirectory, then the ordering is the lexicographic ordering of the filenames;
reportsdirectory, then the ordering is the lexicographic ordering of the sub-directory names.
In the case of an Inline XBRL Document Set, the order of the documents within the set is the lexicographic ordering of the filenames.
Lexicographic ordering means ordering based on comparison of Unicode code point values of each character.
If the path
META-INF/reportPackage.json exists at the root of the package then it should be treated as a future report package and:
META-INF/reportPackage.jsonfile MUST conform to the JSON syntax constraints in Section 8; and
/documentInfo/documentTypeMUST resolve to a string (rpe:invalidJSONStructure).
It is anticipated that future specifications may remove the requirement of a single top-level directory (see Section 3.2), and place the
META-INF directory at the root of the package. This arrangement is not supported by this specification, but processors are required to check for a root-level
META-INF/reportPackage.json in order to provide a more meaningful error message to end users when trying to open a package conforming to a later, unsupported specification version.
JSON files defined by this specification MUST be valid JSON, per RFC 8259 (rpe:invalidJSON).
In order to avoid interoperability issues, objects within JSON documents defined by this specification MUST have unique keys (rpe:invalidJSON).
Such JSON documents MUST use the UTF-8 character encoding (rpe:invalidJSON), and MAY include a Unicode Byte Order Mark, although this is neither required nor recommended.
Processors MAY use an equivalent code prescribed by another applicable XBRL
International Specification in place of
rpe:invalidJSON, such as the
invalidJSON code prescribed by xBRL-CSV or xBRL-JSON.
The example below shows the file structure for a simple report package,
example1.xbri, containing a single Inline XBRL report:
acme-x42-submission-2022/ META-INF/ reportPackage.json taxonomyPackage.xml catalog.xml xbrl.example.com/ v1/ taxonomy.xsd taxonomy-linkbase.xml reports/ report-1.html report-1-graph.svg css/ report-1.css
reportPackage.jsonmust be present.
The example below shows the file structure for a simple report package,
example2.xbr, containing a single xBRL-CSV report:
acme-x42-submission-2022/ META-INF/ reportPackage.json reports/ myReport.json table1.csv table2.csv table3.csv
reportPackage.jsonmust be present.
The example below shows the file structure for a report package,
three reports of different types. It also includes the optional
acme-x42-submission-2022/ META-INF/ reportPackage.json reports/ report-1.xhtml report-2.xhtml report-3.json subdir/ ignored.xhtml
report-2.xhtmlare treated as separate reports, and not an Inline XBRL Document Set.
ignored.xhtmlis ignored, because files with
recognised file extensionsare present within the
reportPackage.jsonis optional, but recommended.
The example below shows the file structure for a report package,
example4.zip, containing two Inline XBRL Document Sets.
acme-x42-submission-2022/ META-INF/ taxonomyPackage.xml catalog.xml xbrl.example.com/ v1/ taxonomy.xsd taxonomy-linkbase.xml reports/ docset1/ report-1-1.xhtml report-1-2.xhtml docset2/ report-2-1.xhtml report-2-2.xhtml
.xhtmlfiles to be treated as a single Inline XBRL Document Set.
This specification addresses a subset of the requirements published in Report Package Requirements 1.0.
The following requirements have been addressed:
The following requirements have not been addressed:
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 (https://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 (https://www.xbrl.org/legal).