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 spec-feedback@xbrl.org.

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:

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

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:

• an entry name component is . or ..;
• two entry names are the same; or
• the name of a file entry is the same as the name of a directory implied by another entry.

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:

• Inline XBRL report package — a report package that contains a single Inline XBRL Document Set.
• Non-Inline XBRL report package — a report package that contains a single XBRL v2.1 report or a single JSON-rooted report.
• Unconstrained report package — a report package that contains any number of reports.

The type of a report package is determined as described in Section 3.4.

3.1.1 File extensions

The following file extensions are prescribed based on the type of the report package (see Section 3.1):

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.

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:

• META-INF/reportPackage.json
• reports

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 https://xbrl.org/report-package/2023.

The report package document type URI is handled as follows:

• If the document type URI is one of the three document type URIs for this specification (see table below), the package MUST be processed according to this specification;
• Otherwise, if the document type URI is a URI prescribed by another XBRL International specification that is supported by the processor then the package MUST be processed according to that other specification, and further processing of this specification is not performed;
• Otherwise, the error rpe:unsupportedReportPackageVersion MUST be raised.

This specification defines the following document type URIs:

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.

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:

• .xbrl – an XBRL v2.1 report.
• .xhtml, .html and .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).

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:

• If it contains no files with a recognised file extension it is ignored;
• Otherwise, if the only files with a recognised file extension have .xhtml, .html or .htm file extensions, the set of such files is treated as an Inline XBRL Document Set;
• Otherwise, if there is a single file with a recognised file extension, it is treated as a report;
• Otherwise, the error rpe:multipleReportsInSubdirectory MUST be raised.

Note that:

• Nested sub-directories are permitted, but ignored for the purposes of report discovery; only direct descendants of the reports directory are considered.
• Files that do not have a recognised file extension are permitted to appear within the reports directory, and any sub-directories, but are ignored for the purpose of report discovery.

If no reports are found, rpe:missingReport MUST be raised.

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

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:

• If the reports are contained in the reports directory, then the ordering is the lexicographic ordering of the filenames;
• If the reports are in sub-directories of the reports directory, 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.

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:

• the META-INF/reportPackage.json file MUST conform to the JSON syntax constraints in Section 8; and
• the JSON Pointer /documentInfo/documentType MUST resolve to a string (rpe:invalidJSONStructure).
• If the string corresponds to a URI defined as a document type URI by a newer XBRL International specification that is supported by the processor, the package MUST be processed according to that specification;
• Otherwise, rpe:unsupportedReportPackageVersion MUST be raised.
• In either case, further processing of this specification is not performed.

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:

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

A.1.1 Notes

• This example is also a taxonomy package.
• This uses the .xbri extension, so reportPackage.json must be present.

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:

acme-x42-submission-2022/
    META-INF/
        reportPackage.json
    reports/
        myReport.json
        table1.csv
        table2.csv
        table3.csv

A.2.1 Notes

• This uses the .xbr extension, so reportPackage.json must be present.

A.3 Example: multiple reports of different types

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

acme-x42-submission-2022/
    META-INF/
        reportPackage.json
    reports/
        report-1.xhtml
        report-2.xhtml
        report-3.json 
        subdir/
            ignored.xhtml

A.3.1 Notes

• report-1.xhtml and report-2.xhtml are treated as separate reports, and not an Inline XBRL Document Set.
• ignored.xhtml is ignored, because files with recognised file extensions are present within the reports directory.
• This package contains multiple reports, so must use the .zip extension.
• reportPackage.json is optional, but recommended.
• This report package is not a taxonomy package.

A.4 Example: Inline XBRL Document Sets

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

A.4.1 Notes

• This package contains multiple reports, so must use the .zip extension.
• This package is also a taxonomy package.
• It would still be necessary to place the files within a sub-directory even if only one Inline XBRL Document Set were present within the report package, in order for the .xhtml files to be treated as a single Inline XBRL Document Set.

Appendix B Requirements

This specification addresses a subset of the requirements published in Report Package Requirements 1.0.

The following requirements have been addressed:

• 4.1 Support for multiple reports
• 4.2 Single report packages
• 4.3 Report discovery
• 4.4 Multiple taxonomies
• 4.5 Absolute URL remapping
• 4.6 Supporting resources
• 4.7 Extension taxonomy
• 4.8 iXBRL file types
• 4.9 Report ordering
• 4.12 Document set ordering
• 4.14 Distinct file formats

The following requirements have not been addressed:

• 4.10 Report signing
• 4.11 External dependencies
• 4.13 Report language documentation
• 4.15 Arbitrary report metadata

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