Table of Contents

1 Introduction

XBRL Report Packages are a standard way of combining the different files that make up an XBRL or Inline XBRL Report into a single file. This makes XBRL and Inline XBRL Reports easier to use, as the file can be opened directly in software that supports the format, and it provides a single file for submission to report collectors.

The Report Package specification defines the following two types of file:

• Inline XBRL report packages, with the file extension .xbri
• Non-Inline XBRL report packages, with the file extension .xbr

This document answers frequently asked questions (FAQs) about the standard way of building multiple components of a Report Package. The target audience for this document is software developers. For a high-level overview of Report Packages from a user perspective, please see the separate Understanding Report Packages guidance.

2 Report Package file structure

Report packages are ZIP files, although as noted above, they typically do not use the .zip file extension. In order to understand the technical FAQs in this document, it is necessary to understand the file structure within the ZIP file.

Top folder: Report Packages must contain a single, top-level folder. It is recommended that the folder name matches the report package filename. No other folders or files may appear at the top-level of the package.

• META-INF: A subfolder within the top folder. It contains metadata and configuration files for identifying XBRL report and taxonomy files. The META-INF folder may contain the following files:

  • reportPackage.json: this file contains a URI to identify the type of Report Package, and the version of the Report Package specification that it conforms to. See Q14 for more detail on possible values.

  • taxonomyPackage.xml: this file includes metadata about the taxonomy, such as its name, publication date, and version. This file is required when a taxonomy is packaged along with the XBRL report.

  • catalog.xml: Contains information for remapping URLs to files within the package. This allows a report to reference an extension taxonomy using a public URL, which is then automatically remapped to the taxonomy files within the package. This file is optional, and is only used when remapping is to be provided a taxonomy is packaged along with the XBRL report.

  Read more about taxonomy packages in this separate guidance document.

• reports: This is a subfolder where the XBRL reports are stored. This folder may contain subfolders depending on the organisation of the XBRL report.

• taxonomy (optional): This is an optional subfolder that contains taxonomy files when a taxonomy is packaged along with the XBRL report. Unlike the reports folder, the name of which is prescribed by the specification, there is no prescribed name for this folder. See Q12 for more details on how to name and organise this folders.

Here is the sample report package file structure. This example uses a folder structure that mirrors the taxonomy’s official URL structure.

Sample-report-package/
    META-INF/
        reportPackage.json
        taxonomyPackage.xml
        catalog.xml
    reports/
        annualReport.xhtml
    www.sample.com/
        taxonomy/
            2024/
                entry-point.xsd
                label.xml
                pre.xml
                cal.xml
                def.xml

3 Technical FAQs

This section provides answers to commonly asked technical questions about report packages. Whenever relevant, a sample report package structure is also provided.

Q1 What file extension should be used for a report package?

The recommended file extension for Inline XBRL report packages is .xbri, while for non-Inline XBRL report packages, it is .xbr.

Q2 Where should a single iXBRL report be placed in a Report Package?

A single document iXBRL report, which may have the extension .xhtml, .html, or .htm file, should be placed in the reports folder. While placing it in a subfolder within the reports folder is possible, this is not the recommended approach.

Sample-iXBRL-document/
    META-INF/
        reportPackage.json
    reports/
        annualReport.xhtml

Q3 How should an iXBRL document set be included in a Report Package?

An iXBRL document set consisting of multiple .xhtml , .html or .htm files should be placed in a subfolder of the 'reports' in a Report Package. Placing the files in a subfolder groups them together signals that they should be processed as a single iXBRL Document Set.

Sample-iXBRL-document-set/
    META-INF/
        reportPackage.json
    reports/
        sample-ixds/
            financialReport.xhtml
            auditReport.xhtml

Q4 Where should supporting resources like image and CSS files be placed in an Inline XBRL report in a Report Package?

Supporting resources, such as images, fonts, and CSS files, used in Inline XBRL Reports should be placed in the same folder as the Inline XBRL report or within a subfolder of that folder. It is recommended to use separate image files rather than embedding images directly within the XHTML.

Sample-iXBRL-report-with-supporting-resources/
    META-INF/
        reportPackage.json
    reports/
        annualReport.xhtml
        logo.png
        style.css

Q5 Where should a single XBRL report be placed in a Report Package?

A single XBRL report, whether it's in the .xbrl file for xBRL-XML report, .json file for xBRL-JSON or .json file (JSON metadata) for xBRL-CSV report, should ideally be placed in the reports folder. While it's technically possible to place it within a subfolder of the reports folder, this is not the preferred method.

Sample-xBRL-XML-report/
    META-INF/
        reportPackage.json
    reports/
        annualReport.xbrl

Sample-xBRL-JSON-report /
    META-INF/
        reportPackage.json
    reports/
        annualReport.json

Sample-xBRL-CSV-report /
    META-INF/
        reportPackage.json
    reports/
        metadata.json
        data.csv

Q6 Where should the CSV data files of an xBRL-CSV report be placed in a Report Package?

