Report Package 1.0

Public Working Draft 9 December 2020

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

Table of Contents


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 been designed for compatibility with the previously-published Report Packages Working Group Note as well as the Taxonomy Packages specification, which defines a standard format for distributing an XBRL taxonomy as a ZIP file.

In most cases, a report packages created according to the WGN may be converted to a valid report package as defined by this specification simply by including a minimal reports.json file with the appropriate documentType definition.

The same zip file may be both a Report Package and a Taxonomy Package. In some cases, the zip will be intended primarily for carrying report data, but will include an extension taxonomy developed along with the report. In other cases, the zip will be intended primarily for publishing a taxonomy, but may include sample reports to illustrate how the taxonomy should be used.

This specification does not alter the processing of zip files loaded as taxonomy packages.

2.2 Requirements

This working draft focuses on a subset of the requirements published on 2019-12-11.

The following requirements have been addressed:

The following requirements have not been addressed:

2.3 Feedback

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

In particular, we would appreciate views on the following questions, which are the subject of ongoing discussions in the working group:

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

Report Packages makes use of QNames to represent values, such as error codes.

Prefix Namespace URI

3 Package structure

A Report Package, according to this specification, is a zip file that meets the following requirements:

A Report Package MUST conform to the .ZIP File Format Specification (rpe:invalidArchiveFormat).

The name of the top-level directory SHOULD be the same as the name of the Report Package with the file extension removed.

The top-level directory MAY contain a sub directory named reports, which is conventionally used to store XBRL reports.

The META-INF directory MAY contain a catalog.xml file, which defines remappings to be used when resolving taxonomy documents and other metadata files defined by XBRL International (see Section 6).

The Report Package MAY also contain other files and directories, some of which may be the targets of remappings defined in the catalog.xml file, but the syntax and semantics of these files and directories is not prescribed by this specification.

A Conformant Processor MUST treat all filenames prescribed by this specification as being case-sensitive.

3.1 Example file structure

The example below shows the file structure for a Report Package containing five separate reports.


Graphs, images, css files referenced by the reports may be placed with reports or with company information; other required contents may be placed in a location not designated by this specification.

4 Report discovery

Two forms of report discovery are supported. If the META-INF/reports.json file contains a reports entry, the reports in the Report package are those that are explicitly enumerated there. If the reports entry is absent, reports are discovered according to naming conventions. These conventions SHOULD be followed even if reports are explicitly enumerated in reports.json.

4.1 Explicit report index

The reports.json file takes the following form:

  "documentInfo": {
   "documentType": "${STATUS_DATE_URI}/report-package"
  "reports": [
     "reportType": "json",
     "documents": [
     "reportType": "xml",
     "documents": [
     "reportType": "ixds",
     "documents": [
     "ixTarget": "blort-primary"
     "reportType": "ixds",
     "documents": [

If any of the syntactic constraints on the JSON file outlined below are not satisfied, rpe:invalidReportsJson MUST be raised.

Each object in the reports list takes the following form:

When presenting reports and documents to the user, Report Package processors are expected to use follow the order given by the JSON lists.

4.2 Convention-driven discovery

As an alternative to the explicit report list specified above, Report Package authors may include a minimal reports.json file of the following form:

  "documentInfo": {
   "documentType": "${STATUS_DATE_URI}/report-package"

When the reports entry is omitted, as above, the reports in a Report Package are identified by scanning the contents of the reports subdirectory within the top-level directory (if there is no such directory, the Report Package defines no reports).

For each file or directory c within the reports directory:

When interpreting JSON reports, processors MAY support multiple report specifications and versions (for example, they may support pre-REC versions of xBRL-JSON and xBRL-CSV 1.0, as well as the 1.0 REC and a future 2.0). Processors MUST raise oimce:unsupportedDocumentType (or an equivalent code from a later version of OIM Common) if they encounter a document type that does not correspond to a specification that is supported by that processor, or if a document type is not present in the document.

When presenting reports and documents to the user, Report Package processors following convention-driven discovery are expected to order lexicographically by filename.

5 Remappings

A Report Package can provide remappings that allow one URL to be substituted for another during URL resolution. The typical usage for this is to allow a public, absolute URL (typically using the "http" scheme [URI]) to be resolved to a file within a Report Package. This allows processors to use copies of published taxonomies provided by a Report Package, rather than retrieving the taxonomy files from the Internet.

Remappings are specified by the inclusion of the optional catalog.xml file within the META-INF directory of a Report Package, conforming to a restricted subset of the XML Catalog specification [XML Catalogs].

If present, the catalog.xml file MUST be a valid XML Catalog file, as defined by the XML Catalog specification XML Catalogs and MUST also conform to the restricted schema defined in Appendix B.2 of the Taxonomy Package specification (rpe:invalidCatalogFile).

5.1 Applying remappings

A Conformant Processor SHOULD apply remappings to any URL that needs to be resolved in the course of processing XBRL files. Remappings are applied by following the process defined for Rewrite Entries (specifically, the rewriteURI entries allowed by the restricted schema) in the XML Catalog specification XML Catalogs.

The XML Catalog specification allows for remappings specified within a single catalog file to overlap, that is, for one prefix to be the same as the first part of another. In this case, the longest matching prefix is to be used.

A Report Package MUST NOT include a catalog file which includes more than one rewriteURI element with the same value (after performing URI Normalization, as prescribed by the XML Catalog Specification) for the @uriStartString attribute (rpe:multipleRewriteURIsForStartString). This is an additional restriction, not specified by the XML Catalog Specification, as the behaviour in this case is undefined.

Neither the XML Catalog specification nor this specification prescribe behaviour for overlapping remappings obtained from different files. Processors SHOULD signal a warning when overlapping remappings are detected.

5.2 Example remappings

In the example package structure above (Section 3.1), the catalog.xml file could include a remapping:

(note that ../ in catalog files is relative to the catalog file location, not to the referencing object location, per Oasis spec)

This will remap all URLs starting with to the corresponding location within the directory.

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, as shown in the example above, are the preferred way to reference an extension taxonomy from an XBRL or iXBRL report included within a taxonomy package, and SHOULD be used if the taxonomy package provides remappings for the taxonomy.

If the package does not provide remappings then it is acceptable to use a relative reference from the report to the taxonomy files.

6 File extensions

To assist software in identifiying report packages, the following file extensions SHOULD be used instead of the .zip extension that is conventional for zip files.

As noted in the introduction, some Taxonomy Packages include reports for illustrative purposes. These packages MAY 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.