Copyright ©2012 XBRL International Inc., All Rights Reserved.
Circulation of this Candidate Recommendation is unrestricted. This document is normative. Other documents may supersede this document. Recipients are invited to submit comments to firstname.lastname@example.org, and to submit notification of any relevant patent rights of which they are aware and provide supporting documentation.
1.2 Relationship to other work
1.3 Language independence
1.5 Document conventions (non-normative)
1.6 Namespaces and namespace prefixes
1.7 XPath usage
1.7.1 XPath context item
2.1 Instance resource element
2.2 Instance-variable relationships
2.3 Formula-instance relationships
2.4 Chaining by instance relationships
2.5 Chaining Processing Model
3 Variable evaluation
3.1 Dimensional implicit filters and dimensional matching filters
4 Assertion evaluation
4.1 Consistency assertion evaluation
4.2 Existence assertion evaluation
The variable instances specification defines syntax for identification of instances as variable-set objects, so that multiple instances can be processed, and so that chaining by instance relationships can be supported.
It provides relationships that allow variables to be bound explicitly to specified instances, and that allow formula results to be directed explicitly to a specified instance.
Each instance is independent of the other; it may have a different DTS, or be an instance with some commonality of parts to other DTSes, but deemed independent of other instance DTSes.
This specification is a member of a suite of similar specifications that define specific types of criteria that can be used to select facts from one or more input XBRL instance. It enhances the fact selection capabilities of the XBRL Variables Specification [VARIABLES], the output production of the XBRL Formulas Specification, [FORMULA].
This specification depends upon the XBRL Specification [XBRL 2.1], and the XBRL Variables Specification [VARIABLES]. In the event of any conflicts between this specification and the specifications upon which it depends, this specification does not prevail.
The official language of XBRL International's own work products is English and the preferred spelling convention is UK English.
This specification is consistent with the definitions of any of the terms defined in specifications that it depends on.
Namespace prefixes [XML NAMES] will be used
for elements and attributes in
ns is the
namespace prefix and
name is the local name.
Throughout this specification, the mappings
from namespace prefixes to actual namespaces is consistent
The prefix column in Table 1 is non normative. The namespace URI column is normative.
XPath usage is identical to that in the XBRL Variables Specification [VARIABLES].
The XPath expressions specified or implied by a
or by a generalVariable,
where the variable has at least one
are evaluated using the sequence of
elements of the related
element, and its descendant nodes, are isolated to
the associate each such variable only to taxonomy information of its own DTS.
The XPath expressions specified or implied by all other constructs are evaluated
element of the standard normal source input instance to a
formula processor. (For example, XPath expressions of
formula elements are only
evaluated by the standard source input instance and its DTS, irrespective of the
instance-variable relationships of any variables in the related variable set.
This specification only provides a textual declaration of syntax constraints when those constraints are not expressed by the normative schema supplied with this specification.
Explanations of elements and attributes are only supplied when explanations are not already provided in other specifications.
Unless explicitly stated otherwise, a reference to a specific element MUST be read as a reference to that element or to any element in its substitution group.
The syntax for the
is defined by the normative schema supplied with this specification.
The instance resource represents a sequence of loaded XBRL
instances, each with its accompanying DTS, with a context element a sequence of
elements. It is of type variable:parameter, so that the semantics of parameter also apply to
the instance resource. (The parameter type is always element(xbrli:xbrl)*, its nodes are
treated as validated PSVI typed nodes.)
Instances can be loaded and saved by a formula processor in a similar manner as a formula processor does for its usual source input instance (and formula output instances), this is left unspecified to be an implementation issue.
Fact variables that are bound to item(s) of an instance are isolated to that instance and the DTS of that instance. If a fact variable is bound as a sequence there may be items from multiple instances together in the same sequence, each item associated individually with its instance and the DTS of its instance.
General variables that are bound to elements (or attributes) of an instance are isolated to that instance and the DTS of that instance. If bound as a sequence there may be nodes from multiple instances, each item associated individually with its instance and the DTS of its instance.
xbrli:xbrlelement if the respective DTS, such as may be supplied by using the instance resource's name as a variable QName, or any relevant expression such as
root(.)/xbrli:xbrl. Functions that expect a single
xbrli:xbrlparameter will not be applicable to instance resources that contain a sequence of zero or more than one XBRL instances, without further XPath coding (such as for loops).
An instance with the QName
refers to the standard normal source input instance to a formula processor, and with the QName
refers to the standard normal output instance for production of formula result items and result tuples.
Error code xbrlvarinste:inputInstanceDuplication MUST be thrown an input instance resource contains a sequence of XBRL instances with any duplication of an XBRL instance. Duplication is determined by comparison of system identifiers (with normalized URI paths). Input instances that are produced dynamically as output instances are not checked for duplication. This check is performed prior to the start of variable set processing.
Error code xbrlvarinste:standardInputInstanceNotUnique MUST be thrown the standard input instance resource contains a sequence of multiple XBRL instances. This is because the standard instance is used to discover formula linkbases and resolve them, and it is not desired to have multiple XBRL instances in a single standard input instance resource each contribute to discovery of co-mingled formula resources and relationships. This check is performed prior to the start of variable set processing.
An output instance resource has a sequence of one output XBRL instance (there is no facility to produce an output instance resource having a sequence of multiple output XBRL instances).
To declare an instance-variable relationship an XLink arc MUST:
The arcrole value,
is declared in the normative schema.
Instance-variable relationships MUST be expressed by generic arcs as indicated by the restrictions imposed by the arcrole declaration in the normative schema.
To declare an formula-instance relationship an XLink arc MUST:
The arcrole value,
is declared in the normative schema.
Formula-instance relationships MUST be expressed by generic arcs as indicated by the restrictions imposed by the arcrole declaration in the normative schema.
Chaining by instance relationships is a form of chaining, or staging result items of one formula, to be used as input terms by a subsequent formula, by explicit specification that the dependent terms are obtained as results from other formulas.This form of chaining can only relate the fact item produced by one formula to an input term of a subsequent variable set. See Chaining by variables scope for chaining by use of variable set in-scope variables visibility, which can also be used for tuples production. This form of chaining provides maximal isolation of the result-producing formula from the chained dependent value consuming formula.
|This example shows use of instance-variable and formula-instance relationships to relate two formulas, one producing a = b + c and the second producing c = d + e, to each other. The c = d + e formula produces its output fact item in an intermediate scratch-pad instance to be used by the dependant a = b + c formula.|
Processing order dependency is implied by instance-variable relationships that depend on facts produced by formulas with formula-instance relationships to the same instance for the same fact as is produced.
All formulas with formula-instance relationships to a given instance may be processed before any variable sets with variables having instance-variable relationships to the same instance are processed. (This is permissive, not mandatory.)
This specification anticipates that fact items of a consuming instance-variable relationship are not produced on demand by the producing formula-instance relationship, but instead that all of the formulas with formula-instance relationships may be completed before any varible-set bindings of instance-variable relationships attempt to consume such facts. This permits optimization of formula processor implementations. This specification does not make it an error for a formula processor to produce facts on demand before consumption.
Recursion and iteration is not provided by this processing model. It could be simulated by having each step of processing assigned to a separate intermediate instance, thus preventing the possibility of endless looping.
Example 1 of A = B + C chained from C = D + E produced a fact item of C in a separate instance document, a temporary instance result, from the fact item of A, in the standard output instance document. It is not required that the processor implementation support intermixing A and C in the same instance document, as that would create an on-demand dependency between producing formula and consuming variable set.
Error code xbrlvarinste:instanceVariableRecursionCycle MUST be thrown if there is a cycle where an variable set with a formula-instance relationship and a chained consuming variable set could or does evaluate recursively.
The specification in [VARIABLES] for variable evaluation is an evaluation against a single input XBRL instance. This specification allows that a variable MAY have instance-variable relationships, and that each non-standard input instance resource may in turn represent a sequence of multiple instances. Multiple such relationships to a single variable, and multiple XBRL instances in each instance resource, are conjoined, so that the evaluation is deemed by this specification to be an evaluation against the set of input XBRL instances represented by such relationships and resources.
The specification in [VARIABLES] for source sequence of evaluation is deemed by this specification to be a single conjoined set of the sequences obtained by evaluating the XPath expression implied by a general variable or a fact variable against the set of input XBRL instances represented by instance-variable relationships and instance resources.
The specification in [VARIABLES] of aspect test for the location aspect is not relevant when comparing facts of different instances, and will be deemed to always be true when this test pertains to a pair of facts of different input XBRL instances.
The specification in [VARIABLES] of aspect test for the dimension aspect specified by the explicit dimension aspect test is not relevant when comparing facts of different instances that have the default value for the subject dimension or no such subject dimension aspect (e.g., the facts lack a context element for the subject dimension), as described further below.
An instance resource is of type variable:parameter
and thus may have
that allow the instance resource to be treated as a named variable in the XPath expressions of
variables, their filters, parameters, etc. This is discouraged but provided as needed for debugging
and other such purposes. When an instance resource is referenced as a named variable, it has the same
semantics and behavior as a general variable bound by a
to that instance, with a select expression of "." (the
element of that
instance). If the instance resource is an output resource, it must be produced before it is consumed,
and if that instance resource is the target of a formula-instance relationship from the producing
variable set, then error code xbrlvarinste:instanceVariableRecursionCycle MUST be thrown.
There may be multi-instance situations where the DTS of the instance of a variable includes explicit dimensions with a default member that is not present or is different in the DTS of another instance of the same variable set, for the same dimension. The intent of this provision is to deem the dimension aspect irrelevant or matched if the dimension aspect has the default value or the dimension aspect is not present, so that two facts with contexts that do not specify an explicit dimension (because of either default value or absence of the dimension aspect) are deemed to pass the implicit filter or aspect matching test.
Two facts, A and B of instances instance-A and instance-B, are deemed to meet the criteria specified by the explicit dimension aspect test for an explicit dimension D if:
XPath expressions in assertion elements, and related validation messages, have the XPath context
1.7 of the
element of the standard normal source input instance to the formula processor.
Consistency assertion evaluation is specified in [CONSISTENCY ASSERTIONS] as evaluation against aspect-matched input facts of a single input XBRL instance, which for this specification refers to the standard normal source input instance to the formula processor.
Existence assertion evaluation is specified in [EXISTENCE ASSERTIONS] under processing model for existence assertions as most one evaluation for a given assertion input. If the variables of the existence assertion access multiple input instances by instance-variable relationships, the processing model must nevertheless have at most one evaluation of the existence assertion.
The following is the XML schema provided as part of this specification. This is normative. Non-normative versions (which should be identical to these except for appropriate comments indicating their non-normative status) are also provided as separate files for convenience of users of the specification.
NOTE: (non-normative) Following the schema maintenance policy of XBRL International, it is the intent (but is not guaranteed) that the location of non-normative versions of these schemas on the web will be as follows:
http://www.xbrl.org/2010/- during the drafting process for this specification this directory should contain a copy of the most recent published version of the schema at http://www.xbrl.org/2010/variable/instance.xsd.
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).
This document could not have been written without the contributions of many people including the participants in the Formula Working Group.
|13 December 2009||Herm Fischer||
First internal working draft created, drawing extensively on wiki page discussions in 2008 and early 2009, discussions with Fujitsu team at Bank of Japan hosted meeting in early 2009, and initial UBmatrix implementation.
|09 May 2010||Herm Fischer||
Revised per working group discussions to separate variable-scope relationships to a separate spec (variable-scope.xml), and to clarify processing model for dependencies between produced and consumed instances fact items.
|12 June 2010||Herm Fischer||
Per working group discussion 2010-06-03 added error xbrlvarinste:instanceVariableRecursionCycle.
|18 June 2010||Herm Fischer||
Added Section 1.7.1. Added instance-assertion arcs (subsequently removed by revision of 2011-03-07).
|20 June 2010||Herm Fischer|
|07 September 2010||Herm Fischer||
Editorial changes per Hitoshi Okumura. Corrected xsd arc role URIs to conform to spec documentation and error namespace. Added new paragraph to Variable Evaluation Section 3 on the possible use of the instance resource as a parameter variable, and such implications regarding chaining.
|07 March 2011||Herm Fischer||
Added to Section 3 that the location aspect test is deemed true when comparing facts of different instances. Removed references to instance-assertion relationship.
|10 March 2011||Herm Fischer||
Removed from Section 2.1 specification of producing the output instance DTS based on input instances and source rules, because the formula specification makes no statements about output instance DTS construction, and this subject is intended to be addressed by future separate documentation for both single-instance and multi-instance formula processing.
|07 September 2011||Herm Fischer||
With Victor Morilla added processing description to Section 3 specifying that implicit filtering and match filters for explicit dimensions that have default values are deemed matched when facts do not have the specified explicit dimension in their contexts, e.g., both may be default (even if default value differs in respective DTS) or dimension aspect does not apply (either no default or absent in respective DTS for the fact's primary item).
|09 May 2012||Herm Fischer||
With Victor Morilla clarified that instance resource elements of Section 2.1 are sequences. A non-standard input resource element may be associated with a sequence of zero or more input XBRL instances, an output resource element always has exactly one instance. Added error code when an instance resource (from an external source, such as input files) has duplicated XBRL instances in its sequence. Clarified processing description in Section 3 that input instance resources may be sequences of XBRL instances.
|07 June 2012||Herm Fischer||
With Takahide Muramoto clarified xbrlvarinste:inputInstanceDuplication and xbrlvarinste:standardInputInstanceNotUnique error processing.
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 Formula Working Group up to and including 03 October 2012. 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.