xBRL-JSON: mapping from Open Information Model 1.0

Candidate Recommendation 02 May 2017

Copyright © XBRL International Inc., All Rights Reserved.

This version:
<http://www.xbrl.org/Specification/xbrl-json/CR-2017-05-02/xbrl-json-CR-2017-05-02.html>
Editors:
Paul Warren, XBRL International Inc. <pdw@xbrl.org>
Herm Fischer, Mark V Systems Limited <fischer@markv.com>
Contributors:
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>

Status

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.

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.

Comment

1 Paul Warren: PWD: The Working Group would value feedback on the merit of the SQName approach. The group considered the more verbose, but simpler and directly comparable Clark notation ("{URI}localname"), but is currently in favour of the more terse and readable QName-like approach. The definition of SQName has relaxed the format of the localname in order to allow it to be used for entity identifiers.

Table of Contents

1 Introduction
1.1 Terminology
 1.2 Namespaces and namespace prefixes
2 JSON mapping documentation conventions
3 Identifiers in xBRL-JSON
4 JSON representation constraints
5 XBRL Report Model (non-GL)
5.1 Aspects
 5.2 Footnotes

Appendices

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

Table

1 Namespaces and namespace prefixes

Examples

1 JSON example: simple fact
2 JSON example: tuple fact
3 JSON example: unit aspect (US dollars per share)
4 JSON example: language
5 JSON example: a text footnote
6 JSON example: a fact footnote

Definitions

Aspects (JSON Object)
Concept core aspect (JSON Member)
DTS reference (JSON Object)
Entity core aspect (JSON Member)
Footnote (JSON Object)
Language core aspect (JSON Member)
Period core aspect (JSON Members)
Prefix (JSON Member)
Prefixes (JSON Object)
Report (JSON Object)
Simple fact (JSON Object)
Taxonomy-defined aspect (JSON Member)
Tuple fact (JSON Object)
Tuple order aspect (JSON Member)
Tuple parent aspect (JSON Member)
Unit core aspect (JSON Member)

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 map and unit string representation are to be interpreted as described in the OIM Common Definitions specification [OIMCOMMON].

1.2 Namespaces and namespace prefixes

Many values in the Open Information Model are XML expanded names, the combination of a namespace URI and a localname. This specification uses QName 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.

As described in [OIMCOMMON], prefixes starting with "xbrl" are considered reserved, and use of the URIs associated with such prefixes MUST use that prefix if included in a prefix map in an xBRL-JSON document.

Table 1: Namespaces and namespace prefixes
Prefix Namespace URI
xbrl http://www.xbrl.org/CR/2017-05-02/oim
xbrli http://www.xbrl.org/2003/instance

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 components [JSON] that represent components in the XBRL Open Information Model [OIM]. Tables define the following types of JSON components:

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

[Paul Warren: PWD: The Working Group would value feedback on the merit of the SQName approach. The group considered the more verbose, but simpler and directly comparable Clark notation ("{URI}localname"), but is currently in favour of the more terse and readable QName-like approach. The definition of SQName has relaxed the format of the localname in order to allow it to be used for entity identifiers. ]

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

5 XBRL Report Model (non-GL)

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:
dtsReferences (array)
An array of DTS reference objects corresponding to the members of the {dts-references} property.
facts (array)
An array of simple fact and tuple fact objects corresponding to the members of the {facts} property.
prefixes (object)
A prefixes object defining the prefixes used by any SQName in this report (see Section 3).
documentType (string)
This property MUST be present with the value "http://www.xbrl.org/CR/2017-05-02/xbrl-json", and identifies the document as being a report covered by this specification.
JSON Object: Simple fact

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

Members:
id (string)
The value of the {id} property if present, otherwise this member MUST be absent or a generated, unique identifier for the simple fact. The {id} MUST be a valid NCName.
value (string)

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 are expressed as SQNames, and MUST use a prefix that is defined in the prefixes object.

accuracy (number)
The value of the {accuracy} property, or absent if the accuracy is infinite or not applicable (for non-numeric facts).
aspects
An aspects object with properties corresponding to the members of the {aspects} property.
footnotes (array)
An array of footnote JSON Objects, corresponding to the members of the {footnotes} property. This member MUST be absent if there are no footnotes.

Example 1: JSON example: simple fact

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

JSON Object: Tuple fact
A tuple fact component is represented by an object with the following members.
Members:
id (string)
The value of the {id} property if present, otherwise this member MUST be absent or a generated, unique identifier for the tuple fact. The {id} MUST be a valid NCName.
aspects
An aspects object with properties corresponding to the members of the {aspects} property.
footnotes (array)
An array of footnote JSON Objects, corresponding to the members of the {footnotes} property. This member MUST be absent if there are no footnotes.

Example 2: JSON example: tuple fact

{ "id": "f123", "aspects": { "xbrl:concept": "tax:TupleConcept" } }, { "id": "f124", "value": "This is a simple fact value", "aspects": { "xbrl:concept": "tax:StringConcept", "xbrl:entity": "cid:123456789", "xbrl:periodStart": "2015-01-01T00:00:00", "xbrl:periodEnd": "2016-01-01T00:00:00", "xbrl:tupleParent": "f123", "xbrl:tupleOrder": 1 } }, { "id": "f125", "value": "Last year's simple fact value", "aspects": { "xbrl:concept": "tax:StringConcept", "xbrl:entity": "cid:123456789", "xbrl:periodStart": "2014-01-01T00:00:00", "xbrl:periodEnd": "2015-01-01T00:00:00", "xbrl:tupleParent": "f123", "xbrl:tupleOrder": 2 } }

