This specification defines a standard structure for XBRL reports within zip files, allowing compliant tools to identify, process and present enclosed reports automatically.
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.
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:
Readers are invited to provide their feedback on this working draft to spec-feedback@xbrl.org.
In particular, we would appreciate views on the following questions, which are the subject of ongoing discussions in the working group:
.pxr and .pxrs file extensions suitable? 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.
Report Packages makes use of QNames to represent values, such as error codes.
| Prefix | Namespace URI |
|---|---|
| rpe | http://www.xbrl.org/PWD/2020-12-09/report-package/error |
META-INF directoryMETA-INF directory contains a file named reports.jsonreports.json is a valid JSON document in which the JSON Pointer /documentInfo/documentType resolves to a string with the value http://xbrl.org/PWD/2020-12-09/report-packageA 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.
The example below shows the file structure for a Report Package containing five separate reports.
acme-x42-submission-2020/
META-INF/
reports.json
taxonomyPackage.xml
catalog.xml
acme-legal.md
xbrl.example.com/
v1/
taxonomy.xsd
taxonomy-linkbase.xml
reports/
report-1.html
report-1-graph.svg
report-2.json
report-3/
doc-3-1.xhtml
doc-3-2.xhtml
fig-1.png
report-4/
doc-4a.xhtml
doc-4b.xhtml
report-5/
xcsv-metadata.json
parameters.csv
table-1.csv
table-2.csv
css/
company-fancy-style.css
images/
company-logo.png
attachments/
non-xbrl-report.pdf
disclaimer.pdf
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.
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.
The reports.json file takes the following form:
{
"documentInfo": {
"documentType": "http://xbrl.org/${STATUS_DATE_URI}/report-package"
},
"reports": [
{
"reportType": "json",
"documents": [
"../reports/foo.json"
]
},
{
"reportType": "xml",
"documents": [
"../reports/bar.xbrl"
]
},
{
"reportType": "ixds",
"documents": [
"../reports/blort/blort.html"
],
"ixTarget": "blort-primary"
},
{
"reportType": "ixds",
"documents": [
"../reports/bling/bling.html",
"../reports/bling/bling-notes.html"
]
}
]
}
If any of the syntactic constraints on the JSON file outlined below are not satisfied, rpe:invalidReportsJson MUST be raised.
reports MAY be present at top level; if present, it MUST contain a list of JSON objects.Each object in the reports list takes the following form:
documents MUST be present and MUST contain a non-empty list of strings containing relative URIs, to be resolved against the location of the reports.json file.reportType MUST be present and MUST have one of the following strings as its value: xml, json, ixds
reportType is json or xml, ixTarget MUST NOT be specified, and there MUST be exactly one entry in the documents list.reportType has the value ixds, ixTarget MAY be specified (if it is absent, the report is loaded from the default target document in the IXDS), and multiple documents MAY be specified in the documents list.In each of the JSON objects mentioned above, only the keys specified above are allowed. Processors MUST raise an error if additional keys are present.
When presenting reports and documents to the user, Report Package processors are expected to use follow the order given by the JSON lists.
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": "http://xbrl.org/${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:
If c is a file with the extension .xml or .xbrl, the file is interpreted as an xBRL-XML report.
If c is a file with the extension .html, .xhtml or .htm, the file is interpreted as an Inline XBRL report corresponding to the default target document.
If c is a file with the extension .json, the file MUST be a valid JSON document in which the JSON Pointer /documentInfo/documentType resolves to a string.
If c is a directory, the entire contents of the directory correspond to a single report.
.json file, the report is processed according to its documentType, as above..html, .xhtml or .htm files, these files are considered together as an Inline XBRL Document Set, and are interpreted as an Inline XBRL report corresponding to the default target document.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.
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).
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.
In the example package structure above (Section 3.1), the catalog.xml file could include a remapping:
https://xbrl.example.com/v1/../xbrl.example.com/v1/(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
https://xbrl.example.com/v1/ to the corresponding location within
the xbrl.example.com/v1/ 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.
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.
.pxr to signify a package containing a single report.pxrs to signify a package containing one or more reportsAs 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.