1 Introduction

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 target XBRL instance is the single XBRL instance that variables are evaluated against in the processing model for variables.

The XPath expressions implied by variables are evaluated using the <xbrli:xbrl> element of the target XBRL instance as the context item.

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 can be used as XPath variable references. Instead, names are associated with variables and parameters by the relationships to 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.

1.1 Background

In many applications of XML [XML] the nested structure of XML resources means that XPath [XPATH 2.0] or XQuery [XQUERY 1.0] 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 based on their content and their supporting discoverable taxonomy sets, at least without a 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.

1.2 Relationship to other work

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.

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.

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].

1.5 Document conventions (non-normative)

1.5.1 Typographic conventions

1.5.1.1 Definition notation

Definitions are highlighted with green text.

1.5.1.2 Footnote notation

Comments which are informative, but not essential to the understanding of the point at hand, are provided in footnotes. All footnotes are non-normative.

1.5.1.3 Element and attribute notation

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.

1.5.2 Formatting conventions

The following highlighting is used for normative technical material in this document:

Example 1: A normative example

Text of the normative example.

The following highlighting is used for non-normative examples in this document:

Example 2: A non-normative example

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.

Example 3: An example of poor usage

The example itself.

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.

Table 1: Namespaces and namespace prefixes

Prefix	Namespace URI
`variable`	`http://xbrl.org/2008/variable`
`xbrlve`	`http://xbrl.org/2008/variable/error`
`aspectTest`	`http://xbrl.org/2008/variable/aspectTest`
`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`
`iso4217`	`http://www.xbrl.org/2003/iso4217`

1.7 XPath usage

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.

The default function namespace is http://www.w3.org/2005/xpath-functions. This means that functions in this namespace do not require a namespace prefix when they are called.

As required by Section 3.1.2 of the XPath 2.0, the variable name used in an unprefixed variable reference is in no namespace. Care needs to be taken to ensure that the default namespace for element and attribute names is not used when determining the QName for variables with no namespace prefix.

The data type of attributes with values that are variable QNames is variable:QName. This distinguishes those attributes from other elements and attributes containing QNames that have data type xs:QName. This distinction prevents the variable QName resolution method from defaulting to the resolution meothod for QNames with data type xs:QName. This is necessary because variable names with no namespace prefix are not to be resolved in the same way as other QNames with no namespace prefix.

Error code xbrlve:variableNameResolutionFailure MUST be thrown if an attribute containing the QName of a fact variable or general variable specifies a namespace prefix that cannot be resolved to a namespace declaration that is in scope for the containing element.

QNames in each XPath expression MUST be resolvable using the specific resolution rules set out in this specification and the 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.

All of the XQuery/XPath data models used for XPath processing MUST be constructed using the relevant Post Schema Validation Infoset.

2 Aspects

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.

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.

An aspect test is an XPath expression that defines an equivalence relation for values of its aspect.

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 can be used to test whether an aspect 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.

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.

Two facts are aspect-matched facts if they have exactly the same aspects and, for each of aspect that they both have, the value for that aspect matches for the two facts.

In this specification, an aspect test is expressed in terms of an XPath expression that contains two XPath variable references, one, $aspectTest:a for a variable that is equal to the first fact in the comparison and the other, $aspectTest:b for the variable that is equal to the second fact in the comparison.

This specification defines the following aspects for all facts, including tuples:

The location of the fact is the ordered sequence of elements from the <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: $aspectTest:a/.. is $aspectTest:b/..
The concept aspect is the concept that the fact reports a value for. The aspect test for this aspect is: (namespace-uri($aspectTest:a) eq namespace-uri($aspectTest:b)) and (local-name($aspectTest:a) eq local-name($aspectTest:b))

This specification defines the following aspects for all items, but not for tuples:

The entity identifier aspect is the identifier of the entity that the fact reports a value for. The aspect test for this aspect is: (xfi:identifier-scheme($aspectTest:a) eq xfi:identifier-scheme($aspectTest:b)) and (xfi:identifier-value($aspectTest:a) eq xfi:identifier-value($aspectTest:b))
The period aspect is the period that the fact reports a value for. The aspect test for this aspect is: xfi:s-equal(xfi:period($aspectTest:a), xfi:period($aspectTest:b))
The complete segment aspect is the complete content of the segment, without interpreting it using the XBRL Dimensions Specification [DIMENSIONS], if a segment is contained by the context of the fact. The aspect test for this aspect is: xfi:s-equal(xfi:segment($aspectTest:a), xfi:segment($aspectTest:b))
The non-XDT segment aspect is the content of the segment, excluding content defined in the XBRL Dimensions Specification [DIMENSIONS], if a segment is contained by the context of the fact. The aspect test for this aspect is: xfi:s-equal(xfi:fact-segment-remainder($aspectTest:a), xfi:fact-segment-remainder($aspectTest:b))
The complete scenario aspect is the complete content of the scenario, without interpreting it using the XBRL Dimensions Specification [DIMENSIONS], if a scenario is contained by the context of the fact. The aspect test for this aspect is: xfi:s-equal(xfi:scenario($aspectTest:a), xfi:scenario($aspectTest:b))
The non-XDT scenario aspect is the content of the scenario, excluding content defined in the XBRL Dimensions Specification [DIMENSIONS], if a scenario is contained by the context of the fact. The aspect test for this aspect is: xfi:s-equal(xfi:fact-scenario-remainder($aspectTest:a), xfi:fact-scenario-remainder($aspectTest:b))
Dimension aspects are XBRL dimensions that are reported in the fact's segment or scenario. The details of aspect tests for dimension aspects are provided in Section 2.1.

