xBRL-JSON: mapping from Open Information Model 1.0

Candidate Recommendation 12 December 2018

Copyright © XBRL International Inc., All Rights Reserved.

This version:
Paul Warren, XBRL International Inc. <pdw@xbrl.org>
Herm Fischer, Mark V Systems Limited <fischer@markv.com>
Daniel Dracott, CoreFiling <djd@corefiling.com>
Mark Goodhand, CoreFiling <mrg@corefiling.com>
Eleanor Joslin, CoreFiling <ejj@corefiling.com>
Harald Schmitt, ABZ Reporting <harald.schmitt@abz-reporting.com>


Circulation of this Candidate Recommendation is unrestricted. This document is normative. Other documents may supersede this document. 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.


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.2.2 JSON mapping documentation conventions
1.3 Namespaces and namespace prefixes
1.4 Validation
2 Identifiers in xBRL-JSON
3 JSON representation constraints
4 Extensibility
5 XBRL Report Model
5.1 Aspects
5.2 Links
6 Features
6.1 Standard features
6.1.1 The Canonical Values feature


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


1 Namespaces and namespace prefixes


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


Aspects (JSON Object)
Canonical form
Document info (JSON Object)
Fact (JSON Object)
Facts (JSON Object)
Features (JSON Object)
Link group (JSON Object)
Links (JSON Object)
Prefixes (JSON Object)
Report (JSON Object)
Space-separated list

Error codes

xbrlje:invalidJSONStructure 2 3 4 5
xbrlje:unknownPrefix 2

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 report, numeric fact, text fact and enumeration fact are to be interpreted as described in the Open Information Model specification [OIM].

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.

1.2.2 JSON mapping documentation conventions

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

Each value within a JSON Object MUST have the specified JSON value type (xbrlje:invalidJSONMemberType).

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

1.3 Namespaces and namespace prefixes

Many values in the Open Information Model are XML expanded names, that is, the combination of a namespace URI and a localname. This specification uses SQName notation in the form prefix:localname to refer to these, where the prefix is a short string representing a full namespace URI. The prefixes used by this specification are defined below.

All prefixes defined in the table below are reserved prefixes as described in [OIMCOMMON]. Use of the URIs associated with these prefixes MUST use that prefix if included in a prefix map in an xBRL-JSON document (xbrlje:invalidPrefixForStandardURI).

Table 1: Namespaces and namespace prefixes
Prefix Namespace URI
xbrl http://www.xbrl.org/CR/2018-12-12
xbrli http://www.xbrl.org/2003/instance
footnotes http://www.xbrl.org/2003/arcrole/fact-footnote
explanatoryFact http://www.xbrl.org/2009/arcrole/fact-explanatoryFact
defaultGroup http://www.xbrl.org/2003/role/link
xsd http://www.w3.org/2001/XMLSchema

1.4 Validation

A processor that consumes xBRL-JSON documents MUST raise an error with the specified error code 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 Identifiers in xBRL-JSON

xBRL-JSON makes use of SQNames to represent expanded names and some other values. The prefix map for resolving SQNames is provided by the prefixes object.

3 JSON representation constraints

RFC 7159 [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:invalidJSONStructure).

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

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 elsewhere (xbrlje:invalidJSONStructure).

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

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.
facts (object)
(required) 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.

documentType (string)
(required) This property MUST be present with the value "http://www.xbrl.org/CR/2018-12-12/xbrl-json", and identifies the document as being a report covered by this specification.
features (object)
(required) A features object.
prefixes (object)
(required) A prefixes object defining the prefixes used by any SQName in this report (see Section 2).
taxonomy (array)
(required) An array of URLs corresponding to the {href} properties of the members of the {dts-references} property for the {report}.
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.

An QName corresponding to the name of feature
value (any)
Any 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: Facts

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

The value 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.

value (string)

(required) The value of the {value} property of the fact in a lexical representation that is valid according to the XML Schema datatype [XML Schema Datatypes], or in the case of nil-valued facts, the JSON literal null.

Facts of type xsd:QName and enumeration facts are expressed as SQNames, and MUST use a prefix that is defined in the prefixes object. In the case of set-valued enumeration facts, the value is a space-separated list of SQNames.

accuracy (number)
The value of the {accuracy} property, or absent if the accuracy is infinite or not applicable (for non-numeric facts).
aspects (object)
(required) An aspects object with properties corresponding to the members of the {aspects} property.
links (object)
A links object, cormesponding to the link groups associated with the fact. This member MUST be absent if there are no link groups associated with the fact.

A space-separated list is a string containing items that are separated by a single space character (unicode 0x20). The list MUST NOT contain sequences of more than one space character, or space characters at the beginning or end of the string.

Example 1: JSON example: fact

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

JSON Object: Prefixes

A JSON object providing a prefix map for use within SQNames appearing within the current JSON document. The prefix map MUST conform to the constraints defined in [OIMCOMMON] (xbrlje:invalidPrefixMap).

The prefix to be defined.
value (string)
The URI to be associated with the prefix [URI].

5.1 Aspects

JSON Object: Aspects

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

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

