1 Introduction
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 both instance relationships and variables-scope 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.
It provides a relationship that allows explicit declaration of in-scope variables from another variable set, forming the basis for both chained variable sets and tuple generation (see tuples specification).
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.
1.1 Background
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], and forms the basis for the tuple output production by the XBRL Formula Tuples Specification [FORMULATUPLES].
1.2 Relationship to other work
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.
1.3 Language independence
The official language of XBRL International's own work products is English and the preferred spelling convention is UK English.
1.4 Terminology
This specification is consistent with the definitions of any of the terms defined in specifications that it depends on.
1.5 Document conventions (non-normative)
Documentation conventions follow those set out in the XBRL Variables Specification [VARIABLES].
1.6 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 consistent
with
Table
1.
The prefix column in Table 1 is non normative. The namespace URI column is normative.
| Prefix | Namespace URI |
|---|---|
instances
|
http://xbrl.org/2010/variable/instance
|
xbrlvarinste
|
http://xbrl.org/2010/filter/variable/instance/error
|
eg
|
http://example.com/
|
fn
|
http://www.w3.org/2005/xpath-functions
|
link
|
http://www.xbrl.org/2003/linkbase
|
xbrli
|
http://www.xbrl.org/2003/instance
|
xfi
|
http://www.xbrl.org/2008/function/instance
|
xbrldi
|
http://xbrl.org/2006/xbrldi
|
xbrldt
|
http://xbrl.org/2005/xbrldt
|
xl
|
http://www.xbrl.org/2003/XLink
|
xlink
|
http://www.w3.org/1999/xlink
|
xs
|
http://www.w3.org/2001/XMLSchema
|
xsi
|
http://www.w3.org/2001/XMLSchema-instance
|
gen
|
http://xbrl.org/2008/generic
|
variable
|
http://xbrl.org/2008/variable
|
iso4217
|
http://www.xbrl.org/2003/iso4217
|
2 Syntax
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.
2.1 Instance resource element
An instance resource is declared by a
<instanaces:instance>
element.
The syntax for the
<instances:instance>
element
is defined by the normative schema supplied with this specification.
The instance resource of an input instance document represents the loaded
instance with its accompanying DTS, with a context element of its <xbrli:xbrl>
element. 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 and general variables that are bound to elements of an instance are isolated to that instance and the DTS of that instance.
- The processor must associate each such variable only to taxonomy information of its own DTS.
- The node of such variable is deemed validated, and has the PSVI value of the corresponding DTS.
- In the same manner as an ordinary org.w3c DOM node knows which document it belongs to, a fact or general variable bound to a fact must correctly reference the DTS of the fact's instance document. Therefore the XPath2, function-registry functions, and custom functions must preserve sufficient formula processor reference information to associate the correct DTS with each bound variable. For example root, node-name, QName, and namespace URI functions know of each input instance variable in its own DTS (and don't intermix or mingle DTS element definitions or linkbase relationships with those of another input instance's DTS).
- Filters with knowledge of DTS link relationships, such as the dimensions filter and preliminary conceptRelation filter, refer only to the DTS that contains the element of the instance which is the context of the filter; all parameters to the filter (e.g., source of dimension, members of dimension, axes) must be of the same DTS as the element under consideration.
-
Functions with knowledge of
DTS relationships generally have an optional argument which is the
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$var/ancestor::xbrli:xbrlorroot(.)/xbrli:xbrl.
Output instances that are produced by the formula element, source, and aspect rules, have the DTS of output instance determined by source elements (and their original input instance associated DTS). Intermixing output facts with source or aspect rules of incompatible input instance DTSes will lead to invalid output instances, and should be avoided by formula authors (but is not intended to be detected automatically).
An output instance produced by a formula element with no sources (e.g., all aspects created by explicit aspect rules) must have the output DTS corresponding to the implied (ordinary) input DTS as it would be in the absence of any use of features of this specification.
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 named variable, and by variables-scope relationships where expression terms of a variable-set that is a target of a variables-scope relationship reference variables of the source variable set.
An instance with the QName
<instances:standard-input-instance>
refers to the standard normal source input instance to a formula processor, and with the QName
<instances:standard-output-instance>
refers to the standard normal output instance for production of formula result items and result tuples.
2.2 Instance-variable relationships
An instance-variable relationship is a specific relationship
between an
<instances:instance>
and a factVariable
or a generalVariable expressed by an
XLink arc.
To declare an instance-variable relationship an XLink arc MUST:
-
have an
arcrole value
equal to
http://xbrl.org/arcrole/2010/instance-variable - have an instance resource as the starting resource of the arc
- have a factVariable or generalVariable at the ending resource of the arc
The arcrole value,
http://xbrl.org/arcrole/2010/instance-variable,
is declared in the normative schema for messages.
Instance-variable relationships MUST be expressed by generic arcs as indicated by the restrictions imposed by the arcrole declaration in the normative schema.
2.3 Formula-instance relationships
An formula-instance relationship is a specific relationship
between a formula
and an
<instances:instance>
expressed by an
XLink arc.
To declare an formula-instance relationship an XLink arc MUST:
-
have an
arcrole value
equal to
http://xbrl.org/arcrole/2010/formula-instance - have a formula resource as the starting resource of the arc
- have an instance resource as the ending resource of the arc
The arcrole value,
http://xbrl.org/arcrole/2010/formula-instance,
is declared in the normative schema for messages.
Formula-instance relationships MUST be expressed by generic arcs as indicated by the restrictions imposed by the arcrole declaration in the normative schema.
2.4 Chaining by instance relationships
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 below 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. |
|
2.5 Variables-scope relationships
An variables-scope relationship is a specific relationship between two variable sets and an expressed by an XLink arc.
This relationship makes the in-scope variables of the relationship's source variable set visible as in-scope variables of the relationship's target variable-set.
If the source is
a formula, the optional @name attribute allows associating an in-scope variable, with the
name specified by this attribute, to the
factVariable node of the source formula. The factVariable is deemed validated, it's value and aspects
all have the PSVI typed values.
If the source is
a variableAssertion, the optional @name attribute allows associating an in-scope variable with the
name specified by this attribute, to the test expression of the source assertion. The test expression result
is deemed a boolean atomic value.
This can implement a form of chaining, and also is used to provide visibility to the location aspect of a parent tuple, to implement output of child factVariables, for tuples production (see tuples specification).
Any of the variables made in-scope by this relationship may have the same variable name as a variable of the target variable-set, in which case the variable of the target variable-set is accessible, and the like-named variable of the source variable-set is not available in the target variable-set.
To declare an variables-scope relationship an XLink arc MUST:
-
have an
arcrole value
equal to
http://xbrl.org/arcrole/2010/variables-scope - have a variable-set resource as the starting resource of the arc
- have an variable-set resource as the ending resource of the arc
The arcrole value,
http://xbrl.org/arcrole/2010/variables-scope,
is declared in the normative schema for messages.
variables-scope relationships MUST
be expressed by
<instances:variables-scope-arc>
as indicated by the restrictions imposed by the arcrole declaration
in the normative schema.
2.6 Chaining by variables-scope relationships
Chaining by variables scope is a form of chaining, or staging in-scope variables and result items of one value assertion, formula, or consistency assertion, to be used as input terms by a subsequent formula, by explicit specification that the dependent variable set has in-scope access to the prior variable set's variables and produced formula fact.
| This example shows use of variables-scope to relate two formulas, one producing a = b + c and the second producing c = d + e, to each other, with this relationship. The c = d + e formula produces its output fact item in the standard output instance, and makes it available as a named result of in-scope variables, to be used by the dependant a = b + c formula. |
|