xBRL-JSON: JSON representation of XBRL data 1.0

Recommendation 13 October 2021 with errata corrections to 19 April 2023

Copyright © 2022, XBRL International Inc., All Rights Reserved.

This version:
<http://www.xbrl.org/Specification/xbrl-json/REC-2021-10-13+errata-2023-04-19/xbrl-json-REC-2021-10-13+corrected-errata-2023-04-19.html>
Editors:
Paul Warren, XBRL International Inc. <pdw@xbrl.org>
Herm Fischer, Mark V Systems Limited <fischer@markv.com>
Mark Goodhand, CoreFiling <mrg@corefiling.com>
Contributors:
Daniel Dracott, CoreFiling <djd@corefiling.com>
Eleanor Joslin, CoreFiling <ejj@corefiling.com>
Harald Schmitt, ABZ Reporting <harald.schmitt@abz-reporting.com>

Status

Circulation of this Recommendation is unrestricted. This document is normative. Recipients are invited to submit comments to oim@xbrl.org, and to submit notification of any relevant patent rights of which they are aware and provide supporting documentation.

Abstract

This document defines xBRL-JSON, a standardised JSON-based representation of data in an XBRL Report. The format is defined in the form of mappings from the XBRL Open Information Model, a syntax-independent definition of the data represented by an XBRL v2.1 instance document.

Table of Contents

1 Introduction
1.1 Terminology
1.2 Documentation conventions
1.2.1 Error codes
1.3 Namespaces and prefixes
1.4 URIs and URI aliases
2 Validation
2.1 JSON representation constraints
2.2 Document type identification
2.3 JSON structure and mapping
3 Identifiers in xBRL-JSON
4 Extensibility
5 XBRL Report Model
5.1 Facts
5.2 Dimensions
5.3 Links
6 Features
6.1 Standard features
6.1.1 The Canonical Values feature
6.1.2 Allowed Duplicates feature

Appendices

A References
B Intellectual property status (non-normative)
C Document History (non-normative)
D Errata Corrections incorporated in this document

Tables

1 Namespaces and namespace prefixes
2 URIs and URI aliases

Examples

1 JSON example: fact
2 JSON example: period dimension (duration)
3 JSON example: period dimension (instant)
4 JSON example: unit dimension (US dollars per share)
5 JSON example: language dimension
6 JSON example: taxonomy-defined dimensions
7 JSON example: a text footnote
8 JSON example: a fact footnote

Definitions

canonical representation
Dimensions (JSON Object)
Document info (JSON Object)
Fact (JSON Object)
Facts (JSON Object)
Feature
Features (JSON Object)
Link group (JSON Object)
Link groups (JSON object)
Link types (JSON object)
Links (JSON Object)
Namespaces (JSON object)
Report (JSON Object)
URI map (JSON Object)
xBRL-JSON document type

Error codes

xbrlje:invalidDimensionValue 2 3
xbrlje:invalidFactValue
xbrlje:invalidJSON 2 3
xbrlje:invalidJSONStructure 2 3 4 5 6 7
xbrlje:invalidLanguageCodeCase
xbrlje:nonCanonicalValue
xbrlje:unknownLinkGroup
xbrlje:unknownLinkTarget
xbrlje:unknownLinkType

oime:disallowedDuplicateFacts
oime:invalidDimensionValue


1 Introduction

1.1 Terminology

The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL, in this specification, are to be interpreted as described in [IETF RFC 2119].

The keywords expanded name, NCName and QName are to be interpreted as described in the XML Names specification [XML Names].

The keywords SQName, prefix, prefix map and unit string representation are to be interpreted as described in the OIM Common Definitions specification [OIMCOMMON].

The keywords canonical lexical representation are to be interpreted as described in the XML Schema Part 2 specification [XML Schema Datatypes].

The keywords member and object are to be interpreted as described in the JavaScript Object Notation specification [JSON].

1.2 Documentation conventions

1.2.1 Error codes

QNames in parenthetical red text after a "MUST" or "MUST NOT" statement prescribe standardised error codes to be used if the preceding condition is violated. "MUST" or "MUST NOT" statements that do not have a prescribed error code are not automatically enforceable, and processors are not required to detect violations.

1.3 Namespaces and prefixes

