XBRL Streaming Extensions Module 1.0

Candidate Recommendation 09 December 2015

Copyright © 2013, 2015 XBRL International Inc., All Rights Reserved.

This version:
<http://www.xbrl.org/Specification/streaming-extensions-module/CR-2015-12-09/streaming-extensions-module-CR-2015-12-09.html>
Editor:
Paul Warren, XBRL International (formerly CoreFiling) <pdw@xbrl.org>
Contributor:
Mark Goodhand, CoreFiling <mrg@corefiling.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 spec@xbrl.org, and to submit notification of any relevant patent rights of which they are aware and provide supporting documentation.

Abstract

This document defines the requirements for an extension to enable efficient streaming of XBRL v2.1 instance documents.

Table of Contents

1 Introduction
1.1 Terminology
2 Namespaces and namespace prefixes
3 Conventions used in this document
4 Serialisation constraints
4.1 Header
4.1.1 Specification Version
4.2 Context
4.2.1 Context example
4.3 Units
4.3.1 Context and unit example
4.4 Footnotes
4.4.1 link:loc
4.4.2 link:footnote
4.4.3 Footnote relationships
5 Processors
5.1 Definition
5.2 Processor Configuration

Appendices

A References
B Intellectual property status (non-normative)
C Document history
D Errata corrections in this document

Table

1 Namespaces and namespace prefixes

Definitions

Configuration Aspect
Streamable Instance Document
Streamable Instance Document Header
Streaming Configuration
Validating Conformant Processor

Error codes

xsee:ContextOutOfScope
xsee:IllegalFootnoteArc
xsee:IllegalFootnoteResource
xsee:IllegalLocator
xsee:InvalidContextBufferValue
xsee:InvalidFootnoteRelationshipBufferValue
xsee:InvalidFootnoteResourceBufferValue
xsee:InvalidLocatorBufferValue
xsee:InvalidUnitBufferValue
xsee:InvalidVersionAttributeFormat
xsee:MisplacedFootnoteResource
xsee:MisplacedFootnoteSource
xsee:MisplacedLocator
xsee:MisplacedStreamableInstanceDocumentHeader
xsee:MissingStreamableInstanceHeader
xsee:MissingVersionAttribute
xsee:RelationshipBufferOverflow
xsee:StreamingRequirementsExceedConfiguredProcessorLimits
xsee:TooManyFootnoteResources
xsee:TooManyLocators
xsee:UnitOutOfScope
xsee:UnresolvedFootnoteRelationship


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 key words concept, context, fact, footnote, instance and unit. in this document are to be interpreted as described in the XBRL Specification [XBRL 2.1].

The key words processing instruction in this document are to be interpreted as described in the XML Specification [XML].

2 Namespaces and namespace prefixes

Namespace prefixes [XML Names] will be used for elements and attributes in the form ns:name where ns is the namespace prefix and name is the local name. Throughout this specification, the mappings from namespace prefixes to actual namespaces is as defined in Table 1.

Table 1: Namespaces and namespace prefixes
Prefix Namespace URI
xseehttp://xbrl.org/CR/2015-12-09/streaming-extensions/errors
xbrli http://xbrl.org/2003/instance
link http://xbrl.org/2003/linkbase

3 Conventions used in this document

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.

4 Serialisation constraints

A Streamable Instance Document is an XBRL v2.1 instance document that obeys the serialisation constraints defined in this section.

4.1 Header

A Streamable Instance Document MAY include a Streamable Instance Document Header.

A Streamable Instance Document Header is an XML processing instruction with a target of xbrl-streamable-instance.. A Streamable Instance Document Header MUST only appear after the opening xbrli:xbrl tag for the document to which it relates, before any child elements, and MUST NOT be repeated. (xsee:MisplacedStreamableInstanceDocumentHeader)

The content of the processing instruction is treated as a string containing pseudo-attributes, and is parsed according to the rules defined in [XMLSTYLESHEET]. The resulting set of pseudo-attributes is the Streaming Configuration, with each pseudo-attribute defining a Configuration Aspect. This specification defines behaviour based on the value of Configuration Aspects with specific names. Configuration Aspects with names that are not documented in this specification MAY also appear. The names and values of Configuration Aspects are case-sensitive.

4.1.1 Specification Version

A Streamable Instance Document Header MUST include a pseudo-attribute named version (xsee:MissingVersionAttribute). The value of this pseudo-attribute MUST be a string consisting of two integer components, separated by a decimal point (xsee:InvalidVersionAttributeFormat). The component before and after the decimal point are referred to as the major and minor version respectively.

This specification defines the semantics for documents with a version number of "1.0". Future specifications defining semantics for other versions with a major version of "1" will only add features that are backwards compatible with this specification. A processor conforming to this specification MUST accept Streamable Instance Documents with a major version of "1".

Processors MUST reject Streamable Instance Documents with an unsupported major version number. Note that a processor MAY support future versions of this specification in addition to this one, and rejection should occur only if the major version number used is not defined by any supported specification.

