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 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.
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].
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/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
|
1.7 XPath usage
XPath usage is identical to that in the XBRL Variables Specification [VARIABLES].
1.7.1 XPath context item
The XPath expressions specified or implied by a
factVariable and
its filters,
or by a generalVariable,
where the variable has at least one
instance-variable relationship
are evaluated using the sequence of <xbrli:xbrl> elements of the related
instances. Each <xbrli:xbrl> 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
using the <xbrli:xbrl> element of the standard normal source input instance to a
formula processor. (For example, XPath expressions of
parameters,
preconditions and
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.
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 variables that are bound to item(s) of an instance are isolated to that instance and the DTS of that instance. If 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.
- The processor must associate each such variable and variable node 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.
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.
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.
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 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 Chaining Processing Model
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.
3 Variable evaluation
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. If there are multiple such relationships to a single variable, the evaluation is deemed by this specification to be an evaluation against the set of input XBRL instances represented by such relationships.
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.
The specifications in [VARIABLES] for binding as a sequence and binding to an empty sequence apply to the single conjoined source sequence of evaluation of all related input XBRL instances.
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
variable-set relationships
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
instance-variable relationship
to that instance, with a select expression of "." (the <xbrli:xbrl> 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.
3.1 Dimensional implicit filters and dimensional matching filters
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:
- They meet the criteria specified by the explicit dimension aspect test for implicit filtering, or are deemed matching by a Dimension Matching Filter, or
- Both facts have the default value for the explicit dimension D in their respective DTS or do not have an explicit dimension aspect for dimension D. E.g., neither the context for fact A nor the context for fact B has a syntax element for explicit dimension D.
4 Assertion evaluation
XPath expressions in assertion elements, and related validation messages, have the XPath context
Section 1.7 of the <xbrli:xbrl>
element of the standard normal source input instance to the formula processor.
An assertion input is described in [VALIDATION] as a single input XBRL instance, which for this specification refers to the standard normal source input instance to the formula processor.
4.1 Consistency assertion evaluation
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.
4.2 Existence assertion evaluation
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.