If the {interval} property denotes a duration of non-zero length then ISO 8601 date time representations of the start and end of that duration, separated by the "/" character, otherwise, a single ISO 8601 date time representation of the instant denoted by the {interval} property. See Example 2 and Example 3.

The date time representations used in this property MUST be valid according to the xsd:dateTime datatype. It should be noted that unlike the xbrli:dateUnion type used in xBRL-XML, the xsd:dateTime datatype used here does not allow the time component to be omitted.

unit (string)
A value corresponding to the unit string representation of the unit core aspect component. See Example 4. The value MUST be a valid unit string representation (xbrlje:invalidUnitString).
language (string)
The value of the {language} property of the language core aspect. See Example 5.
noteId (string)
The value of the {id} property of the note ID core aspect. See Example 7.
Any SQName (string)

Any taxonomy-defined aspects on the fact are included as properties with a name corresponding to the {name} property of the aspect, expressed as a SQName. The value is the {value} property of the taxonomy-defined aspect expressed in a lexical representation that is valid according to the XML Schema datatype of the aspect, or in the case of nil-valued aspects, the JSON literal null. See Example 6.

Aspects of type xsd:QName are expressed as SQNames, and MUST use a prefix that is defined in the prefixes object.

Example 2: JSON example: period aspect (duration)

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

Example 3: JSON example: period aspect (instant)

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

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

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

Example 5: JSON example: language aspect

"language": "en-US"

Example 6: JSON example: taxonomy-defined aspects

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

5.2 Links

JSON Object: Links
This object represents the link groups associated with an OIM fact.
A prefix for the {link type} OIM property URI for the link group. The prefix MUST be defined in the prefixes object (xbrlje:unknownPrefix).
value (object)
A link group object.
JSON Object: Link group
A link group object represents the link group OIM component.
A prefix for the {group} OIM property URI. The prefix MUST be defined in the prefixes object (xbrlje:unknownPrefix).
value (array)
An array of the {id} properties for the facts that are the targets of the relationships in this link group.

Example 7: JSON example: a text footnote

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

Example 8: JSON example: a fact footnote

{ "f923": { "value": "1234", "aspects": { "concept": "tax:NumericConcept", "entity": "cid:123456789", "period": "2015-01-01T00:00:00/2016-01-01T00:00:00", "unit": "iso4217:GBP" }, "links": { "explanatoryFacts": { "defaultGroup": [ "f924" ] } } }, "f924": { "value": "Some text explaining the other fact", "aspects": { "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. 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 a single feature, the Canonical Values feature.

6.1.1 The Canonical Values feature

The Canonical Values feature is identified by the SQName xbrl:canonicalValues, and takes a simple boolean value to indicate its enablement.

An xBRL-JSON document that declares this feature MUST use the canonical form for the following values:

  • the values of properties of aspects objects; and
  • the values of the value property of fact objects.

The canonical form of a value is the canonical lexical representation [XML Schema Datatypes] for the value's datatype, with the following special cases:

  • The period aspect should be treated as either a single xsd:dateTime value or a pair of xsd:dateTimes separated by the "/" character.
  • The language aspect, and any other values with a datatype of, or derived from, xsd:language, MUST be respresented as lowercase strings.

Appendix A References

XBRL International Inc.. "XBRL Dimensions 1.0"
Ignacio Hern√°ndez-Ros
, and Hugh Wallis.
(See http://www.xbrl.org/Specification/XDT-REC-2006-09-18.htm)
IETF (Internet Engineering Task Force). "RFC 2119: Key words for use in RFCs to Indicate Requirement Levels"
Scott Bradner.

(See http://www.ietf.org/rfc/rfc2119.txt)
Internet Engineering Task Force. "The JavaScript Object Notation (JSON) Data Interchange Format"
(See https://tools.ietf.org/html/rfc7159)
XBRL International Inc.. "XBRL Open Information Model"
Paul Warren.

(See https://specifications.xbrl.org/release-history-open-information-model-oim.html)
XBRL International Inc.. "XBRL Open Information Model Common Definitions"
Herm Fischer
, Mark Goodhand, and Paul Warren.
(See https://specifications.xbrl.org/release-history-open-information-model-oim-common.html)
IETF (Internet Engineering Task Force). "RFC 3986: Uniform Resource Identifier (URI): Generic Syntax"
T. Berners-Lee
, L. Masinter, and R. Fielding.
(See http://tools.ietf.org/html/rfc3986)
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.
(See http://www.xbrl.org/Specification/XBRL-2.1/REC-2003-12-31/XBRL-2.1-REC-2003-12-31+corrected-errata-2013-02-20.html)
XML Names
W3C (World Wide Web Consortium). "Namespaces in XML 1.0 (Third Edition)"
(See http://www.w3.org/TR/2009/REC-xml-names-20091208)
XML Schema Datatypes
W3C (World Wide Web Consortium). "XML Schema Part 2: Datatypes Second Edition"
Paul V. Biron
, and Ashok Malhotra.
(See http://www.w3.org/TR/xmlschema-2/)

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


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)

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

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 12 December 2018. 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.

No errata have been incorporated into this document.