Copyright ©2007 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 the authors and contributors, and to submit notification of any relevant patent rights of which they are aware and to provide supporting documentation.
This specification is an extension to the XBRL Specification [XBRL 2.1]. It defines syntax for structures that support the extraction and usage of information from an XBRL instance and its supporting discoverable taxonomy set.
This specification provides building blocks for other extension specifications including for XBRL formulae and for assertions about the expected content of XBRL instances.
1 Introduction
1.1 Background
1.2 Relationship to other work
1.3 Language independence
1.4 Terminology
1.5 Document conventions (non-normative)
1.5.1 Typographic conventions
1.5.1.1 Definition notation
1.5.1.2 Footnote notation
1.5.1.3 Element and attribute notation
1.5.2 Formatting conventions
1.6 Namespaces and namespace prefixes
1.7 XPath usage
1.7.1 Custom function signatures
1.7.2 Parameters
2 Syntax
2.1 General variables
2.2 XBRL fact variables
2.2.1 Filters
2.2.1.1 Variable-filter relationships
2.2.1.1.1 Variable-filter arcs
2.2.1.2 Variable-set-filter relationships
2.2.1.2.1 Variable-set filter arcs
2.3 Variable sets
2.3.1 Variable-set relationships
2.3.1.1 Variable arcs
2.3.2 Aspects
2.3.2.1 Aspect models
2.3.2.2 Implicit filters
2.3.3 Preconditions
2.3.3.1 Variable-set-precondition relationships
3 Variable evaluation
3.1 Fact variable evaluation
3.1.1 Binding as a sequence
3.1.2 Binding to an empty sequence
A Normative schema
B References
C Intellectual property status (non-normative)
D Acknowledgements (non-normative)
E Document history (non-normative)
F Errata corrections in this document
1 Namespaces and namespace prefixes
1 A normative example
2 A non-normative example
3 An example of poor usage
4 Circular variable references
XML schema
aspect
aspect model
aspect test
bind to sequence
can bind to an empty sequence
complemented variable-filter relationship
complemented variable-set-filter relationship
complete scenario aspect
complete segment aspect
concept aspect
covering filter
covering variable-filter relationship
covers an aspect
custom function
custom function signature
different variable-set evaluation
dimensional aspect model
entity identifier aspect
equivalent aspect value
evaluation exception
fact variable
fact variable evaluation
fallback value
filter
filter complement
general variable
general variable evaluation
group-filter
identical fact-variable evaluation
identical variable-set evaluation
location aspect
match
non-XDT scenario aspect
non-XDT segment aspect
non-covering filter
non-dimensional aspect model
parameter
period aspect
precondition
precondition expression
rfc2119 terminology
satisfied precondition
scenario dimension aspect
segment dimension aspect
source sequence
target XBRL instance
target fact
uncovered aspect
unit aspect
uses implicit filtering
variable arc
variable dependency
variable evaluation
variable set
variable set's aspect model
variable-filter arc
variable-filter relationship
variable-set evaluation
variable-set filter arc
variable-set relationship
variable-set resource
variable-set-filter relationship
variable-set-precondition relationship
xbrlve:cyclicDependencies
xbrlve:factVariableReferenceNotAllowed
xbrlve:missingImplicitFilters
xbrlve:noCustomFunctionSignature
xbrlve:parameterNameClash
xbrlve:parameterTypeMismatch
xbrlve:unknownAspectModel
xbrlve:unresolvedDependency
This specification is an extension to the XBRL Specification [XBRL 2.1]. It defines syntax for declaration of two kinds of variables: fact variables that only evaluate to sequences of facts in an XBRL instance and general variables that can evaluate to a broader range of values. This specification also defines syntax for parameters that can be given default values or values that are supplied by processing software.
XBRL variables play an important role in extracting information from an XBRL instance or a discoverable taxonomy set . XBRL variables can also be used to define constants and to define transformations of the information available in other variables.
Every XBRL variable implies an XPath expression. A variable is evaluated by evaluating the implied XPath in the context of an XBRL instance.
The XPath expressions implied by variables
are evaluated using the <xbrli:xbrl> element of the
target XBRL instance
as the context node.
As well as defining syntax for variables, this specification defines syntax for signatures of custom functions that can be used in XPath expressions and parameters that can be referenced in XPath expressions. These features are intended to enhance the usability of XBRL variables. They are also intended to form infrastructure for additional extension specifications that make use of XBRL variables.
The syntax for variables and parameters does not support specification of names that they can be referenced with in XPath variable references. Instead, names are associated with variables and parameters by the resources (formulae, assertions, etc.) that depend on them. This enables variables and parameters to be referred to by different names when used in different contexts.
This flexibility is important because the QNames in XPath variable references are hard coded into XPath expressions. Thus, the names of variables and parameters need to be able to adapt depending on the names used in the XPath variable references that they are being accessed by.
In many applications of XML [XML] the nested structure of XML resources means that XPath [XPATH 2.0] or XQuery [] is a natural and powerful means of selecting required information from XML resources.
For various reasons, the XBRL Specification [XBRL 2.1] makes minimal use of the normal hierarchical structure of XML, instead requiring relatively flat syntax for XBRL instances and for their supporting XML schemas and linkbases.
This design makes it cumbersome to use XPath or XQuery to select data from XBRL instances, at least without an extensive library of custom functions.
This specification provides a framework for an alternative syntax for specifying the filters that are to be applied to an XBRL instance to select the required data from them, if it is available. The alternative syntax is extensible in the sense that additional filters can be defined as they are deemed useful.
The alternative syntax is intended to be an improvement over direct use of XPath or XQuery in that allows users to work with the various kinds of relationships that exist in XBRL without burying them in XPath or XQuery contortions.
This specification depends upon the XBRL Specification [XBRL 2.1].
This specification is intended to be augmented with a range of separate filter specifications that provide concise syntax for selecting data from XBRL instances.
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.
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].
Where this document refers to an XML schema, it is referring to an XML document [XML] that contains a declaration of a schema that is compliant with XML Schema [XML SCHEMA STRUCTURES].
Comments which are informative, but not essential to the understanding of the point at hand, are provided in footnotes. All footnotes are non-normative.
When referring to a specific element, it will be identified by
its namespace prefix and local name. For example, the root
element for a specification container element would be referred to as
<variable:generalVariable>.
Attributes are also identified by their local name and, where
appropriate, their namespace prefix. Attributes are
distinguished from elements by prefixing them by an
@
symbol. Thus,
@id
refers to the attribute with the name id.
When referring to any attribute, so long as it has a specific
namespace, the local name is replaced by an asterisk (
*).
Thus, the notation @xml:* specifies any attribute
in the namespace
http://www.w3.org/XML/1998/namespace.
The following highlighting is used for normative technical material in this document:
Text of the normative example.
The following highlighting is used for non-normative examples in this document:
Text of the helpful example.
Next paragraph of the helpful example.
Example 3 shows the formatting for non-normative examples of poor, discouraged or disallowed usage.
The example itself.
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 |
|---|---|
variable
|
http://xbrl.org/2007/variable
|
xbrlve
|
http://xbrl.org/2007/variable/error
|
eg
|
http://example.com/
|
fn
|
http://www.w3.org/2006/xpath-functions
|
link
|
http://www.xbrl.org/2003/linkbase
|
xbrli
|
http://www.xbrl.org/2003/instance
|
xfi
|
http://www.xbrl.org/2005/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
|
generic
|
http://xbrl.org/2007/generic
|
iso4217
|
http://www.xbrl.org/2003/iso4217
|
Some attributes defined by this specification contain values that are evaluated as XPath 2.0 [XPATH 2.0] expressions. Wherever an XPath expression is mentioned in this specification it refers to an XPath 2.0 expression. The evaluation context for an XPath expression is determined by the attribute that contains the expression. The statically known namespaces used in the expressions are those that are in scope for the element that has the attribute that contains the XPath expression.
Evaluation of XPath expressions MUST NOT be performed using the XPath 1.0 compatibility mode.
QNames in each XPath expression MUST be resolvable using namespace declarations that are in scope for the element that contains the XPath expression. See Namespaces in XML [XML NAMES] for more information on namespace declarations and their scope.
An evaluation exception is defined as any one of a static error , a dynamic error , or a type error .
A custom function is an XPath function that is not defined in the XPath and XQuery Functions Specification [XPATH FUNCTIONS].
A custom function signature is declared by a <variable:function>
element.
The syntax for the <variable:function> element is defined by
the normative schema supplied with
this specification.
Custom functions MAY be used within XPath expressions.
[Error: Error code xbrlve:noCustomFunctionSignature MUST be thrown if a custom function is used in an XPath expression but does not have a custom function signature within the discoverable taxonomy set that is being processed. ]
The @name attribute on a custom function signature
contains the QName of the custom function.
The value of the @output attribute on a custom
function signature specifies the data type of the result
produced by evaluating the custom function.
The <variable:input> elements, if any, of a custom function
signature specify the data types of the custom function's input
parameters. The value of the @type attribute on
<variable:input> elements specifies the data type of the
input parameter.
The ordering of the custom function's input parameters matches
the document order of the <variable:input>child elements
of the custom function signature.
A parameter is declared by a <formula:parameter>
element.
The syntax for the <variable:parameter> element is defined
by the normative schema supplied with
this specification.
The @name attribute on a parameter
declaration contains the QName of the parameter
being declared. This is the QName used by the
formula processor to uniquely identify the parameter
when setting its value. It is not the QName by which
the parameter is referenced when it is used.
That QName is specified by relationship of the
parameter to the resource that makes use of it.
[Error:
Error code
xbrlve:parameterNameClash
MUST be thrown
if two parameters in the one
discoverable taxonomy set
have the same QName specified by their @name
attributes.
]
If the @required attribute on a parameter declaration
is equal to true, then the parameter is mandatory;
its value MUST be supplied by
the processing application.
The value of the parameter MAY be supplied
by the processing application. If no value is supplied by the
processing application and if the parameter is
not mandatory, then the supplied value MAY
be computed using the XPath expression given in the
@select attribute.
A parameter declaration MAY
contain an @as attribute that
specifies the data type required by the parameter.
[Error:
Error code
xbrlve:parameterTypeMismatch
MUST be thrown if the parameter value,
either supplied by the caller or determined from the
@select attribute on the parameter,
cannot be converted to the specified data type.
]
Sequence constructors are not available for declaring default parameter values.
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 .
A general variable is declared by a <variable:generalVariable>
element.
The syntax for the <variable:generalVariable> element is defined
by the normative schema supplied with
this specification.
The XPath expression implied by a general variable is the
content of the @select attribute on the general
variable. The context node for evaluation of the
XPath expression is the <xbrli:xbrl> element of the
target XBRL instance
.
A fact variable is declared by a <variable:factVariable>
element.
The syntax for the <variable:factVariable> element is defined
by the normative schema supplied with
this specification.
The XPath expression implied by a fact variable depends on its filters.
The XPath expression implied by a fact variable begins with:
xfi:facts-in-instance()
This term is followed by an
XPath predicate
that filters the facts in the sequence
produced by the xfi:facts-in-instance()
function.
The expression in the XPath predicate includes an
XPath expression implied by each of the fact variable's filters.
A fact variable can either use a filter or the filter complement to determine its implied XPath expression. The complement of a filter selects all of those facts that are not selected by the filter.
The XPath expression implied by a filter complement is the
fn:not()
function applied to the XPath expression implied by a filter.
If a fact variable is using a filter rather than its complement,
then the XPath expression implied by that filter is surrounded by
round brackets (, and ) before inclusion
in the XPath expression implied by the fact variable.
If a fact variable is using a filter complement rather than the filter, then the XPath expression implied by the filter complement is not modified before inclusion in the XPath expression implied by the fact variable.
To obtain the complete XPath expression in the XPath predicate,
the XPath expressions implied by the filters and the filter
complements are combined using the
and token to form a single
XPath and-expression
.
A filter defines selection criteria for facts in the target XBRL instance.
A target fact is a fact in the target XBRL instance that is being filtered.
Filters express criteria that can be applied to target facts. Such criteria are incorporated into the XPath expressions implied by fact variables.
Filters are declared as
XLink resources
in
XLink extended links
.
Filters MUST be in
the
substitution group
for
the abstract <variable:filter> element
.
All filters MUST imply an XPath expression that can be evaluated using any fact as a context node.
Every filter specification MUST include a definition of the XPath expression that is implied by the filter.
The XPath expression implied by a filter MAY include XPath variable references . Resolution of XPath variable references in the XPath expressions implied by filters is beyond the scope of this specification. Resolution of such XPath variable references needs to be addressed by specifications that build upon this specification. This includes specification of how variables are to be associated with the QNames used for XPath variable references.
A fact meets the criteria specified by a
filter only if the result of evaluating the
XPath expression implied by that filter,
using the fact as the context node,
results in an
effective Boolean value
of true.
Every explicit filter specification MUST indicate the aspects, if any, that it can cover.
A covering filter is a filter that does cover the aspect or aspects that it can cover.
A non-covering filter is a filter that does not cover the aspect or aspects that it can cover.
Whether a filter is covering or non-covering is specified as a part of the association between the filter and the fact variable that utilises it.
A filter complement never covers an aspect.
Filters MAY be associated with fact variables in the following three ways:
All methods of associating filters with fact variables identifying whether the filter covers aspects and whether the fact variable uses the filter or the filter complement.
A variable-filter relationship is a relationship between an fact variable and a filter expressed by an XLink arc.
To declare a variable-filter relationship an XLink arc MUST:
http://xbrl.org/arcrole/2007/variable-filter
The arcrole value,
http://xbrl.org/arcrole/2007/variable-filter,
is declared in
the normative schema
for variables.
Variable-filter relationships MUST be expressed by variable-filter arcs . Violations of this requirement can be detected by validation against the XBRL Specification [XBRL 2.1].
A fact variable with a complemented variable-filter relationship to a filter uses the filter complement in its implied XPath expression rather than the filter itself.
If a filter is related to a variable by a variable-filter relationship, that filter only covers aspects of the facts being filtered if the variable-filter relationship is covering .
A variable-filter arc is expressed by the <variable:variableFilterArc>
element.
The syntax for the <variable:variableFilterArc> element is defined by
the normative schema supplied with
this specification.
A variable-set-filter relationship is a relationship between a variable set resource and a filter expressed by an XLink arc.
To declare a variable-set-filter relationship an XLink arc MUST:
http://xbrl.org/arcrole/2007/variable-set-filter
The arcrole value,
http://xbrl.org/arcrole/2007/variable-set-filter,
is declared in
the normative schema
for variables.
Variable-set-filter relationships MUST be expressed by filter arcs . Violations of this requirement can be detected by validation against the XBRL Specification [XBRL 2.1].
A filter participating in a variable-set-filter relationship is, by definition, associated with each of the fact variables in variable set defined by the resource that it is related to.
The fact variables in a variable set defined by a resource with a complemented variable-set-filter relationship to a filter use the filter complement in their implied XPath expressions rather than the filter itself.
All filters that are associated with fact variables by variable-set-filter relationships, by definition, do not cover any aspects.
Filters that are associated with fact variables by variable-set-filter relationships MUST NOT imply XPath expressions that include XPath variable references to general variables or fact variables.
[Error: Error code xbrlve:factVariableReferenceNotAllowed MUST be thrown if a filter that is associated with fact variables by a variable-set-filter relationship implies an XPath expression that includes an XPath variable reference to a general variable or a fact variable. ]
A variable-set filter arc is expressed by the <variable:variableSetFilterArc>
element.
The syntax for the <variable:variableSetFilterArc> element is defined by
the normative schema supplied with
this specification.
The XPath expressions implied by variables can include XPath variable references that need to be resolved to other fact or general variables. This reference can only be resolved if the variable implying the XPath expression and the variable being referenced are in the same variable set.
Variable sets are defined by local XLink resources that are in the
substitution group
for the abstract <variable:variableSet> element.
Such resources are referred to as variable-set resources.
All variables that have
variable-set relationships
to a variable-set resource are in the variable set defined by that resource.
A variable-set relationship is a relationship between a variable-set resource and either a fact variable or a general variable , or a parameter expressed by an XLink arc.
To declare a variable-set relationship an XLink arc MUST:
http://xbrl.org/arcrole/2007/variable-set
The arcrole value,
http://xbrl.org/arcrole/2007/variable-set,
is declared in
the normative schema
for variables.
Variable-set relationships MUST be expressed by variable arcs . Violations of this requirement can be detected by validation against the XBRL Specification [XBRL 2.1].
The value of the @name attribute on a
variable arc
is the QName of the variable or parameter
in the variable-set relationship expressed by the arc.
When evaluating the variables in a variable-set, XPath variable references
with this QName are references to the variable or
parameter. Note that this parameter name MAY
differ from the name given in the
parameter
declaration.
A variable arc is expressed by the <variable:variableArc>
element.
The syntax for the <variable:variableArc> element is defined by
the normative schema supplied with
this specification.
XBRL facts are not just values. They are supported by a wide range of additional information that provides the information necessary to interpret the values contained by XBRL facts.
An aspect is defined as one part of the additional information about an XBRL fact.
A filter can cover an aspect if it selects facts using that aspect as a selection criterion.
Two facts have equivalent values for a given aspect if the aspect test for that aspect evaluates to true.
For two facts, an aspect test is an XPath expression
that can be used to test whether the aspect being tested is not
reported for both facts or is reported with an equivalent value
for both facts.
The context item when evaluating all aspect tests is the
<xbrli:xbrl> element of the target XBRL instance.
All aspect definitions MUST include the definition
of the aspect test to use when assessing the equivalency of two values
for the aspect being defined.
In this specification, an aspect test is expressed in terms of
an XPath expression that contains two
XPath variable references, one, $a for a variable that is equal
to the first fact in the comparison and the other, $b for the
variable that is equal to the second fact in the comparison.
Two values for the one aspect match if the aspect test for that aspect returns true when evaluated with two variables, one of which has the first value for the aspect and the other of which has the second value for the aspect.
This specification defines the following aspects for all facts, including tuples:
<xbrli:xbrl> element
at the root of the XBRL instance to the element that is the fact itself.
The aspect test for this aspect is:
$a/.. is $b/..(namespace-uri($a) = namespace-uri($b)) and (local-name($a) = local-name($b))This specification defines the following aspects for all items, but not for tuples:
(xfi:identifier-scheme($a) = xfi:identifier-scheme($b)) and (xfi:identifier-value($a) = xfi:identifier-value($b))xfi:s-equal(xfi:period($a), xfi:period($b))xfi:s-equal(xfi:segment($a), xfi:segment($b)) xfi:s-equal(xfi:segment-remainder($a), xfi:segment-remainder($b)) xfi:s-equal2( xfi:segment-dimension($a,#dimension), xfi:segment-dimension($b,#dimension) )
where #dimension is the QName of the dimension for which the aspect is defined.
xfi:s-equal(xfi:scenario($a), xfi:scenario($b)) xfi:s-equal(xfi:scenario-remainder($a), xfi:scenario-remainder($b)) xfi:s-equal2( xfi:scenario-dimension($a,#dimension), xfi:scenario-dimension($b,#dimension) )
where #dimension is the QName of the dimension for which the aspect is defined.
This specification defines the following aspect for for numeric items only:
xfi:s-equal(xfi:unit($a), xfi:unit($b)) or
There are a number of different ways that the additional information about an XBRL fact can be separated into a set of aspects. For example, the entity identification information could be treated as a single aspect or it could be treated as an entity identification scheme aspect and an entity identification value aspect. More significantly, the content of a segment or scenario can be treated as a single aspect or it can be broken down into a potentially large number of aspects.
This specification defines two aspect models.
Specifications that define new aspect models will need to specify new values
for the @aspectModel attribute to identify the new aspect models.
All aspect models MUST include the following aspects:
All aspect models MUST also include sufficient additional aspects to ensure that any content in context segments and scenarios is also associated with an aspect.
The value of the @aspectModel attribute on a
Variable-set resource specifies the aspect model to be
used when evaluating variables in the variable set defined
by the variable-set resource.
A variable set's aspect model is the aspect model identified by
the @aspectModel attribute on the variable-set resource defining the
variable set.
The variable set of a variable-set resource with an @aspectModel
attribute equal to dimensional has a dimensional aspect model.
The dimensional aspect model includes all of the aspects defined in this
specification except for
the complete segment aspect
and
the complete scenario aspect.
The variable set of a variable-set resource with an @aspectModel
attribute equal to non-dimensional has a non-dimensional aspect model.
The non-dimensional aspect model includes all of the aspects defined in this
specification except for
the non-XDT segment aspect,
the non-XDT scenario aspect,
the segment dimension aspect, and
the scenario dimension aspect.
[Error:
Error code xbrlve:unknownAspectModel
MUST be
thrown if the processing software does not recognise the aspect model
identified by the value of the @aspectModel attribute.
]
Fact variables in a variable set MAY be associated with implicit filters as well as filters that are related to them explicitly by variable-filter relationships and variable-set-filter relationships.
A variable set MUST have an @implicitFiltering attribute that is
equal to true if its fact variables are to have
implicit filters.
If the @implicitFiltering attribute is equal to false then
the fact variables in the variable set are not associated with implicit filters.
The implicit filters, if any, that are associated with the fact variables in a variable set depend on the variable set's aspect model.
If a variable set has a dimensional aspect model, then the fact variable in the variable set are associated with dimensional implicit filters.
If a variable set has a non-dimensional aspect model, then the fact variable in the variable set are associated with non-dimensional implicit filters.
[Error:
Error code xbrlve:missingImplicitFilters
MUST be
thrown if the processing software does not know the implicit filtering
system to be used for a variable set's aspect model and the
@implicitFiltering attribute equals true.
]
Variable set resources MAY be associated with preconditions by variable-set-precondition relationships. Preconditions are define conditions that must be satisfied if for a variable set evaluation to occur.
A precondition is expressed by the <variable:precondition>
element.
The syntax for the <variable:precondition> element is defined by
the normative schema supplied with
this specification.
The @test attribute on a precondition contains an
XPath expression. It's content is referred to as a
precondition expression.
A satisfied precondition is a precondition for which the
precondition expression evaluates to an
effective Boolean value
of true given the values of the variables in the variable set
that the precondition is associated with.
The
context node
for evaluation of precondition expressions is the
<xbrli:xbrl> element of the
target XBRL instance.
A variable-set-precondition relationship is a relationship between an variable-set resource and a precondition, expressed by an XLink arc.
To declare a variable-set-precondition relationship an XLink arc MUST:
http://xbrl.org/arcrole/2007/variable-set-precondition
The arcrole value,
http://xbrl.org/arcrole/2007/variable-set-precondition,
is declared in
the normative schema
for variables.
Variable-set-precondition relationships MUST be expressed by generic arcs . Violations of this requirement can be detected by validation against the XBRL Specification [XBRL 2.1].
A general variable evaluation is the evaluation of a general variable against a target XBRL instance.
A fact variable evaluation is the evaluation of a fact variable against a target XBRL instance.
A variable evaluation is either a general variable evaluation or a fact variable evaluation.
A variable-set evaluation is deemed to have occurred if all variables in the variable set have been evaluated and if all of the preconditions associated with the variable set are satisfied given the evaluations of the variables in the variable set. If there are no variables in the variable set, then the variable set is deemed to have been evaluated if the preconditions associated with the variable set are satisfied.
Two evaluations of a variable-set for a given input are identical variable-set evaluations if each fact variable evaluation in one variable set evaluation is identical to the evaluation of the same fact variable in the other variable set evaluation.
Two evaluations of a variable-set for a given input are different variable-set evaluations if they are not identical.
Two evaluations of a fact variable are identical fact-variable evaluations if: both evaluations are empty sequences; or both evaluations are sequences of nodes and for each node in the sequence for each evaluation, there is an identical node in the sequence for the other evaluation. The two evaluations of the fact variable MUST also be sequences of equal length if they are identical.
All variable evaluations begin with evaluation of the XPath expression implied by the variable.
[Error: Error code xbrlve:unresolvedDependency MUST be thrown if there an XPath expression to be evaluated has a variable dependency that cannot be resolved to a variable or parameter. ]
[Error: Error code xbrlve:cyclicDependencies MUST be thrown if there are circular dependencies in the references to variables in a variable set. ]
Fact variable $a implies an XPath expression that
includes an XPath variable reference to general variable $b.
General variable $b implies an XPath expression that
includes an XPath variable reference to general variable $c.
General variable $c implies an XPath expression that
includes an XPath variable reference to fact variable $a.
Note that a circular set of XPath variable references can involve both fact and general variables.
A source sequence is the sequence obtained by evaluating the XPath expression implied by a variable.
The result of evaluating a general variable is the source sequence. The result of evaluating a fact variable depends on the source sequence and a variety of attributes on the fact variable itself.
A fact variable binds to a sequence if it has a
@bindAsSequence attribute
with a value of true.
The result of a fact variable evaluation depends on whether the variable binds to a sequence.
If the source sequence is not empty and if the fact variable does not bind as a sequence, then the result of a fact variable evaluation is any one of the facts in the source sequence.
If the source sequence is not empty and if the fact variable does bind as a sequence, then the result of a fact variable evaluation is any sequence of facts that meets the following conditions:
The order of the facts in the evaluation result is application dependent. Evaluation results that only differ with regard to the order of the facts that they contain are deemed to be the same evaluation.
If the source sequence is empty, then the result
of a fact variable evaluation depends on the
@bindEmpty attribute and the @fallback
attribute on the fact variable.
A fact variable can bind to an empty sequence if it has a
@bindEmpty attribute with a value of true.
Otherwise a fact variable cannot bind to an empty sequence and so if the
source sequence is empty, the fact variable cannot be evaluated.
If a fact variable can bind to an empty sequence, and the source sequence
is empty, then the result of variable evaluation depends on whether
the fact variable includes a @fallbackValue attribute.
If a fact variable does not include a @fallbackValue attribute
then the result of the fact variable evaluation is the empty sequence.
If a fact variable includes a @fallbackValue attribute then the result
of the fact variable evaluation is given by evaluating the XPath expression
contained by the @fallbackValue attribute, using the
<xbrl:xbrli> element of the target XBRL instance as
the context node.
If all fact variables in a variable set evaluate to empty sequences or to fallback values, then the variable set is not deemed to have been evaluated.
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/2007/ - 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/2007/variable.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.
| Date | Author | Details |
|---|---|---|
| 18 December 2006 | Geoff Shuetrim |
First internal working draft created, drawing extensively on the previous formula specification drafts. |
| 23 April 2007 | Geoff Shuetrim |
Added identification of the context node for evaluation of the XPath expression implied by general variables based on the feedback from Masatomo Goto. Made the section on the XPath expression implied by a fact variable a sub-section of the section on fact variables. |
| 24 April 2007 | Geoff Shuetrim |
Introduced the sections on implicit filtering and distinguished the explicit filtering. Added the section on the evaluation of fact variables to specify how implicit filters are to be introduced into the evaluation of fact variables. |
| 25 May 2007 | Geoff Shuetrim |
Added a date to the arcrole defined in the specification. |
| 03 May 2007 | Geoff Shuetrim |
Changed the implicit filtering treatment for facts that have concepts with relationships to dimension hyper-cubes as defined in the XBRL Dimensions Specification. The implicit filter now involves a component for dimensions and a component for everything else in the segment or the scenario. |
| 07 May 2007 | Geoff Shuetrim |
Removed the requirement that relationships be defined in terms of the concrete arcs that express them. |
| 08 May 2007 | Geoff Shuetrim |
Added the implicit concept filter. |
| 29 May 2007 | Geoff Shuetrim |
Changed the name of the implicit sibling filter to the implicit location filter. Refined the algorithm for determining when implicit filters are required. |
| 13 June 2007 | Geoff Shuetrim |
Simplified the algorithm for inferring the need for implicit filters. Allowed general variables to bind as sequences or individually, analogously to fact variables, based on suggestions and motivating examples provided by Herm Fischer. |
| 25 June 2007 | Geoff Shuetrim |
Introduced implicit dimension filters and redefined the notion of coverable aspects. Refined the implicit segment and scenario filters to only deal with the content of segments and scenarios that are not reporting values for XDT dimensions. |
| 24 July 2007 | Hugh Wallis |
Edited for public working draft publication. |
| 30 September 2007 | Herm Fischer |
Added explanatory diagrams and text to clarify the operation of implicit filters. |
| 07 November 2007 | Geoff Shuetrim |
Converted the specification to XML format. Added in the definitions and the hyperlinks to the relevant sections of the normative schema. Moved the parameter resource to the variable specification so that it can be used with variables without needing to involve formula evaluation. Removed the language about inclusion of parameters in the DTS when evaluating XPath expressions because these kinds of problems will be covered by XPath evaluation exceptions. Defined an error code for parameter data type mismatches. Moved the material on custom function signatures to the variable specification. |
| 12 November 2007 | Geoff Shuetrim |
Linked all of the external terminology references back to bibliographic citations. Added a definition of an XPath evaluation exception to the section on XPath usage. This provides a catch all term for static, dynamic and type XPath errors. |
| 13 November 2007 | Geoff Shuetrim |
Defined a new variable-filter arc to provide for new attributes allowing a filter or its complement to be used for a fact variable and to allow a filter to cover or not cover an aspect. The arc expresses variable-filter relationships. Eliminated the distinction between explicit and implicit filters but enabled the association of filters with fact variables to be extensible so that such associations can be defined using structures other than variable-filter relationships. This opens up the possibility of defining the associations implicitly in a separate specification covering implicit filtering. This change removed the explanatory diagrams and examples provided by Herm Fischer. Added a final section to the specification to define the notion of an aspect of a fact. Following the suggestions from Masatomo Goto and Masaru Uchida, added abstract filter and variable element declarations to the normative schema and required all variables to be in the substitution group for the abstract variable element and all filters to be in the substitution group for the abstract filter element. All of the normative filter schemas have been updated to reflect this change. Changed the custom function signature specification of input parameter order to be based on document order instead of an order attribute to eliminate the need for an error code relating to ambiguous input parameter orderings.
Moved the |
| 14 November 2007 | Geoff Shuetrim |
Added the complete-segment and complete-scenario aspect definitions to support developments in the matching filter specification. These will support implicit filtering in a system that does not take the XBRL Dimensions Specification [DIMENSIONS] into account. Added the definition of an uncovered aspect to the section on aspects to support the specifications of relative filters and implicit filters. Eliminate mixed content features from the resources defined in this and dependent specifications based on the suggestion from Mark Goodhand Moved the sections on custom function signatures and parameters to the XPath usage section. Removed the boilerplate XPath usage reference to this specification, now that the XPath usage section in this specification is complete. |
| 15 November 2007 | Geoff Shuetrim |
Weakened the definition of covering an aspect so that a filter covers an aspect if it always uses that aspect in its filtration criteria. This is important because coverage is not just about tying all aspects to specific values but it is also able just finding the aspects that you do not want to match to other fact variables in the group of variables being evaluated. Resolved issue of interaction between aspect coverage and filter complements (filters with the XPath fn:not() function applied to them) by specifying that filter complements do not cover aspects. Moved a paragraph introducing the syntax section to the introduction to fit better with the shift of the parameters and custom function signatures to the XPath usage section. Added the definition of a variable set to the specification to better support structures like implicit filtering. Variable sets are sets of variables that can reference each-other using XPath variable references. This definition enables scoping issues to be clearer in things like the formula specification. |
| 19 November 2007 | Geoff Shuetrim |
Added the dimensions specification and the XLink specification to the list of references.
As suggested by Victor Morilla,
defined the Formally defined covering and non-covering filters to support the terminology set out in the implicit filter specification. |
| 23 November 2007 | Geoff Shuetrim |
Fixed up wording problems in the abstract as detected by Jim Richards. Improved the wording in relation to variables that evaluate as sequences. Added a statement to the effect that if all XPath expressions implied by all fact variables in a variable set evaluate to empty sequences, then evaluation of all variables in the variable set and any XPath expressions that reference those variables MUST stop. |
| 23 November 2007 | Jim Richards |
Reworded definitions for target facts and target XBRL instances so that the terminology being defined is the first part of the definition. Made some minor grammatical corrections. |
| 26 November 2007 | Jim Richards |
Reworded definitions for sections on Aspects of Facts and Variable Evaluation so that the terminology being defined is the first part of the definition. Made some minor grammatical corrections and re-ordered some paragraphs in the sections mentioned. |
| 26 November 2007 | Geoff Shuetrim |
Added explanatory material to the introduction on variable and parameter naming.
Added an error code to cover situations where two
parameters in the one DTS have the same value of their
Added in variable-set-filter relationships to address the syntax niceties sought by Victor Morilla. |
| 27 November 2007 | Geoff Shuetrim |
Incorporated the proposal from Victor Morilla regarding the definition of an evaluation of a variable that is allowed to bind to a sequence of facts. Moved the formula section on implicit filters back to the variable specification and expressed it in terms of a variable-set resource so that the notion of implicit filtering is available for variable usages going beyond formula evaluation.
Provided formal definitions of aspect-models and variable sets
to support a clearer definition of when and how implicit filters
are to be used. Changed how the aspect model to use (what aspects
are defined for the facts being filters) is identified so that we
are not using the Defined the notion of an aspect test to be used to test for the equivalency of the value of an aspect for two different facts. Defined the notion of a variable-set precondition and the notion of a variable-set evaluation, thus enabling preconditions and variable-set evaluations to be used for both formulae and assertions. Added paragraphs to define the evaluation ordering of variables in a variable set. This improves on the ordering of formula-variable relationships that was in the formula specification. Added an error code to cover situations where a variable set resource has variable-set relationships to variables that are in different relationship networks. This blocks situations where an ordering of variables could otherwise need to be defined across networks of relationships. |
| 28 November 2007 | Victor Morilla |
Corrected a few bibliographic references Added comments on variable-set-filters Added comments on attributes for general variables Comment on context node for most XPath expressions Comments on order of evaluation Included error for cyclic references |
| 29 November 2007 | Geoff Shuetrim |
Removed explicit ordering of variables in a variable set given that it is no longer needed for implicit filtering, as per suggestion from Victor Morilla. Removed attributes relating to binding process for general variables as per suggestion from Victor Morilla. Refined aspect test definition to cover cases where the aspect is not reported for the facts being tested. |
| 30 November 2007 | Geoff Shuetrim |
Added in a missing arcrole declaration to the normative schema. Fixed up various cross-link ID attribute values. |
| 03 December 2007 | Geoff Shuetrim |
Added in a definition of an aspect match to support context and unit construction rules in the formula specification. Added rules to the section on aspect models to require that all aspect models cover all of the required aspects for facts and cover the information that can be contained in segments and scenarios. |
| 04 December 2007 | Geoff Shuetrim |
Added definitions of different and identical variable-set evaluations. These support extensions such as assertion specifications where assertion results depend on a count of the different possible variable-set evaluations that are possible with a given target XBRL instance. |
| 05 December 2007 | Geoff Shuetrim |
Modified the normative schemas to make them conform to XML Schema.
Till now, they have not been conformant because all resources were
in the substitution group for the |
| 07 December 2007 | Geoff Shuetrim |
As recommended by Herm Fischer, added a sentence to variable set evaluation definition to clarify the edge case where the variable set has no variables. |
| 13 December 2007 | Geoff Shuetrim |
Changed the |
| 24 December 2007 | Geoff Shuetrim |
Fixed up schema imports in the normative schema to include an import of the generic link schema to support some software that expects such imports when arcrole type declarations refer to elements in those schemas and to include an import of the XBRL 2.1 schemas on the public XII website. |
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 31 December 2007. 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.