This specification defines the following aspect for for numeric items only:

The unit aspect is the unit of the fact. The aspect test for this aspect is: xfi:s-equal(xfi:unit($aspectTest:a), xfi:unit($aspectTest:b))

2.1 Dimension aspect tests

A dimension aspect test is an aspect test for a dimension aspect.

Dimension aspect tests depend on whether the is an explicit dimension or a typed dimension, and, if the dimension is a typed dimension, whether a equality definition has been associated with the typed-dimension domain definition of the typed dimension.

2.1.1 Explicit-dimension aspect tests

An explicit-dimension aspect test is a dimension aspect test for an explicit dimension.

Explicit-dimension aspect tests are:

xfi:elements-correspond(xfi:fact-explicit-dimension-value($aspectTest:a,#dimension),xfi:fact-explicit-dimension-value($aspectTest:b,#dimension))

where $aspectTest:a and $aspectTest:b are defined as in Section 2, and #dimension is the QName of the dimension defining the aspect.

2.1.2 Typed-dimension aspect tests

A typed-dimension aspect test is a dimension aspect test for a typed dimension.

A typed dimension value is a value of a typed dimension in an XBRL instance. Syntactically, it is the single XML fragment with root element that is the child element of the typed-dimension's dimension container.

Typed-dimension aspect tests are tests of equality between typed dimension values for the same typed dimension.

A typed-dimension domain definition is the element in an XML Schema that defines the content model for a typed dimension and that is identified as such by an @xbrldt:typedDomainRef attribute on the XML Schema element declaring a typed dimension.

Note that [DIMENSIONS] allows more than one typed dimension to use the same typed-dimension domain definition.

Typed-dimension aspect tests depend upon whether the typed dimension defining the dimension aspect has a typed-dimension domain definition that, itself, has an equality definition.

A default typed-dimension aspect test is a typed-dimension aspect test for a typed dimension that does not have an equality definition associated with its typed-dimension domain definition.

A custom typed-dimension aspect test is a typed-dimension aspect test for a typed dimension that does have an equality definition associated with its typed-dimension domain definition.

2.1.2.1 Default typed-dimension aspect tests

Two element/attribute nodes, A and B have the same name if either they both have QName names, Aqn and Bqn, and the XPath 2.0 expression (Aqn eq Bqn) evaluates to an effective Boolean value of true when using the empty sequence as the context item; or they both have names that are not defined in any namespace, An and Bn, and the XPath 2.0 expression (An eq Bn) evaluates to an effective Boolean value of true when using the empty sequence as the context item.

Two attribute nodes, A and B, are corresponding attributes if the following conditions are all satisfied:

A and B have the same name
The sequences of atomic values obtained by atomizing A and B, As and Bs, are the same length and for each item Ai, at position i in As, the item Bi at position i in Bs, is such that the XPath 2.0 expression (Ai eq Bi) evaluates to an effective Boolean value of true when using the empty sequence as the context item.

Note that if the attribute nodes, A and B, both atomize to empty sequences then those attribute nodes correspond.

Two element nodes, A and B, are corresponding elements if the following conditions are all satisfied:

A and B have the same name
The sequences of atomic values obtained by atomizing A and B, As and Bs, are the same length and for each item Ai, at position i in As, the item Bi at position i in Bs, is such that the XPath 2.0 expression (Ai eq Bi) evaluates to an effective Boolean value of true when using the empty sequence as the context item.
A and B have the same number of attributes^{[
1
]}
For each attribute on element node A, there is a corresponding attribute on element node B.
A and B have the same number of child elements.
For each child element of element node A, Ac, there is a corresponding child element of element node B, Bc, such that Ac and Bc have the same number of preceding sibling elements.

Note that, as for attribute nodes, if the element nodes, A and B, both atomize to empty sequences then those element nodes correspond.

Two typed dimension values are corresponding typed-dimension values if they are values for the same typed dimension and their root elements correspond.

The default typed-dimension aspect test is:

(fn:count(xfi:fact-typed-dimension-value($aspectTest:a,#dimension)/*) eq 1) and (fn:count(xfi:fact-typed-dimension-value($aspectTest:b,#dimension)/*) eq 1) and (xfi:nodes-correspond(xfi:fact-typed-dimension-value($aspectTest:a,#dimension)/*[1],xfi:fact-typed-dimension-value($aspectTest:b,#dimension)/*[1]))

where $aspectTest:a and $aspectTest:b are defined as in Section 2, and #dimension is the QName of the dimension defining the aspect.

2.1.2.2 Custom typed-dimension aspect tests

The custom typed-dimension aspect test is:

(fn:count(xfi:fact-typed-dimension-value($aspectTest:a,#dimension)/*) eq 1) and (fn:count(xfi:fact-typed-dimension-value($aspectTest:b,#dimension)/*) eq 1) and (#custom)

where $aspectTest:a and $aspectTest:b are defined as in Section 2, #dimension is the QName of the dimension defining the aspect, and #custom is the XPath expression contained by the @test attribute on the equality definition that MUST be associated with the typed-dimension's domain definition if the custom typed-dimension aspect test is to be applicable.

2.1.2.2.1 Equality definitions for typed dimensions

An equality definition is a definition of equality between any two values in a typed-dimension's domain definition. It is expressed by a <variable:equalityDefinition> element.

The syntax for the <variable:equalityDefinition> element is defined by the normative schema supplied with this specification.

The content of the @test attribute on an equality definition is an XPath expression that is incorporated into the custom typed-dimension aspect tests of those typed dimensions that use the typed-dimension domain definitions that are related to the equality definition by equality-definition relationships.

The variable $aspectTest:a, when used in the XPath expression contained by an equality definition, is equal to the first fact in the comparison of aspect values and the variable $aspectTest:b, when used in the XPath expression contained by an equality definition, is equal to the second fact in the comparison of aspect values.

Error code xbrlve:multipleTypedDimensionEqualityDefinitions MUST be thrown if a typed-dimension domain definition has more than one equality-definition relationship to an equality definition.

2.1.2.2.1.1 Equality-definition relationships

An equality-definition relationship is a relationship between a typed-dimension domain definition and an equality definition expressed by an XLink arc.

To declare an equality-definition relationship an XLink arc MUST:

have an arcrole value equal to http://xbrl.org/arcrole/2008/equality-definition
have a typed-dimension domain definition at the starting resource of the arc
have an equality definition at the ending resource of the arc

The arcrole value, http://xbrl.org/arcrole/2008/equality-definition, is declared in the normative schema supplied with this specification.

Equality-definition relationships MUST be expressed by generic arcs. Violations of this requirement can be detected by validation against the XBRL Specification [XBRL 2.1].

2.2 Aspect models

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.

An aspect model is a definition of how the information about a fact will be split into separate aspects.

An aspect model identifier is a text string that can be used to identify an aspect model.

All aspect model definitions MUST specify the aspect model identifier the for the aspect model being defined.

All aspect models MUST include the following aspects:

location aspect
concept aspect
entity-identifier aspect
period aspect
unit aspect

All aspect models MUST include sufficient aspects to ensure that all content in both the contexts and units of facts is associated with at least one aspect.

An open context component (OCC), is a segment or scenario.

A segment OCC is the OCC for a segment.

A scenario OCC is the OCC for a scenario.

An OCC aspect, is an aspect with a value that is reported by the content of an OCC that remains after removing all content corresponding to other aspect values.

An OCC value is the value of an OCC aspect.

A segment OCC aspect, is the OCC aspect with a value given by the remainder content of the segment.

A scenario OCC aspect, is the OCC aspect with a value given by the remainder content of the segment.

Because [XBRL 2.1] places so few constraints on the content and meaning of OCCs, all aspect models MUST include two aspects: one segment OCC aspect, and one scenario OCC aspect. Moreover, all aspect model definitions MUST identify their segment OCC aspect and their scenario OCC aspect.

This specification defines two aspect models: the dimensional aspect model and the non-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 dimensional aspect model has an aspect model identifier equal to dimensional.

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, and dimension aspects. The non-dimensional aspect model has an aspect model identifier equal to non-dimensional.

The complete segment aspect is the segment OCC aspect for the non-dimensional aspect model. The complete scenario aspect is the scenario OCC aspect for the non-dimensional aspect model.

The non-XDT segment aspect is the segment OCC aspect for the dimensional aspect model. The non-XDT scenario aspect is the scenario OCC aspect for the dimensional aspect model.

The dimensional and non-dimensional aspect models are summarised in Table 2.

Table 2: Aspect inclusion in aspects models

Aspect	Aspect model
	Dimensional	Non-dimensional
Location	include	include
Concept	include	include
Entity identifier	include	include
Period	include	include
Unit	include	include
Complete segment	exclude	include
Complete scenario	exclude	include
Non-XDT segment	include	exclude
Non-XDT scenario	include	exclude
Dimension	include	exclude

3 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.

3.1 Custom function signatures

A custom function is an XPath function that is not defined in the XPath and XQuery Functions Specification [XPATH AND XQUERY 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 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.

The implementation of a custom function is outside of the scope of this specification.

3.2 Parameters

A parameter is declared by a <variable:parameter> element and can be given default values, specified as part of their declaration, or values that are supplied by processing software.

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 variable 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 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.

Otherwise, 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 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.

Unlike parameters in the XSLT 2.0 specification [XSLT 2.0], the parameters defined in this specification cannot contain sequence constructors.

3.3 General variables

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.

The @bindAsSequence attribute on general variables has implications for their evaluation as set out in Section 4.1

3.4 XBRL fact variables

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 @bindAsSequence attribute on fact variables has implications for their evaluation, as set out in Section 4.1

The optional @fallbackValue attribute on fact variables also has implications for their evaluation, as set out in Section 4.2.

The XPath expression implied by a fact variable depends on its filters.

If the @nils attribute on a fact variable is omitted or is equal to false then the XPath expression implied by a fact variable begins with:

xfi:non-nil-facts-in-instance()

If the @nils attribute on a fact variable is equal to true then 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 or the xfi:non-nil-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.

3.4.1 Filters

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 item.

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 item, results in an effective Boolean value of true.

A filter can cover an aspect if it selects facts using that aspect as a selection criterion.

An uncovered aspect of a fact variable is an aspect that is not covered by any of the filters that are being used to construct the XPath expression implied by the variable.

Every 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.

Filters MAY be associated with fact variables in the following three ways:

Explicitly, via variable-filter relationships (See Section 3.4.1.1)
Explicitly, via variable-set-filter relationships (See Section 3.5.2)
Implicitly (See Section 3.5.3)

All methods of associating filters with fact variables identify whether the filter covers aspects and whether the fact variable uses the filter or the filter complement.

3.4.1.1 Variable-filter relationships

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:

have an arcrole value equal to http://xbrl.org/arcrole/2008/variable-filter
have a fact variable at the starting resource of the arc
have a filter at the ending resource of the arc

The arcrole value, http://xbrl.org/arcrole/2008/variable-filter, is declared in the normative schema supplied with this specification.

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 complemented variable-filter relationship is a variable-filter relationship that is expressed by an arc with a @complement attribute that has a value of true.

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.

A covering variable-filter relationship is a variable-filter relationship that is expressed by an arc with a @cover attribute that has a value of true.

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.

3.4.1.1.1 Variable-filter arcs

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.

3.5 Variable sets

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.

A variable set is a set of fact and/or general variables that are able to reference each-other using XPath variable references.

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.

Variable sets identify their aspect model using their @aspectModel attribute. The value of the @aspectModel attribute on a variable-set resource is the aspect model identifier of 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.

Error code xbrlve:unknownAspectModel MUST be thrown if the processing software does not recognise the aspect model identified by the value of an @aspectModel attribute.

Error code xbrlve:duplicateVariableNames MUST be thrown if two or more variables or parameters in the same variable set have the same name.

Error code xbrlve:filterAspectModelMismatch MUST be thrown if the processing software encounters a variable set in which one or more of the fact variables in the variable set has a filter that can cover an aspect that is not defined in the aspect model of the variable set.

3.5.1 Variable-set relationships

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:

have an arcrole value equal to http://xbrl.org/arcrole/2008/variable-set
have a variable-set resource at the starting resource of the arc
have a parameter or a fact variable or a general variable at the ending resource of the arc

The arcrole value, http://xbrl.org/arcrole/2008/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 QName of a variable or parameter is specified by the @name attribute on the variable arc connecting it to a variable set. If the QName has no namespace prefix, then it has no namespace, regardless of the default namespace for the containing element. Otherwise, the QName is resolved in accordance with [XML NAMES] using the namespace declarations that are in scope for the variable arc containing the @name attribute. ^{[
2
]}

When evaluating the variables in a variable-set, XPath variable references with this QName are references to the variable or parameter. Note that, for parameters, this QName MAY differ from the QName given in the parameter declaration.

3.5.1.1 Variable arcs

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.

3.5.2 Variable-set-filter relationships

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:

have an arcrole value equal to http://xbrl.org/arcrole/2008/variable-set-filter
have an XLink resource that defines a variable set at the starting resource of the arc
have a filter at the ending resource of the arc

The arcrole value, http://xbrl.org/arcrole/2008/variable-set-filter, is declared in the normative schema supplied with this specification.

Variable-set-filter relationships MUST be expressed by variable-set 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.

A filter that is associated with a fact variable by a variable-set-filter relationship is referred to as a group filter.

A complemented variable-set-filter relationship is a variable-set-filter relationship that is expressed by an arc with a @complement attribute that has a value of true.

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 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.

3.5.2.1 Variable-set filter arcs

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.

3.5.3 Implicit filters

Fact variables in a variable set MAY be associated with implicit filters, defined in the Implicit filters specification [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.

A variable set uses implicit filtering if its @implicitFiltering attribute equals true and it does not use implicit filtering if the @implicitFiltering attribute equals false.

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.

3.5.4 Preconditions

Variable set resources MAY be associated with preconditions by variable-set-precondition relationships. Preconditions define conditions that must be satisfied 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.

3.5.4.1 Variable-set-precondition relationships

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:

have an arcrole value equal to http://xbrl.org/arcrole/2008/variable-set-precondition
have a variable-set resource at the starting resource of the arc
have a precondition at the ending resource of the arc

The arcrole value, http://xbrl.org/arcrole/2008/variable-set-precondition, is declared in the normative schema supplied with this specification.

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].

4 Variable evaluation

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.

Except for the following two special cases, 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.

The special cases are:

If there are no variables in the variable set, then the variable set is deemed to have been evaluated if all preconditions associated with the variable set are satisfied.^{[
3
]}
If a variable set contains fact variables but all of the fact variables in it evaluate to fallback values, then the variable set is not deemed to have been evaluated.
If a variable set contains a fact variable, V, that has evaluated to a fallback value but that fact variable could have evaluated to a non-fallback value without forcing a change in the value of any one of the other fact variables in the variable set that has not evaluated to a fallback value and that does not have a dependency on fact variable V.

Error code xbrlve:ambiguousAspects MUST be thrown if the target XBRL instance contains a fact for which the aspects cannot be uniquely determined, given the aspect model of the variable set to be evaluated.

Error code xbrlve:ambiguousAspectValues MUST be thrown if the target XBRL instance contains a fact for which the values of one or more of its aspects cannot be uniquely determined, given the aspect model of the variable set to be evaluated.

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 sequences of the same length and for each item in one of the sequences, there is an identical item in the other sequence.

All variable evaluations begin with evaluation of the XPath expression implied by the variable.

An XPath expression has a variable dependency if the expression includes an XPath variable reference.

Applications are responsible for determining an evaluation order for variables in a variable set that ensures that the variable dependencies for each variable in the variable set are to variables that have already been evaluated.

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 code xbrlve:cyclicDependencies MUST be thrown if there are circular dependencies in the references to variables in a variable set.

Example 4: Circular variable references

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 general variable or a fact variable.

4.1 Binding as a sequence

A variable binds as a sequence if it has a @bindAsSequence attribute equal to true. Otherwise, it does not bind as a sequence.

The result of a variable evaluation depends upon whether the variable binds as a sequence.

For a general variable that does not bind as a sequence, the result of its evaluation is any one of the items in its source sequence. For a general variable that does bind as a sequence, the result of its evaluation is the source sequence.

For a fact variable, if the source sequence is not empty and if it does not bind as a sequence, then the result of its evaluation is either its fallback value or any one of the facts in its source sequence.

For a fact variable, if the source sequence is not empty and if it does bind as a sequence, then the result of its evaluation is either its fallback value or any sequence of facts in the source sequence that meets the following conditions:

All facts in the evaluation result are also in the source sequence of the fact variable.
No fact occurs more than once in the evaluation result.
Each uncovered aspect of each fact in the evaluation result sequence MUST have an equivalent aspect value for all of the other facts in the evaluation result.
All facts in the evaluation result MUST have the same set of aspects.
If the @matches attribute on the fact variable is omitted or is equal to false then the evaluation result MUST NOT contain any aspect-matched facts.
The evaluation result MUST include all possible facts from the source sequence that meet the previous conditions.

The order of the facts in the evaluation result for fact variables 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.

4.2 Binding to an empty sequence

The previous section addressed the evaluation of general variables and the evaluation of fact variables when the source sequence is not empty. This section addresses the evaluation of fact variables when the source sequence is empty.

If the source sequence is empty, then the result of a fact variable evaluation also depends on the @fallbackValue attribute on the fact variable.

A fact variable can bind to an empty sequence if it has a @fallbackValue attribute. 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 is determined by the @fallbackValue attribute. Specifically, 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. The parameters in the variable set are in context for the evaluation of the XPath expression in the @fallbackValue attribute but fact and general variables in the variable set are not and so cannot be referenced from within that XPath expression.

A fallback value is the value of a fact variable that has been determined on the basis of the content of the @fallbackValue attribute.

A non-fallback value is the value of a fact variable that has been determined on the basis of its source sequence rather than the content of the @fallbackValue attribute.

Appendix A Normative schema

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:

While any schema is the most current RECOMMENDED version and until it is superseded by any additional errata corrections a non-normative version will reside on the web in the directory http://www.xbrl.org/2008/ - 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/2008/variable.xsd.
A non-normative version of each schema as corrected by any update to the RECOMMENDATION will be archived in perpetuity on the web in a directory that will contain a unique identification indicating the date of the update.

<link:definition>

typed-dimension domain definition has equality definition

</link:definition>

<link:usedOn>

gen:arc

</link:usedOn>

</link:arcroleType>

<link:definition>

variable set has variable

</link:definition>

<link:usedOn>

variable:variableArc

</link:usedOn>

</link:arcroleType>

<link:definition>

variable has filter

</link:definition>

<link:usedOn>

variable:variableFilterArc

</link:usedOn>

</link:arcroleType>

<link:definition>

fact variables in variable set have filter

</link:definition>

<link:usedOn>

variable:variableSetFilterArc

</link:usedOn>

</link:arcroleType>

<link:definition>

variable set has precondition

</link:definition>

<link:usedOn>

gen:arc

</link:usedOn>

</link:arcroleType>

</appinfo>

</annotation>

</restriction>

</simpleType>

</restriction>

</simpleType>

</attributeGroup>

</extension>

</complexContent>

</complexType>

</complexType>

</element>

</sequence>

</extension>

</complexContent>

</complexType>

</element>

</extension>

</complexContent>

</complexType>

</element>

</extension>

</complexContent>

</complexType>

</element>

</extension>

</complexContent>

</complexType>

</extension>

</complexContent>

</complexType>

</element>

</extension>

</complexContent>

</complexType>

</element>

</extension>

</complexContent>

</complexType>

</element>

</extension>

</complexContent>

</complexType>

</element>

</extension>

</complexContent>

</complexType>

</element>

</extension>

</complexContent>

</complexType>

</element>

</schema>

Appendix B References

DIMENSIONS: XBRL International Inc.. "XBRL Dimensions 1.0"
Ignacio Hernández-Ros, and Hugh Wallis.
(See http://www.xbrl.org/Specification/XDT-REC-2006-09-18.htm)
GENERIC LINKS: XBRL International Inc.. "XBRL Generic Links 1.0"
Mark Goodhand, Ignacio Hernández-Ros, and Geoff Shuetrim.
(See ../../gnl/CR-2008-12-31/gnl-CR-2008-12-31.html)
IETF RFC 2119: IETF (Internet Engineering Task Force). "RFC 2119: Key words for use in RFCs to Indicate Requirement Levels"
Scott Bradner.
(See http://www.ietf.org/rfc/rfc2119.txt)
IMPLICIT FILTERS: XBRL International Inc.. "XBRL Implicit Filters 1.0"
Phillip Engel, Herm Fischer, Victor Morilla, Jim Richards, Geoff Shuetrim, David vun Kannon, and Hugh Wallis.
(See ../../implicitFilters/CR-2008-12-31/implicitFilters-CR-2008-12-31.html)
XBRL 2.1: XBRL International Inc.. "Extensible Business Reporting Language (XBRL) 2.1"
Phillip Engel, Walter Hamscher, Geoff Shuetrim, David vun Kannon, and Hugh Wallis.
(See http://www.xbrl.org/Specification/XBRL-RECOMMENDATION-2003-12-31+Corrected-Errata-2008-07-02.htm)
XDM: W3C (World Wide Web Consortium). "XQuery 1.0 and XPath 2.0 Data Model (XDM)"
Mary Fernández, Ashok Malhotra, Jonathan Marsh, Marton Nagy, and Norman Walsh.
(See http://www.w3.org/TR/xpath-datamodel/)
XLINK: W3C (World Wide Web Consortium). "XML Linking Language (XLink) Version 1.0"
Steve DeRose, Eve Maler, and David Orchard.
(See http://www.w3.org/TR/xlink/)
XML: W3C (World Wide Web Consortium). "Extensible Markup Language (XML) 1.0 (Fourth Edition)"
Tim Bray, Jean Paoli, C. M. Sperberg-McQueen, Eve Maler, and François Yergeau.
(See http://www.w3.org/TR/REC-xml/)
XML NAMES: W3C (World Wide Web Consortium). "Namespaces in XML 1.0 (Second Edition)"
Tim Bray, Dave Hollander, Andrew Layman, and Richard Tobin.
(See http://www.w3.org/TR/REC-xml-names/)
XML SCHEMA STRUCTURES: W3C (World Wide Web Consortium). "XML Schema Part 1: Structures Second Edition"
Henry S. Thompson, David Beech, Murray Maloney, and Noah Mendelsohn.
(See http://www.w3.org/TR/xmlschema-1/)
XPATH 2.0: W3C (World Wide Web Consortium). "XML Path Language (XPath) 2.0"
Anders Berglund, Scott Boag, Don Chamberlin, Mary F. Fernández, Michael Kay, Jonathan Robie, and Jérôme Siméon.
(See http://www.w3.org/TR/xpath20/)
XPATH AND XQUERY FUNCTIONS: W3C (World Wide Web Consortium). "XQuery 1.0 and XPath 2.0 Functions and Operators"
Ashok Malhotra, Jim Melton, and Norman Walsh.
(See http://www.w3.org/TR/xpath-functions/)
XQUERY 1.0: W3C (World Wide Web Consortium). "XQuery 1.0: An XML Query Language"
Scott Boag, Don Chamberlin, Mary F. Fernández, Daniela Florescu, Jonathan Robie, and Jérôme Siméon.
(See http://www.w3.org/TR/xquery/)
XSLT 2.0: W3C (World Wide Web Consortium). "XSL Transformations (XSLT) Version 2.0"
Michael Kay.
(See http://www.w3.org/TR/xslt20/)

Appendix C Intellectual property status (non-normative)

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).

Appendix D Acknowledgements (non-normative)

This document could not have been written without the contributions of many people including the participants in the Formula Working Group.

Appendix E Document history (non-normative)

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 `@bindEmpty` attribute and the `@bindAsSequence` attribute from the formula arc to the general and fact variable resources. This means that classification of variables as being able to bind to empty sequences and being able to bind to non-singleton sequences is within scope for the variable specification. This is important because such classification is useful outside the scope of formulae. For example, it will be useful in the XBRL instance validation usage pattern where variables are used directly rather than as components of a formula for testing the existence or otherwise of certain classes of facts in XBRL instances.
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 `@fallbackValue` attribute for variables to provide a value for variables that evaluate to an empty sequence. 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 `@name` attribute, as suggested by Masatomo Goto. 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 `@xlink:role` attribute on the variable set resource but are using an `@aspectModel` attribute instead. This allows us to avoid needing to declare a role that then forces us to define what elements it is used on. It also allows us to separate the specification of which aspect model to use from the specification of whether to use implicit filtering when evaluating the variables in the variable set. 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 `<xl:resource>` element which allows mixed content but all resources did not allow mixed content. This has been fixed by not having the resources in the normative schemas in the substitution group for the `<xl:resource>` element.
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 `@required` attribute to a Boolean data type instead of a `yes`/`no` enumeration. This is more in line with the syntax of the rest of the specification, but it now deviates from the syntax of the `@required` attribute on parameters in XSLT 2.0.
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.
09 January 2008	Geoff Shuetrim	Removed the regular-expression constraint on the `variable:expression` data type in the normative schema to support greater flexibility in formatting of regular expressions. Ideally, a more flexible regular expression constraint will be re-introduced.
20 January 2008	Geoff Shuetrim	Inserted a new regular expression constraint on the `variable:expression` data type in the normative schema based on the suggestion from Cliff Binstock. This achieves the objectives of the constraint in the third Public Working Draft without the unintended consequences. From feedback by Pablo Navarro Salvador: fixed up the erroneous reference to a `<formula:parameter>` instead of a `<variable:parameter>`; and fixed up the grammatical error "the how the" in the section on aspect models.
29 January 2008	Geoff Shuetrim	Removed the obsolete order attribute from the `<variable:input>` element in custom function declarations. Input parameter ordering is expressed by the document order of the `<variable:input>` elements in a custom function declaration, as documented in the specification text.
30 January 2008	Geoff Shuetrim	Relaxed the requirement that data types for custom function signatures be expressed as QNames given the need to deal in sequences.
31 January 2008	Geoff Shuetrim	Standardised the format of the hyperlinks to the normative schema. Corrected an erroneous statement that variable-set filter relationships have to be expressed by filter arcs instead of variable-set filter arcs.
02 February 2008	Geoff Shuetrim	The `@bindAsSequence` attribute for general variables is back by popular demand after being eliminated during the reworking of the second public working draft to produce the third public working draft. It was eliminated because of the potential for the one formula, with the one set of evaluations for fact variables, to produce quite different output facts if general variables do not get forced to always bind to sequences. A number of sensible use cases that could be simplified by general variables that do bind to individual items in the source sequence rather than the source sequence itself have motivated the return of the attribute for general variables. Added paragraphs to the sections on general variables and fact variables pointing to the explanations of the attributes impacting on how they bind when they are evaluated depending on the `@bindAsSequence` and `@bindEmpty` attributes. These are intended only to ease navigation of the specification.
05 February 2008	Geoff Shuetrim	Modified the XBRL functions used to test matches of segment and scenario dimensions to eliminate the need to directly obtain the nodes representing dimension values for the purposes of testing s-equal2 conditions. This is necessary given that some dimensions can have default values.
12 February 2008	Geoff Shuetrim	Fixed the spacing in the definition of binding as a sequence.
16 February 2008	Geoff Shuetrim	Added a missing reference for XQuery. Corrected reference to Pablo in the revision history.
26 February 2008	Geoff Shuetrim	Removed the erroneous `or` from the end of the unit aspect test. This error was introduced on 29 November 2007. Bought the names of the XBRL functions used for the dimension aspect tests into line with the function naming conventions used in the function registry.
07 March 2008	Geoff Shuetrim	Defined a default function namespace.
08 March 2008	Geoff Shuetrim	Changed any to all to improve the clarity of the requirement that aspect models include aspects for whatever content is permitted in segments and scenarios. Added a table summarising the aspects in the dimensional and non-dimensional aspect models. Eliminated the redundant `@bindEmpty` attribute and simplified the specification explanation for how fact variables evaluate when their source sequences are empty. Fixed grammatical errors in the definition of a precondition. These changes were suggested by Paul Bull.
10 March 2008	Geoff Shuetrim	Grouped the various paragraphs contributing to the definition of a variable set evaluation so that the complete definition is available in a single place rather than having to be pieced together from different sections of the specification. Clarified the reference to XSLT 2.0 sequence constructors as suggested by Phillip Engel.
13 March 2008	Geoff Shuetrim	Created links from terms used in the introduction. Added explanation of the function of parameters to the parameter definition. Clarified motivation for XBRL custom functions by referencing the need to draw on information from the DTS supporting XBRL instances. Flagged that the implementation of custom functions is outside the scope of the variable specification. Changed the reference to a formula processor to a reference to a variable processor. Clarified the wording in relation to sourcing of values for mandatory and non-mandatory parameters. Rearranged sections to minimise references to terms not already defined. Simplified the definitions of the dimensional and non-dimensional aspect models to avoid relying on references to the `@aspectModel` attribute on variable sets. Defined the unique text string identifier for an aspect model. Clarified that aspect tests are equivalence relations. Relaxed the requirement on the aspects that had to be included in all aspect models. Added an explicit reference to the implicit filtering specification. These changes were in response to feedback by CompSci Resources.
20 March 2008	Geoff Shuetrim	Fixed broken hyperlinks.
14 April 2008	Geoff Shuetrim	Changed `xfi:scenario-remainder`, `xfi:segment-remainder`, `xfi:facts-scenario-dimension-s-equal2` and `xfi:facts-segment-dimension-s-equal2` function names to conform with the function registry as suggested by Takahide Muramoto.
17 April 2008	Geoff Shuetrim	Clarified that a variable set with no preconditions and no variables can be deemed to have evaluated once, as suggested by Herm Fischer.
23 April 2008	Geoff Shuetrim	Removed the error code relating to missing implicit filters, as suggested by Herm Fischer, because it would only be relevant in situations where an aspect model has not been adequately specified. Added error ( xbrlve:filterAspectModelMismatch ) that prohibits the usage of explicit filters in a variable set when those explicit filters can cover aspects that are not defined in the aspect model of the variable set in question. This was suggested by Herm Fischer.
12 June 2008	Geoff Shuetrim	Added a new error code that is to be thrown whenever two variables or parameters in the same variable set have the same variable name. This is necessary now that evaluation order is determined based upon dependencies that are reflected in variable names.
17 June 2008	Geoff Shuetrim	Refined the definition of identical fact variable evaluations to handle the case where the fact variable evaluation is the fallback value.
26 June 2008	Geoff Shuetrim	Deleted the sentence requiring that filter complements never cover aspects. Now such filters can cover aspects in the same way that normal filters can. This issue was raised by Victor Morilla. Clarified that variable names with no namespace prefix are not to be resolved using the default namespace for the containing element. This issue was raised by Herm Fischer. Changed the evaluation context for fallback values to ensure that fact and general variables are not able to be referenced by the XPath expressions in `@fallbackValue` attributes. This enables the specification to remain silent on interactions between fallback values and implicit filtering and relative filtering. This issue was raised by Andy Harris.
12 August 2008	Geoff Shuetrim	Corrected the definition of identical fact variable evaluations to handle sequences of atomic values as well as sequences of facts. Modified the definition of variable set evaluations and fact variable evaluations to ensure that application dependent evaluation ordering decisions cannot impact on the set of legal variable set evaluations for a formula and a given target XBRL instance. This modification was suggested by Andy Harris.
13 August 2008	Geoff Shuetrim	Removed un-necessary schema limitations on undirected cycles in relationship networks.
22 August 2008	Geoff Shuetrim	Added the `@nils` attribute to fact variables to ensure that fact variables can determine their own ability to evaluate to nil facts. This change was motivated by feedback from Michele Romanelli. Added the `@duplicates` attribute to fact variables to ensure that fact variables can determine their own ability to evaluate to sequences that include duplicate facts. This change was motivated by feedback from Mark Goodhand.
25 August 2008	Geoff Shuetrim	Added two new error codes: ( xbrlve:ambiguousAspects ) and ( xbrlve:ambiguousAspectValues ) , to cover situations where the aspect model does not match the information in the XBRL instance well enough to uniquely determine the aspects, and the values of those aspects, for all facts in the instance. Simplified the dimensional aspect model to include only dimension aspects rather than segment dimension aspects and scenario dimension aspects. This simplification is now possible because the base specification WG agreed to require that the one dimension not be reported in both the segment and scenario for a given fact. It is also required because the XDT specification does not always associate a dimension value with a segment or a scenario. This is the case for default dimension values for facts reporting values with dimensions that validate against a conjunction of open hypercubes. Without this simplification the new error codes added today would be thrown for such facts. Moved the definition of an OCC and an OCC aspect to the variable specification from the formula specification so that they can be utilised more generally. Modified the definition of an OCC to be more concrete. Added more explicit requirements on aspect model definitions to ensure that they include one segment OCC aspect and one scenario OCC aspect.
26 September 2008	Geoff Shuetrim	Modified the naming of variables and parameters on variable arcs to ensure that variable and parameter QNames could not be inadvertently changed to incorrect values by processing software that is namespace aware but that does not understand the special treatment of XPath 2.0 variables with no namespace. Variable and parameter names are now provided by two attributes, a `@name` name attribute that provides the local name, and, where required, a `@namespace` attribute that provides the namespace. Added a definition of aspect-matched facts to replace the notion of duplicate facts as defined in the XBRL 2.1 specification. This also improves terminology support for the consistency assertions specification. Changed the `@duplicates` attribute to a `@matches` attribute to reflect the change from controlling whether variables that can bind as a sequence can allow duplicate facts in a single evaluation sequence to controlling whether variables that can bind as a sequence can allow aspect-matched facts in a single evaluation sequence.
01 October 2008	Geoff Shuetrim	Modified the syntax for variable and parameter names once more, reverting to a single attribute that specifies a QName but that uses a restriction on the XML Schema Name type rather than an XML Schema QName type. The specification wording then makes explicit how the value of the name attribute on variable arcs is to be resolved, ensuring that any name attribute value without a QName prefix is resolved to a QName with no namespace. This requires resolution of name attribute values with QName prefixes to be resolved in the usual way, using the namespace declarations that are in scope for the containing variable arc. This approach was universally preferred by the UBMatrix and Fujitsu developers participating in the discussion of variable QName resolution issues. Added a new error code to catch situations where the QName for variables on variable arcs cannot be resolved.
24 October 2008	Geoff Shuetrim	Added Section 2.1 to overcome the inherent limitations of the definition of s-equal2 for dimension aspect tests.
29 October 2008	Geoff Shuetrim	Corrected typographic errors in Section 2.1 as suggested by Victor Morilla.
04 November 2008	Geoff Shuetrim	Corrected function signatures in the implied XPath expressions for dimension aspect tests and removed redundant terms in them, as suggested by Takahide Muramoto.
06 November 2008	Geoff Shuetrim	Renamed the `$a` and `$b` variables used in the definitions of aspect tests to be in a namespace defined in this specification to reduce the risk of unintended variable name clashes.
17 November 2008	Geoff Shuetrim	Clarified that ( xbrlve:variableNameResolutionFailure ) is required to be thrown when namespaces cannot be resolved for any attributes that contain fact or general variable QNames. This involved moving the explanation of the error code to the XPath usage section. This change was suggested by Herm Fischer during analysis of conformance suite coverage.
27 November 2008	Geoff Shuetrim	Added a paragraph to Section 1.7 to clarify the purpose behind using the `variable:QName` data type for attributes that contain XPath variable names. This was suggested by Nathan Summers. Added a paragraph to Section 1.7 to be specific that the XQuery/XPath data models used for XPath processing are to be constructed from post XML Schema Validation Infosets. This was a result of feedback from Nathan Summers on the consequences of not being specific in this way.
15 December 2008	Geoff Shuetrim	Updated references to the latest errata-corrected version of the XBRL 2.1 specification.

Appendix F Errata corrections in this document

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 2008. 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.

End Notes

[1]: Note that namespace declarations are not included in the count of attributes.
[2]: Note that the XML Schema type for the @name attribute on variable arcs is not the XML Schema QName data type. This goes some way toward ensuring that the QName value of the@name attribute will not be resolved incorrectly by software that is unaware of this specification, based upon any default namespace declaration in scope for the containing variable arc.
[3]: Thus, if there are no variables in the variable set, and the variable set has no preconditions associated with it, then the variable set can be deemed to have been evaluated.

Variables 1.0

Candidate Recommendation 31 December 2008

Status

Abstract

Table of Contents

Appendices

Tables

Examples

Definitions

Error codes

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

2 Aspects

2.1 Dimension aspect tests

2.1.1 Explicit-dimension aspect tests

2.1.2 Typed-dimension aspect tests

2.1.2.1 Default typed-dimension aspect tests

2.1.2.2 Custom typed-dimension aspect tests

2.1.2.2.1 Equality definitions for typed dimensions

2.1.2.2.1.1 Equality-definition relationships

2.2 Aspect models

3 Syntax

3.1 Custom function signatures

3.2 Parameters

3.3 General variables

3.4 XBRL fact variables

3.4.1 Filters

3.4.1.1 Variable-filter relationships

3.4.1.1.1 Variable-filter arcs

3.5 Variable sets

3.5.1 Variable-set relationships

3.5.1.1 Variable arcs

3.5.2 Variable-set-filter relationships

3.5.2.1 Variable-set filter arcs

3.5.3 Implicit filters

3.5.4 Preconditions

3.5.4.1 Variable-set-precondition relationships

4 Variable evaluation

4.1 Binding as a sequence

4.2 Binding to an empty sequence

Appendix A Normative schema

Appendix B References

Appendix C Intellectual property status (non-normative)

Appendix D Acknowledgements (non-normative)

Appendix E Document history (non-normative)

Appendix F Errata corrections in this document

End Notes