Report Package 1.0

Candidate Recommendation 3 May 2023

This version
https://www.xbrl.org/Specification/report-package/CR-2023-05-03/report-package-CR-2023-05-03.html
Editors
Mark Goodhand, CoreFiling <mrg@corefiling.com>
Paul Warren, XBRL International <pdw@xbrl.org>
Contributors
David Bell, UBPartner <dbell@ubpartner.fr>
Brett Kail, Workiva <brett.kail@workiva.com>
Jonathan Michael Rabbitt, CoreFiling <jmr@corefiling.com>
Harald Schmitt, ABZ Reporting <harald.schmitt@abz-reporting.com>
Herm Fischer, Mark V Systems <herm@markv.com>

Table of Contents

Definitions

Error codes

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:

Prefix Namespace URI
rpe https://xbrl.org/CR/2023-05-03/report-package/error
tpe http://xbrl.org/2016/taxonomy-package/errors

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:

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.

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 unconstrained report package type exists primarily for backwards compatibility, and SHOULD NOT be used when packaging invididual reports.

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:

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:

This specification defines the following document type URIs:

URI Report package type
https://xbrl.org/report-package/CR/2023-05-03/xbri Inline XBRL report package
https://xbrl.org/report-package/CR/2023-05-03/xbr non-Inline XBRL report package
https://xbrl.org/report-package/CR/2023-05-03 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 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.4.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 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

The report package file extension MUST match the report package type specified by the report package document type URI (rpe:documentTypeFileExtensionMismatch).

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

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

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.

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:

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

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

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

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

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