Copyright © 2013 XBRL International Inc., All Rights Reserved.
Circulation of this Public Working Draft 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.
This document defines the requirements for an extension to enable efficient streaming of XBRL v2.1 instance documents.
1 Paul Warren:
To-do: error codes are required for all "MUST"s.
2 Paul Warren:
Note that this is effectively optional functionality, and so should be designated as such in the conformance suite.
1 Introduction
1.1 Terminology
2 Namespaces and namespace prefixes
3 Serialisation constraints
3.1 Header
3.1.1 Specification Version
3.2 Context
3.2.1 Context example
3.3 Units
3.3.1 Context and unit example
3.4 Footnotes
4 Processors
4.1 Definition
A References
B Intellectual property status (non-normative)
C Document history
D Errata corrections in this document
1 Namespaces and namespace prefixes
Configuration Aspect
Streamable Instance Document
Streamable Instance Document Header
Streaming Configuration
Validating Conformant Processor
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].
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.
| Prefix | Namespace URI | xbrli |
http://xbrl.org/2003/instance |
link |
http://xbrl.org/2003/linkbase |
|---|
A Streamable Instance Document is an XBRL v2.1 instance document that obeys the serialisation constraints defined in this section.
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 appear after the opening xbrli:xbrl tag for the document to which it relates, and before any child elements.
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.
A Streamable Instance Document Header MUST include a pseudo-attribute named version. The value of this pseudo-attribute MUST be a string consisting of two integer components, separated by a decimal point. 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.
A Streamable Instance Document
may optionally obey 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:
none, or absent: There are no constraints on the placement of xbrli:context elements beyond those imposed by XBRL v2.1.INF: In addition to the constraints imposed by XBRL v2.1, context declarations MUST appear before any facts which use them.contextBuffer Configuration Aspect.
The contextBuffer Configuration Aspect MUST have one of the values specified above, or be absent.
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.
A processor MAY be configurable to attempt to
consume a Streamable Instance
Document by assuming a more restrictive value for the
contextBuffer Configuration Aspect. If
processing is aborted because the document cannot be processed using
the assumed value, then it MUST be rejected with the
error codes below rather than the standard codes listed above.
This functionality is intended to allow a processor to attempt to consume documents that have no Streamable Instance Header by assuming specific sizes for the context and/or unit buffers. It also allows a processor to take a "best efforts" approach to all input. As noted in Section 4, it is also possible for processor to be configured to reject documents that either do not have a Streamable Instance Header, or which require too large a buffer.
[Paul Warren: Note that this is effectively optional functionality, and so should be designated as such in the conformance suite. ]
A Streamable Instance Document
may optionally obey 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:
none, or absent: There are no constraints on the placement of xbrli:unit elements beyond those imposed by XBRL v2.1.INF: In addition to the constraints imposed by XBRL v2.1, unit declarations MUST appear before any facts which use them.unitBuffer Configuration Aspect.
The unitBuffer Configuration Aspect MUST have one of the values specified above, or be absent.
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.
A processor MAY be configurable to attempt to
consume a Streamable Instance
Document by assuming a more restrictive value for the
unitBuffer Configuration Aspect. If
processing is aborted because the document cannot be processed using
the assumed value, then it MUST be rejected with the
error codes below rather than the standard codes listed above.
A Streamable Instance Document
may optionally obey additional constraints on the placement of link:footnoteLink
elements within the document.
The constraints to be followed are specified by the value of the
footnoteBuffer Configuration Aspect, which is
interpreted as follows:
none, or absent: There are no constraints on the placement of link:footnoteLink elements beyond those imposed by XBRL v2.1.INF: In addition to the constraints imposed by XBRL v2.1, link:footnoteLink elements MUST appear before any facts which are referenced by link:loc elements contained within them.INF, there MUST be no more than N-1 other link:footnoteLink elements appearing between a link:footnoteLink element and any fact referenced by a link:loc element contained within that link:footnoteLink, where N is the value of the footnoteBuffer Configuration Aspect.
The contextBuffer Configuration Aspect MUST have one of the values specified above, or be absent.
For example, a value of 1 for the
footnoteBuffer Configuration Aspect
would mean that all facts referenced by a footnote must
appear before the next link:footnoteLink element.
It should be noted that the many-to-many relationships between
footnotes and facts, and the fact that it
is not clear that multiple footnotes with the same content
referencing different footnotes are always semantically equivalent to
a single footnote referencing all such facts, means that, unlike the
contextBuffer and
unitBuffer Configuration Aspects, it
will not always be possible to serialise a document to comply with a
value of 1 for footnoteBuffer.
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.
For example, a particular application might wish to impose upper limits on the contextBuffer and unitBuffer values.
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).
| Date | Author | Details |
|---|---|---|
| 04 January 2013 | Paul Warren |
Initial draft. |
| 11 February 2013 | Paul Warren |
Change location of header processing instruction. Made header optional. Added support for footnotes. |
| 20 February 2013 | Paul Warren |
Fixed examples and typos. |
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 06 March 2013. 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.