xBRL-CSV reports are identified by a JSON metadata file from which all CSV data can be discovered. The .csv data files should be in the same folder as the JSON metadata file or a subfolder of that folder.

Sample-xBRL-CSV-report /
    META-INF/
        reportPackage.json
    reports/
        metadata.json
        data.csv

Q7 How should an xBRL-CSV file with multiple JSON metadata files be included in a Report Package?

xBRL-CSV allows metadata to be split into multiple JSON files. It is important that multiple metadata JSON files are not placed in the reports folder, as they will be treated as separate reports. Instead, only the primary metadata file should be placed in the reports folder, and all other files should be placed within a subfolder.

Sample-xBRL-CSV-report-multiple-metadata /
    META-INF/
        reportPackage.json
    reports/
        primary-metadata.json
        files/
            metadata1.json
            metadata2.json
            data1.csv
            data2.csv

Q8 How do you combine multiple XBRL reports to create a Report Package?

Inline XBRL Report Packages (.xbri) support a single Inline XBRL Document or Document Set. Non-Inline XBRL Report Packages (.xbr) support a single XBRL Report.

If there is a requirement to combine multiple reports for submission or distribution, the preferred approach is to prepare each report as a separate Report Package, of the appropriate type and combine them using a separate mechanism, such as a ZIP file.

Q9 Is it permissible to use the .zip format for a Report Package?

The .zip file extension for report packages is primarily for maintaining backwards compatibility with the 2018 Working Group Note. It is not recommended for new XBRL programmes adopting Report Packages. However, if the .zip RP file extension is used, it is recommended to specify the documentType value as https://xbrl.org/report-package/2023 in the reportPackage.json file. However, it is not mandatory for report packages with .zip file extensions to include a reportPackage.json file.

Q10 What user experience should a user expect when opening a Report Package?

Software is expected to automatically recognise XBRL Report Packages with .xbr and .xbri extensions and automatically open the contained report. Users should only encounter a prompt to select a target document if necessary. When opening a Report Package with a .xbr or .xbri extension, users should not ordinarily be given the option to treat it as a Taxonomy Package or open any contained taxonomy entry points Additionally, it's recommended to configure file associations for .xbr and .xbri file types in the relevant application.

Q11 How should the taxonomy folder should be arranged?

The taxonomy folder becomes necessary when a Report Package includes an extension taxonomy. It is common practice to reference extension taxonomies via a public URL based on the reporting entity’s website, and to remap this URL to a file within the report package. Where this is done, it is common to name the folder after the hostname in the URL, and to mirror the URL in the folder structure. Remappings for the taxonomy files can be defined in the catalog.xml file in the META-INF folder.

For example, the extension taxonomy could use a nominal, public URL of 'https://www.sample.com/taxonomy/2024/entry-point.xsd'

In this case, the folder structure would be as follows:

Sample-iXBRL-document/
    META-INF/
        reportPackage.json
        taxonomyPackage.xml
        catalog.xml
    reports/
        annualReport.xhtml
    www.sample.com/
        taxonomy/
            2024/
                entry-point.xsd
                label.xml
                pre.xml
                cal.xml
                def.xml

The catalog.xml file would contain an entry remapping https://www.sample.com/taxonomy/2024/entry-point.xsd to ../www.sample.com/taxonomy/2024/entry-point.xsd

Q12 Is it necessary to include the reportPackage.json file in a report package?

For report packages using the .xbr or .xbri file extension, the reportPackage.json file is mandatory. For report packages using the .zip extension, the file is optional, but this is for backwards compatibility reasons; it is recommend that it is included in all report packages.

Q13 Which document type URI should be used for different report packages in the reportPackage.json file?

For an Inline XBRL Report Package with a .xbri extension, use the URI: https://xbrl.org/report-package/2023/xbri.

For a Non-Inline XBRL Report Package with a .xbr extension, use the URI: https://xbrl.org/report-package/2023/xbr.

For a Legacy Report Package with a .zip extension, use the URI: https://xbrl.org/report-package/2023 ¹.

Q14 When should report packages be used?

Report Packages are most useful for XBRL and Inline XBRL Reports that consist of multiple files, such as those with extension taxonomies or external images, stylesheets and other resources, but for consistency and ease of use it is recommended that all XBRL reports are distributed as Report Packages using the extensions above.

Filing rules will typically specify the exact format to be used, and preparers should ensure that they comply with such rules. Where reports are published on a website, it may be useful to also make them available in unpackaged form, provided that all dependencies are also available. Examples of this include publishing an Inline XBRL report for end user consumption, or publishing xBRL-JSON reports as part of an API.

4 Terminology

Report Packages seek to make XBRL reports easier to deal with, by assembling all the files that make up a report into a single file with a recognisable file extension that indicates that is an Inline XBRL or XBRL report. As such, the preferred term to refer to a "Report Package" is "Report" (or "XBRL Report" or "Inline XBRL Report"). Users should not need to know any of the details of what is contained within the "package", or even that it is a "package" at all, and software developers are encouraged to avoid the term "Report Package" in end-user software.