Report Package 1.0

Proposed Recommendation 6 September 2023

This version
Mark Goodhand, CoreFiling <>
Paul Warren, XBRL International <>
David Bell, UBPartner <>
Brett Kail, Workiva <>
Jonathan Michael Rabbitt, CoreFiling <>
Harald Schmitt, ABZ Reporting <>
Herm Fischer, Mark V Systems <>

Table of Contents


Error codes

1 Abstract

This specification defines a standard container structure for XBRL reports, allowing compliant tools to identify, process and present enclosed reports automatically.

2 Introduction

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.

2.1 Base taxonomy resolution

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.

2.2 Relationship to other work

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.

2.3 Feedback

Readers are invited to provide their feedback on this working draft to

2.4 Documentation conventions

2.4.1 Error codes

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.

2.5 Namespaces and namespace prefixes

This specification makes use of QNames to represent values, such as error codes. The following prefixes are used in this specification:

Prefix Namespace URI

3 Package structure

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).

3.1 Report package types

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 single Inline XBRL Document Set contained in an Inline XBRL report package may define multiple target documents.

The unconstrained report package type exists primarily for backwards compatibility, and SHOULD NOT be used when packaging invididual reports.

3.1.1 File extensions

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 .xbri
Non-Inline XBRL report package .xbr
Unconstrained report package .zip or .ZIP

The report package file extension MUST match the report package type specified by the report package document type URI (rpe:documentTypeFileExtensionMismatch). The extensions .xbr and .xbri MUST be lowercase. The extension .zip SHOULD be lowercase, but .ZIP is permitted for backwards compatibility.

Future specifications may define additional document type URIs that may be used with these file extensions.

The rpe:documentTypeFileExtensionMismatch is only raised if:

Any other document type URI results in rpe:unsupportedReportPackageVersion as per Section 3.4.

3.2 Directory structure

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.

3.3 Identifying report and taxonomy packages

A processor MAY be configured to determine if a file with a .zip or .ZIP 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).

3.4 Report package version identification

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 (rpe:invalidJSONStructure).

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.

The reportPackage.json is optional for files with a .zip or .ZIP 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 .xbr or .xbri extensions (see Section 3.1.1). It is recommended that these extensions are used in preference to .zip if the package contains a single report.

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).

3.4.1 Illustrative reports in taxonomy packages

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.

3.5 Taxonomy Package compatibility

If a report package contains the path META-INF/taxonomyPackage.xml within 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.

3.6 The reports directory

A report package MUST contain a directory called reports as a child of the STLD (rpe:missingReportsDirectory).

4 Reports

4.1 Report types

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:

The term report, as used in this specification, can refer to an Inline XBRL Document or Document Set with multiple target documents. Each target document would constitute a separate OIM report.

4.2 Report discovery

If the 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 report discovery.

Otherwise, each sub-directory of the reports directory is treated as follows:

Note that:

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 reports directory and the META-INF/reportPackage.json must both be absent in order to avoid triggering rpe:missingReport and other report package-specific errors (see Section 3).

4.2.1 Package type constraints

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).

4.2.2 JSON-rooted reports

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.
If /documentInfo/documentType does not resolve to a string, it should be treated as if a "document type is not present".

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 .csv files 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 .json file, or a sub-directory of that directory.

4.3 Report validation

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.

5 Remappings

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 META-INF/catalog.xml is ignored.

6 Report ordering

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:

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.

7 Future specification compatibility

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:

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.

8 JSON syntax constraints

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.

Appendix A Example file structure

A.1 Example: simple, single Inline XBRL report

The example below shows the file structure for a simple report package, example1.xbri, containing a single Inline XBRL report:


A.1.1 Notes

A.2 Example: simple, single xBRL-CSV report

The example below shows the file structure for a simple report package, example2.xbr, containing a single xBRL-CSV report:


A.2.1 Notes

A.3 Example: multiple reports of different types

The example below shows the file structure for a report package,, containing three reports of different types. It also includes the optional reportPackage.json metadata file.


A.3.1 Notes

A.4 Example: Inline XBRL Document Sets

The example below shows the file structure for a report package,, containing two Inline XBRL Document Sets.


A.4.1 Notes

Appendix B Requirements

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:

Appendix C Intellectual property status (non-normative)

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 (


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 (