JSON Object: Prefixes

A JSON object providing a mapping of short prefixes to namespace URIs for use within SQNames appearing within the current JSON document.

Properties:
prefix
A set of prefix members.
JSON Member: Prefix
Properties:
name
The prefix to be defined. This MUST follow the constraints for SQName prefixes defined in [OIMCOMMON].
value (string)
The URI to be associated with the prefix. The value MUST be a valid URI (as defined in [URI]), and MUST be unique amongst the values in the object.
JSON Object: DTS reference
This object represents a DTS reference component.
Members:
href (string)
The value of the {href} property of the DTS reference component.
type (string)
The string "schema", "linkbase", "role" or "arcrole", determined by the value of the {type} property of the DTS reference component.

5.1 Aspects

JSON Object: Aspects
This object represents the aspects associated with a fact.
Members:
Aspects
A set of JSON members corresponding to the aspects associated with a fact. The JSON representation for each type of aspect is defined below.
JSON Member: Concept core aspect
This member represents the concept core aspect component.
name
An SQName representing xbrl:concept
value (string)
The {value} property expressed as an SQName.
JSON Member: Entity core aspect
This member represents the entity core aspect component.
name
A SQName representing xbrl:entity
value (string)
An SQName representing the {scheme} and {identifier} properties of the entity core aspect as the URI and localpart, respectively.
JSON Members: Period core aspect
These members represents the period core aspect component. If absent, the period value is forever (for simple facts) or not applicable (for tuple facts).
name
An SQName representing xbrl:periodStart.
value (string)

An ISO 8601 date time representations of the start of the duration denoted by the {interval} property.

name
An SQName representing xbrl:periodEnd.
value (string)

An ISO 8601 date time representations of the end of the duration denoted by the {interval} property.

The representations used for xbrl:periodStart, and xbrl:periodEnd values 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.

JSON Member: Unit core aspect
A JSON member representing the unit core aspect.
name
A unit string representation representing xbrl:unit
value (string)
A value corresponding to the unit string representation of the unit core aspect component.

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

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

JSON Member: Tuple parent aspect
This member represents the tuple parent aspect.
name
An SQName corresponding to xbrl:tupleParent
value (string)
The value of the id member of the tuple fact object that represents the fact identified by the {parent} property.
JSON Member: Tuple order aspect
This member represents the tuple order aspect.
name
An SQName corresponding to xbrl:tupleParent
value (number)
The value of the {order} property of the aspect.
JSON Member: Language core aspect
name
The expanded name corresponding to xbrl:language
value (string)
The value of the {language} property of language core aspect.

Example 4: JSON example: language

"xbrl:language": "en-US"

JSON Member: Taxonomy-defined aspect
This member is repeated for each taxonomy-defined aspect present on the fact.
name
The value of the {name} property of the taxonomy-defined aspect, expressed as a SQName.
value (string)

The value of the {value} property of the fact 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.

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

5.2 Footnotes

JSON Object: Footnote
This object represents a footnote OIM component.
Members:
group (string)
The value of the {group} property.
footnoteType (string)
The value of the {footnote type} property.
factRef (string)
If the footnote is a fact footnote then the value of the id member of the fact's JSON representation. This member is absent otherwise.
footnote (string)
If the footnote is a text footnote then the value of the {value} property. This member is absent otherwise.
language (string)
If the footnote is a text footnote then the value of the {language} property, otherwise this member is absent.

Example 5: JSON example: a text footnote

{ "id": "f923", "value": "1234", "aspects": { "xbrl:concept": "tax:NumericConcept", "xbrl:entity": "cid:123456789", "xbrl:periodStart": "2015-01-01T00:00:00", "xbrl:periodEnd": "2016-01-01T00:00:00", "xbrl:unit": "iso4217:GBP", }, "footnotes": [ { "group": "http://example.com/role/link1", "footnoteType": "http://www.xbrl.org/2003/arcrole/fact-footnote", "footnote": "Footnote text", "language": "en" } ] }

Example 6: JSON example: a fact footnote

{ "id": "f923", "value": "1234", "aspects": { "xbrl:concept": "tax:NumericConcept", "xbrl:entity": "cid:123456789", "xbrl:periodStart": "2015-01-01T00:00:00", "xbrl:periodEnd": "2016-01-01T00:00:00", "xbrl:unit": "iso4217:GBP" }, "footnotes": [ { "group": "http://example.com/role/link1", "footnoteType": "http://www.xbrl.org/2009/arcrole/fact-explanatoryFact", "factRef": "f924" } ] }, { "id": "f924", "value": "Some text explaining the other fact", "aspects": { "xbrl:concept": "tax:StringConcept", "xbrl:entity": "cid:123456789", "xbrl:periodStart": "2014-01-01T00:00:00", "xbrl:periodEnd": "2015-01-01T00:00:00", } }

Appendix A References

DIMENSIONS
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 RFC 2119
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)
JSON
Internet Engineering Task Force. "The JavaScript Object Notation (JSON) Data Interchange Format"
(See https://tools.ietf.org/html/rfc7159)
OIM
XBRL International Inc.. "XBRL Open Information Model"
Paul Warren.
(See http://www.xbrl.org/Specification/tbd/tbd.html)
OIMCOMMON
XBRL International Inc.. "XBRL Open Information Model Common Definitions"
Herm Fischer, Mark Goodhand, and Paul Warren.
(See http://www.xbrl.org/Specification/tbd/tbd.html)
URI
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).

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

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 02 May 2017. 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.