This specification makes use of QName notation to refer to XML expanded names (the combination of a namespace URI and a localname, and the xBRL-JSON format make use of abbreviated forms for these identifiers. The prefixes used by this specification are shown in the table below.

Table 1: Namespaces and namespace prefixes
Prefix Namespace URI
xbrl https://xbrl.org/2021
xbrli http://www.xbrl.org/2003/instance
xs http://www.w3.org/2001/XMLSchema
xbrljehttps://xbrl.org/2021/xbrl-json/error
oimce https://xbrl.org/2021/oim-common/error

1.4 URIs and URI aliases

The xBRL-JSON format make use of URI aliases as an abbreviated representation of URIs, as described in [OIMCOMMON]. The table below defines reserved URI aliases for the link types and link groups URI maps.

Table 2: URIs and URI aliases
URI alias URI
footnote http://www.xbrl.org/2003/arcrole/fact-footnote
explanatoryFact http://www.xbrl.org/2009/arcrole/fact-explanatoryFact
_ http://www.xbrl.org/2003/role/link

2 Validation

On encountering a document with the xBRL-JSON document type, an xBRL-JSON processor MUST raise errors with the specified error codes if the document does not conform to the constraints defined in this specification. Additionally, such a processor MUST perform the validation required of a conformant processor, as defined in the Open Information Model [OIM]. A processor MAY apply the validation required of a validating conformant processor.

2.1 JSON representation constraints

xBRL-JSON documents MUST be valid JSON, per RFC 8259 [JSON] (xbrlje:invalidJSON).

RFC 8259 [JSON] does not prohibit a JSON object from having multiple occurrences of the same key, but states that behaviour of such objects is unpredictable. In order to avoid interoperability issues, objects within JSON documents conforming to this specification MUST have unique keys (xbrlje:invalidJSON).

xBRL-JSON reports MUST use the UTF-8 character encoding (xbrlje:invalidJSON), and MAY include a Unicode Byte Order Mark, although this is neither required nor recommended.

2.2 Document type identification

A document has the xBRL-JSON document type if it is a valid JSON document in which the JSON Pointer [JSONPOINTER] /documentInfo/documentType resolves to the string https://xbrl.org/2021/xbrl-json. A document that does not have the xBRL-JSON document type should be treated as described in OIM Common and the errors defined in this specification MUST NOT be raised, aside from xbrlje:invalidJSON ( Section 2.1) which is tested before the document type is assessed.

2.3 JSON structure and mapping

This document is intended to define a bi-directional mapping between the Open Information Model and an xBRL-JSON document. The transformation from xBRL-JSON back to the model not explicitly described, but may be inferred from the model to JSON mappings, taken in conjunction with the constraints defined in the Open Information Model, and those defined in the XBRL v2.1 [XBRL 2.1] and XBRL Dimensions v1.0 [DIMENSIONS] specifications applied to the xBRL-XML representation of that model.

The mapping is defined as a series of tables describing JSON objects that represent components in the XBRL Open Information Model [OIM].

Tables define the members of JSON objects. The table lists the name of each member, the JSON value type, and a description of how the value is obtained from the model. Where a key is denoted as "(required)" it MUST be present in each occurrence of the object (xbrlje:invalidJSONStructure).

This specification documents the allowed types for JSON properties. Types are specified as a combination of JSON primitive types (string, array, object, number, boolean and null) and an optional XML Schema built-in simple type [XML Schema Datatypes], identified by a QName. Values within JSON documents MUST have the JSON type specified and, where an XML Schema type is specified, MUST be in the canonical lexical representation for that type (xbrlje:invalidJSONStructure). Note that values for facts and taxonomy-defined dimensions are not required to be in canonical form.

References to components defined by the Open Information Model [OIM] are denoted by curly braces, e.g. {facts}.

3 Identifiers in xBRL-JSON

xBRL-JSON makes use of QNames to represent expanded names and SQNames to represent some other values. The prefix map for resolving QNames, SQNames and other prefixed content is provided by the namespaces object. Any prefixes used in QNames or SQNames are resolved as described in [OIMCOMMON].

4 Extensibility

In order to facilitate the inclusion of additional information within an xBRL-JSON report, additional properties beyond those defined in this specification MAY be included within the following objects:

Additional properties MUST NOT be included in any other objects defined by this specification (xbrlje:invalidJSONStructure).

Any such additional properties included in the above objects MUST have names that are QName values (xbrlje:invalidJSONStructure), and unless defined in a specification published by XBRL International MUST have a prefix that identifies a namespace that does not use the xbrl.org domain name.

The content of any such additional properties is not constrained by this specification.

5 XBRL Report Model

The section describes how each component defined in the Open Information Model is mapped to a corresponding JSON representation.

An xBRL-JSON document consists of a report object, as defined below.

JSON Object: Report
This object represents an OIM report component.
Members:
facts (object)
(optional) A facts object.
documentInfo (object)
(required) A document info object.
JSON Object: Document info

The document info object contains metadata information necessary to correctly process the rest of the document.

Members:
documentType (string)
(required) This property MUST be present with the value "https://xbrl.org/2021/xbrl-json", and identifies the document as being a report covered by this specification. See Section 2.2.
features (object)
(optional) A features object.
namespaces (object)
(optional) A URI map object defining the prefix map for QNames, SQNames and prefixed content in this report (see Section 3).
linkTypes (object)
(optional) A URI map object defining URI aliases used to identify link types in this report.
linkGroups (object)
(optional) A URI map object defining URI aliases used to identify link groups in this report.
taxonomy (array)

(required) An array of URLs (xs:anyURI) corresponding to the members of the {taxonomy} property for the {report}.

Processors SHOULD use remappings provided by XBRL Taxonomy Packages [Taxonomy Package] when resolving taxonomy URLs.

baseURL (string)
(optional) If present, this property is an xs:anyURI providing the value of the {base-url} property for the {report}, if any. Inclusion of this property is optional, even where the {base-url} property is present in the model. When creating an OIM report from an xBRL-JSON document, the {base-url} property is the value of this property, if present. Otherwise, the {base-url} property MAY optionally be set to the absolute URL from which the document was loaded.

Note that the baseURL property has no effect on the resolution of URLs in the taxonomy property.

JSON Object: Features

The features object is used to indicate that the document conforms to additional constraints, beyond those required for xBRL-JSON itself. For example, it can be used to indicate that all values are represented in their canonical form. See Section 6 for more information, including the standard features defined by this specification.

Members:
name
An xs:QName corresponding to the name of the feature.
value (any (non-null))
Any non-null JSON value, indicating the state of the feature. A value of false is equivalent to omitting the property, and indicates that the feature is disabled. Any other value indicates that the feature is enabled. Values other than true may be used to indicate specific additional properties of the feature.
JSON Object: URI map

A JSON object providing a map of URI aliases to full URIs. The URI map MUST conform to the constraints defined in [OIMCOMMON] for URI maps.

Members:
name
The URI alias (xs:NCName) to be defined.
value (string)
The URI (xs:anyURI) to be associated with the URI alias [URI].

5.1 Facts

JSON Object: Facts

The {facts} property of a {report} is represented by an object containing members of the following form:

Members:
name
The value (xs:NCName) of the {id} property of the fact.
value (object)
A fact object.
JSON Object: Fact

A fact component is represented by an object with the following members.

Members:
value (string or null)

(required) The value of the {value} property of the fact. The value MUST be represented as (xbrlje:invalidFactValue):

If the value is prefixed content, any prefixes used are resolved as described in [OIMCOMMON], and oimce:unboundPrefix MUST be raised in the case of prefix resolution failure, rather than xbrlje:invalidFactValue.

decimals (number)
An integer providing the value of the {decimals} property, or absent if the value is infinitely precise or not applicable (for nil or non-numeric facts).
dimensions (object)
(required) A dimensions object with properties corresponding to the members of the {dimensions} property.
links (object)
A links object, cormesponding to the link groups associated with the fact. This member MAY be absent if there are no link groups associated with the fact.

Example 1: JSON example: fact

{ "f923": { "value": "1234", "dimensions": { "concept": "tax:NumericConcept", "entity": "cid:123456789", "period": "2015-01-01T00:00:00/2016-01-01T00:00:00", "unit": "iso4217:GBP", "tax:RegionDimension": "tax:Europe" } } }

5.2 Dimensions

JSON Object: Dimensions

This object represents the dimensions associated with a fact. Each property of the object corresponds to an dimension. For core dimensions, the name of the property is a simple string, as documented below. For taxonomy-defined dimensions the property name is a QName.

Members:
concept (string)
(required) The {value} property of the concept core dimension expressed as an xs:QName.
entity (string)
An SQName representing the {scheme} and {identifier} properties of the entity core dimension as the URI and localpart, respectively.
period (string)

A valid period string representation for the {interval} property of the period core dimension, if present. See Example 2 and Example 3.

unit (string)
The unit string representation of the unit core dimension component, if any. See Example 4.
language (string)
The value (xs:language) of the {language} property of the language core dimension. The code MUST be represented as a lowercase string (xbrlje:invalidLanguageCodeCase). See Example 5.
noteId (string)
The value (xs:NCName) of the {id} property of the note ID core dimension. See Example 7.
Any QName (string or null)

Any taxonomy-defined dimensions on the fact are included as properties with a name corresponding to the {name} property of the dimension, expressed as a QName. The value is the {value} property of the taxonomy-defined dimension expressed as described below.

If the dimension is an explicit taxonomy-defined dimension, the value MUST be a valid QName (xbrlje:invalidDimensionValue), and MUST NOT be the default member for that dimension (oime:invalidDimensionValue).

Otherwise, the value MUST be null or a value that is a valid lexical representation for the XML Schema datatype of the typed taxonomy-defined dimension (xbrlje:invalidDimensionValue). If the dimension is not a nillable, typed taxonomy-defined dimension then the value MUST NOT be null (xbrlje:invalidDimensionValue). If the value is prefixed content, any prefixes used MUST be defined in the namespaces object.

The property name MUST have a prefix and the prefix MUST NOT be xbrl (xbrlje:invalidJSONStructure)

If the value is prefixed content, any prefixes used are resolved as described in [OIMCOMMON], and oimce:unboundPrefix MUST be raised in the case of prefix resolution failure, rather than xbrlje:invalidDimensionValue.

See Example 6.

Example 2: JSON example: period dimension (duration)

"period": "2017-01-01T00:00:00/2018-01-01T00:00:00"

Example 3: JSON example: period dimension (instant)

"period": "2018-01-01T00:00:00"

Example 4: JSON example: unit dimension (US dollars per share)

"unit": "iso4217:USD/xbrli:shares"

Example 5: JSON example: language dimension

"language": "en-us"

Example 6: JSON example: taxonomy-defined dimensions

"tax:RegionDimension": "tax:Europe", "tax:CounterPartyLEI": "254900ARU0VC1WY6GJ71"

5.3 Links

JSON Object: Links
This object represents the link groups associated with an OIM fact.
Members:
name
A URI alias (xs:NCName) for the {link type} OIM property for the link group. The URI alias MUST be defined in the link types object (xbrlje:unknownLinkType).
value (object)
A link group object.
JSON Object: Link group
A link group object represents the link group OIM component.
Members:
name
A URI alias (xs:NCName) for the {group} OIM property. The URI alias MUST be defined in the linkGroups object (xbrlje:unknownLinkGroup).
value (array)
An array of xs:NCName values containing the {id} properties for the facts that are the targets of the relationships in this link group. If any item in this list does not correspond to the {id} property of a fact in the report, xbrlje:unknownLinkTarget MUST be raised.

Example 7: JSON example: a text footnote

{ "f923": { "value": "1234", "dimensions": { "concept": "tax:NumericConcept", "entity": "cid:123456789", "period": "2015-01-01T00:00:00/2016-01-01T00:00:00", "unit": "iso4217:GBP" }, "links": { "footnote": { "_": [ "f123", "f456" ] } } }, "f123": { "value": "This is an <b>important</b> footnote", "dimensions": { "concept": "xbrl:note", "noteId": "f123", "language": "en" }, } "f456": { "value": "This is a second footnote", "dimensions": { "noteId": "f456", "concept": "xbrl:note", "language": "en" } } }

Example 8: JSON example: a fact footnote

{ "f923": { "value": "1234", "dimensions": { "concept": "tax:NumericConcept", "entity": "cid:123456789", "period": "2015-01-01T00:00:00/2016-01-01T00:00:00", "unit": "iso4217:GBP" }, "links": { "explanatoryFact": { "_": [ "f924" ] } } }, "f924": { "value": "Some text explaining the other fact", "dimensions": { "concept": "tax:StringConcept", "entity": "cid:123456789", "period": "2014-01-01T00:00:00/2015-01-01T00:00:00" } } }

6 Features

The features mechanism allows an xBRL-JSON document to assert that it conforms to additional constraints beyond those required by this specification. This can be used by consuming software to safely make simplifying assumptions about how data can be processed.

A feature is a specific property of the document, identified by an expanded name. This specification defines standard features, which MUST be supported by all processors. Additional features MAY be defined by other specifications. Such specifications that are not published by XBRL International MUST NOT use a namespace that uses the xbrl.org domain name.

6.1 Standard features

This specification defines the following features:

6.1.1 The Canonical Values feature

The Canonical Values feature is identified by the QName xbrl:canonicalValues. If present, the feature MUST have a JSON boolean value (xbrlje:invalidJSONStructure).

An xBRL-JSON document with the xbrl:canonicalValues feature set to true MUST use the canonical representation for the following properties (xbrlje:nonCanonicalValue):

  • the values of any taxonomy-defined dimensions; and
  • the values of the value property of fact objects.

The canonical representation for values is as follows:

  • Values for set-valued enumeration facts MUST be lexicographically ordered. The ordering is applied to the QName value as it appears in the document (i.e. prefix then localname).
  • Values with a type, or derived from, xs:language MUST use the canonical lexical representation and be represented as a lower case string.
  • All other non-null values MUST use the canonical lexical representation for the XML Schema type on which they are based.

Note that this is in addition the requirement for canonicalisation of values where the datatype is specified in this specification (see Section 2.3).

6.1.2 Allowed Duplicates feature

This feature allows an xBRL-JSON document to declare what classes of duplicate facts, if any, are permitted in the report. By default, all types of duplicates are permitted.

The Allowed Duplicates feature is identified by the QName xbrl:allowedDuplicates, and takes one of the following string values:

If present, the xbrl:allowedDuplicates feature MUST have one of the values listed above (xbrlje:invalidJSONStructure).

Processors MUST use the error code oime:disallowedDuplicateFacts if prohibited duplicates are detected.

Appendix A References

DIMENSIONS
XBRL International Inc..
"XBRL Dimensions 1.0"
Ignacio Hernández-Ros
, and Hugh Wallis.
IETF RFC 2119
IETF (Internet Engineering Task Force).
"RFC 2119: Key words for use in RFCs to Indicate Requirement Levels"
Scott Bradner.
JSON
Internet Engineering Task Force.
"The JavaScript Object Notation (JSON) Data Interchange Format"
JSONPOINTER
Internet Engineering Task Force.
"JavaScript Object Notation (JSON) Pointer"
OIM
XBRL International Inc..
"XBRL Open Information Model"
Paul Warren.
OIMCOMMON
XBRL International Inc..
"XBRL Open Information Model Common Definitions"
Herm Fischer
, Mark Goodhand, and Paul Warren.
Taxonomy Package
XBRL International Inc..
"Taxonomy Packages 1.0"
Paul Warren
, and Herm Fischer.
URI
IETF (Internet Engineering Task Force).
"RFC 3986: Uniform Resource Identifier (URI): Generic Syntax"
T. Berners-Lee
, L. Masinter, and R. Fielding.
XBRL 2.1
XBRL International Inc..
"Extensible Business Reporting Language (XBRL) 2.1 Includes Corrected Errata Up To 2013-02-20"
Phillip Engel
, Walter Hamscher, Geoff Shuetrim, David vun Kannon, and Hugh Wallis.
XML Names
W3C (World Wide Web Consortium).
"Namespaces in XML 1.0 (Third Edition)"
XML Schema Datatypes
W3C (World Wide Web Consortium).
"XML Schema Part 2: Datatypes Second Edition"
Paul V. Biron
, and Ashok Malhotra.

Appendix B 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 (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 (www.xbrl.org/legal).

Appendix C Document History (non-normative)

DateAuthorDetails
04 June 2015Paul Warren

First Public Working Draft

14 December 2016Paul Warren

Candidate Recommendation

02 May 2017Paul Warren

Second Candidate Recommendation

12 December 2018Paul Warren

Third Candidate Recommendation

12 June 2019Paul Warren

Fourth Candidate Recommendation

07 May 2020Paul Warren

Fifth Candidate Recommendation

14 October 2020Paul Warren

Sixth Candidate Recommendation

03 February 2021Paul Warren

Seventh Candidate Recommendation

07 July 2021Paul Warren

Eighth Candidate Recommendation

04 August 2021Paul Warren

Proposed Recommendation

13 October 2021Paul Warren

Recommendation

Appendix D Errata Corrections incorporated in this document

This appendix contains a list of the errata that have been incorporated into this document. This represents all those errata corrections that have been approved by the XBRL International Specification Maintenance Working Group (SWG) up to and including 19 April 2023. Hyperlinks to relevant e-mail threads may only be followed by those who have access to the relevant mailing lists. Access to internal XBRL mailing lists is restricted to members of XBRL International Inc.

NumberDateSectionsDetails
1.29 September 2022 Section 5.2

Explicitly prohibit inclusion of default dimension values, and specify error code (#557).