4.2 Context

A Streamable Instance Document obeys additional constraints on the placement of xbrli:context elements within the document by declaring that contexts will appear before the facts that reference them, or by declaring the maximum number of context declarations that are necessary to be retained when consuming the instance in document order.

The constraints to be followed are specified by the value of the contextBuffer Configuration Aspect, which is interpreted as follows:

  • INF, or absent: In addition to the constraints imposed by XBRL v2.1, context declarations MUST appear before any facts which use them.
  • any positive, non-zero integer value: Any reference to a context by a fact must refer to a context declaration which is in the preceding N context declarations, where N is the value of the contextBuffer Configuration Aspect.

Processors MUST raise xsee:ContextOutOfScope when encountering a fact for which the referenced xbrli:content element is not within the scope defined by the above rules.

The contextBuffer Configuration Aspect MUST have one of the values specified above, or be absent (xsee:InvalidContextBufferValue).

4.2.1 Context example

In the example below, the contextBuffer Configuration Aspect has a value of one. This means that only the most recent context declaration is available for use by facts.

<xbrli:xbrl
  xmlns
="http://www.example.com/mytaxonomy"

  xmlns:xbrli
="http://www.xbrl.org/2003/instance"
>
<?xbrl-streamable-instance version="1.0" contextBuffer="1" ?>
<xbrli:context id="c1">
<!-- ... -->
</xbrli:context>
<xbrli:context id="c2">
<!-- ... -->
</xbrli:context>
<!-- Only context c2 is in scope at this point -->
<fact1 contextRef="c2">
My fact
</fact1>
<xbrli:context id="c3">
<!-- ... -->
</xbrli:context>
</xbrli:xbrl>

4.3 Units

A Streamable Instance Document obeys additional constraints on the placement of xbrli:unit elements within the document by declaring that units will appear before the facts that reference them, or by declaring the maximum number of unit declarations that are necessary to be retained when consuming the instance in document order.

The constraints to be followed are specified by the value of the unitBuffer Configuration Aspect, which is interpreted as follows:

  • INF, or absent: In addition to the constraints imposed by XBRL v2.1, unit declarations MUST appear before any facts which use them.
  • any positive, non-zero integer value: Any reference to a unit by a fact MUST refer to a unit declaration which is in the preceding N unit declarations, where N is the value of the unitBuffer Configuration Aspect.

Processors MUST raise xsee:UnitOutOfScope when encountering a fact for which the referenced xbrli:unit element is not within the scope defined by the above rules.

The unitBuffer Configuration Aspect MUST have one of the values specified above, or be absent (xsee:InvalidUnitBufferValue ).

4.3.1 Context and unit example

In the example below, the contextBuffer Configuration Aspect has a value of one, and the unitBuffer Configuration Aspect has a value of INF. This combination is usually a good default, as the number of units in the document is typically small, whereas for highly dimensional documents, the number of contexts is likely to increase with the number of facts.

<xbrli:xbrl
  xmlns
="http://www.example.com/mytaxonomy"

  xmlns:xbrli
="http://www.xbrl.org/2003/instance"
>
<?xbrl-streamable-instance version="1.0" contextBuffer="1" unitBuffer="INF"?>
<xbrli:unit id="u1">
<!-- ... -->
</xbrli:unit>
<xbrli:unit id="u2">
<!-- ... -->
</xbrli:unit>
<xbrli:context id="c1">
<!-- ... -->
</xbrli:context>
<xbrli:context id="c2">
<!-- ... -->
</xbrli:context>
<!-- All preceding units are in scope at this point. Unit u3 is out of scope. -->
<fact1 contextRef="c2" unitRef="u1">
My fact
</fact1>
<xbrli:unit id="u3">
<!-- ... -->
</xbrli:unit>
<xbrli:context id="c3">
<!-- ... -->
</xbrli:context>
</xbrli:xbrl>

4.4 Footnotes

4.4.1 link:loc

A Streamable Instance Document obeys additional constraints on the placement of <link:loc> elements within each <link:footnoteLink> element, with all such locators appearing before the arcs that reference them, and optionally obeying a limit on the maximum number of locator elements that appear within each <link:footnoteLink> element.

The constraints to be followed are specified by the value of the locatorBuffer Configuration Aspect, which is interpreted as follows:

  • INF, or absent: In addition to the constraints imposed by XBRL v2.1, link:loc elements MUST appear before any arcs that reference them (xsee:MisplacedLocator).
  • 0: link:loc elements MUST NOT appear in the instance document (xsee:IllegalLocator).
  • any positive, non-zero integer value: In addition to the constraints of "INF", there MUST NOT be more than this number of locators in any <link:footnoteLink> element (xsee:TooManyLocators).

The locatorBuffer Configuration Aspect MUST have one of the values specified above, or be absent (xsee:InvalidLocatorBufferValue).

It should be noted that the constraints imposed by this specification are in addition to the requirements of XBRL v2.1, which requires that link:loc elements appear within the same link:footnoteLink element as the link:footnoteArc elements that reference them.

