1 Abstract

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

2 Introduction

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

2.2 Feedback

Readers are invited to provide their feedback on this working draft to spec-feedback@xbrl.org.

2.3 Documentation conventions

2.3.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.4 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 conform to the .ZIP File Format Specification (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.

The Inline XBRL Document Set contained in an Inline XBRL report package MAY be comprised of multiple Inline XBRL Documents or define multiple target documents.

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 is referred to as the STLD. If this constraint is 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 extension is a taxonomy package or a report package by inspection. In this case a .zip file is considered to be a report package if either of the following paths exist within the STLD:

• META-INF/reportPackage.json
• reports

If the package has a file extension of .zip and 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/CR/2023-05-03.

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

3.4.2 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.4.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 an JSON-rooted report (rpe:incorrectReportType).

4.2.2 JSON-rooted reports

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

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