4.4.2 link:footnote

A Streamable Instance Document obeys additional constraints on the placement of <link:footnote> elements within each <link:footnoteLink> element, with all such footnotes appearing before the arcs that reference them, and optionally obeying a limit on the maximum number of footnote elements that appear within each <link:footnoteLink> element.

The constraints to be followed are specified by the value of the footnoteResourceBuffer Configuration Aspect, which is interpreted as follows:

  • INF, or absent: In addition to the constraints imposed by XBRL v2.1, link:footnote elements MUST appear before any arcs that reference them (xsee:MisplacedFootnoteResource).
  • 0: link:footnote elements MUST NOT appear in the instance document (xsee:IllegalFootnoteResource).
  • any positive, non-zero integer value: In addition to the constraints of "INF", there MUST NOT be more than this number of footnote elements in any <link:footnoteLink> element (xsee:TooManyFootnoteResources).

The footnoteResourceBuffer Configuration Aspect MUST have one of the values specified above, or be absent (xsee:InvalidFootnoteResourceBufferValue).

4.4.3 Footnote relationships

A Streamable Instance Document may optionally obey additional constraints on the number of footnote relationships that are necessary to be retained when processing the instance. A single link:footnoteArc may represent multiple footnote relationships as there may be multiple resources or locators sharing the same XLink label.

The constraints to be followed are specified by the value of the footnoteRelationshipBuffer Configuration Aspect, which is interpreted as follows:

  • INF, or absent: In addition to the constraints imposed by XBRL v2.1, link:footnoteArc elements MUST appear before any facts referenced by the footnoteArc. For footnote relationships that associate a fact with another fact (e.g. those with arcrole http://www.xbrl.org/2009/arcrole/fact-explanatoryFact), it is additionally required that the target fact MUST appear before the source fact.
  • 0: link:footnoteArc elements MUST NOT appear in the instance document (xsee:IllegalFootnoteArc).
  • any positive, non-zero integer value: In addition to the constraints imposed for 'INF', it MUST be possible to consume the instance in document order by maintaining a buffer of no more than N footnote relationships, where footnote relationships are added to the buffer when a link:footnoteArc is processed, and removed when both endpoints have been processed, where N is the value of the footnoteRelationshipBuffer Configuration Aspect.

A processor MUST raise xsee:RelationshipBufferOverflow if it is not possible to consume the document using the specified buffer size, and error xsee:UnresolvedFootnoteRelationship if there are relationships in the document that cannot be fully resolved using only facts that appear after the corresponding link:footnoteArc element. xsee:MisplacedFootnoteSource MUST be raised if the source fact for a fact-to-fact relationship is discovered before the target fact.

The footnoteRelationshipBuffer Configuration Aspect MUST have one of the values specified above, or be absent (xsee:InvalidFootnoteRelationshipBufferValue).

5 Processors

5.1 Definition

A Validating Conformant Processor is a processor which consumes Streamable Instance Documents conforming to the constraints prescribed in Section 4 and rejects all other input with the prescribed error codes.

5.2 Processor Configuration

A Validating Conformant Processor MAY be configurable to only accept Streamable Instance Documents with specified values for particular Configuration Aspects, and to reject other input. Where this is done, a processor MUST reject documents that do not have a Streamable Instance Document Header (xsee:MissingStreamableInstanceHeader), or where any of the Configuration Aspects in the header exceed a limit configured for the processor (xsee:StreamingRequirementsExceedConfiguredProcessorLimits).

For example, a particular application might wish to impose upper limits on the contextBuffer and unitBuffer values, in order to limit the potential memory usage of the streaming processor. By configuring such limits in the processor, instance that do not include a streaming header, or which have a streaming header that declares a requirement for a larger contextBuffer or unitBuffer can be quickly rejected by the processor.

Appendix A References

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)
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
W3C (World Wide Web Consortium). "Extensible Markup Language (XML) 1.0 (Fifth Edition)"
Tim Bray
, Jean Paoli, C. M. Sperberg-McQueen, Eve Maler, and François Yergeau.
(See http://www.w3.org/TR/REC-xml/)
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)
XMLSTYLESHEET
W3C (World Wide Web Consortium). "Associating Style Sheets with XML documents 1.0 (Second Edition)"
James Clark
, Simon Pieters, and Henry S. Thompson.
(See http://www.w3.org/TR/xml-stylesheet/)

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

DateAuthorDetails
04 January 2013Paul Warren

Initial draft.

11 February 2013Paul Warren

Change location of header processing instruction. Made header optional. Added support for footnotes.

20 February 2013Paul Warren

Fixed examples and typos.

24 November 2015Paul Warren

Added footnote functionality. Added requirement for processors to immediately reject documents that do not meet configured constraints, and to reject documents without headers where such constraints are configured.

Appendix D Errata corrections 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 Base Specification and Maintenance Working Group up to and including 09 December 2015. 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.