Copyright ©2008 XBRL International Inc., All Rights Reserved.
Circulation of this Candidate Recommendation is unrestricted. This document is normative. Other documents may supersede this document. Recipients are invited to submit comments to formula-feedback@xbrl.org, 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 Variables Specification [VARIABLES]. It defines XML syntax for filters that condition on dimension information, as defined in the XBRL Dimensions Specification [DIMENSIONS], when selecting facts from XBRL instances.
The filters defined in this specification facilitate selection of facts based on dimension information in both the target XBRL instance and in its supporting DTS. Both typed and explicit dimensions can be used to filter facts in the target XBRL instance.
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.6 Namespaces and namespace prefixes
1.7 XPath usage
2 Syntax
2.1 Explicit dimension filter
2.2 Typed dimension filter
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 explicit dimension filters
2 Typed dimension filters
dimension filter
explicit dimension filter
filter dimension
filter linkrole
filter member
filter member set
recognised domain for a dimension
typed dimension filter
This specification is an extension to the XBRL Variables Specification [VARIABLES]. It defines XML syntax [XML] for filters that condition on dimensions [DIMENSIONS] when selecting facts from XBRL instances.
All of the filters defined in this specification are referred to collectively as filter dimensions.
All dimension filters have a <df:dimension> element.
That element specifies both the filter dimension and whether the filter can cover a
segment dimension aspect or
scenario dimension aspect.
If the <df:dimension> element contains a @contextElement attribute equal to
segment then the dimension filter can cover the segment dimension aspect for the dimension
identified by the <df:dimension> element.
If the <df:dimension> element contains a @contextElement attribute equal to
scenario then the dimension filter can cover the scenario dimension aspect for the
filter dimension.
This specification is a member of a suite of similar specifications that define specific types of criteria that can be used to select facts from XBRL instances. It enhances the fact selection capabilities of the XBRL Variables Specification [VARIABLES].
This specification depends upon the XBRL Specification [XBRL 2.1], the XBRL Variables Specification [VARIABLES], and the XBRL Dimensions Specification [DIMENSIONS]. In the event of any conflicts between this specification and the specifications upon which it depends, this specification does not prevail.
The official language of XBRL International's own work products is English and the preferred spelling convention is UK English.
This specification is consistent with the definitions of any of the terms defined in specifications that it depends on.
Documentation conventions follow those set out in the XBRL Variables Specification [VARIABLES].
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 |
|---|---|
df
|
http://xbrl.org/2008/filter/dimension
|
xbrldfe
|
http://xbrl.org/2008/filter/dimension/error
|
eg
|
http://example.com/
|
fn
|
http://www.w3.org/2005/xpath-functions
|
link
|
http://www.xbrl.org/2003/linkbase
|
xbrli
|
http://www.xbrl.org/2003/instance
|
xfi
|
http://www.xbrl.org/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
|
gen
|
http://xbrl.org/2008/generic
|
variable
|
http://xbrl.org/2008/variable
|
iso4217
|
http://www.xbrl.org/2003/iso4217
|
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.
An explicit dimension filter is declared by
a <df:explicitDimension> element.
The syntax for the
<df:explicitDimension>
element is defined by the normative schema supplied with this specification.
The explicit dimension filter can be used to match facts that report any one of a specified set of domain members as the value of an explicit dimension.
The XPath expression implied by a explicit dimension filter is
determined by its <df:dimension> element,
its <df:member> element, and
its <df:linkrole> element.
A filter linkrole is the value of the <df:linkrole> child
element in an explicit dimension filter.
The filter linkrole is used as the #linkrole value in the
implied XPath expressions below. It serves to identify different domains
that have been defined for the one dimension.
A recognised domain for a dimension
is the set of domain members allowed as values for that dimension by
consecutive relationships
that include a
has-hypercube relationship
expressed by an arc in an extended link with an @xlink:role
attribute that is equal to the
filter linkrole.
A fact is only matched by a explicit dimension filter if it has a value for its filter dimension that is in the recognised domain for the filter dimension.
In the implied XPath expressions below, a value needs to be determined for #dimension.
If the <df:dimension> element has a <df:qnameExpression> child element,
then #dimension is the QName returned by evaluating the
XPath expression contained by the <df:qnameExpression> element.
If the <df:dimension> element has a child <df:qname>
element, then that <df:qname> element contains a QName.
#dimension is then fn:QName(#namespace,#name)) where
#namespace is the namespace of that QName value
and #name is the local name of that QName value.
In the implied XPath expressions below, a #member value needs to be determined
for each <df:member> child element of the explicit dimension filter.
If the <df:member> element has a <df:qnameExpression> child element,
then #member is the QName returned by evaluating the
XPath expression contained by the <df:qnameExpression> element.
If the <df:member> element has a child <df:qname>
element, then that <df:qname> element contains a QName.
#member is then fn:QName(#namespace,#name)) where
#namespace is the namespace of that QName value
and #name is the local name of that QName value.
Otherwise, the <df:member> element has a child <df:variable>
element and #member is the QName of the member that is the value
of the filter dimension for fact bound to the
variable named by the QName value of the <df:variable> element.
If the explicit dimension filter has no filter members
then all domain members in the recognised domain
for the filter dimension meet the filter criteria. The implied XPath expression is then
that specified in the following table. It depends upon the value of the
@contextElement attribute on the filter's <df:dimension> child element.
@contextElement attribute value |
Implied XPath expression |
|---|---|
segment
|
some $member in xfi:concept-explicit-segment-dimension-values(fn:node-name(.),#dimension,#linkrole),
$value in xfi:fact-explicit-segment-dimension-value(.,#dimension)
satisfies ($value eq $member)
|
scenario
|
some $member in xfi:concept-explicit-scenario-dimension-values(fn:node-name(.),#dimension,#linkrole),
$value in xfi:fact-explicit-scenario-dimension-value(.,#dimension)
satisfies ($value eq $member)
|
Otherwise the implied XPath expression is constructed by combining, using the
XPath or operator, a set of terms, one for
filter member
in the explicit dimension filter.
Each filter member in the explicit dimension filter implies a set of domain members that are allowed as values of the filter dimension.
Error code xbrldfe:invalidDomainMember MUST be thrown if the domain member specified by a filter member is not part of the recognised domain for the filter dimension.
Which domain members are in a filter member set depends upon the value
of the @axis attribute on the filter member defining the set.
If the @axis attribute on a filter member equals
self, then the filter member set contains the specified filter member
if it is in the recognised domain for the filter dimension and is empty otherwise.
If the @axis attribute on a filter member equals child,
then the filter member set includes those members in the recognised
domain for the filter dimension that are children of
the filter member in a network of domain-member relationships that is included in the
consecutive relationships identified by the linkrole value.
If the @axis attribute on a filter member equals child-or-self,
then the filter member set includes those members in the recognised
domain for the filter dimension that are either the filter member itself or are children of
the filter member in a network of domain-member relationships that is included in the
consecutive relationships identified by the linkrole value.
If the @axis attribute on a filter member equals descendant,
then the filter member set includes those members in the recognised
domain for the filter dimension that are descendants of
the filter member in a network of domain-member relationships that is included in the
consecutive relationships identified by the linkrole value.
If the @axis attribute on a filter member equals descendant-or-self,
then the filter member set includes those members in the recognised
domain for the filter dimension that are either the filter member itself or are descendants of
the filter member in a network of domain-member relationships that is included in the
consecutive relationships identified by the linkrole value.
The term in the implied XPath expression, for each filter member is given in the table below. It
depends upon the value of the @contextElement attribute
on the filter's <df:dimension> child element.
@contextElement attribute value |
Implied XPath expression |
|---|---|
segment
|
some $member in xfi:concept-select-explicit-segment-dimension-values(fn:node-name(),#dimension,#linkrole,#member,#axis),
$value in xfi:fact-explicit-segment-dimension-value(.,#dimension)
satisfies ($value eq $member)
|
scenario
|
some $member in xfi:concept-select-explicit-scenario-dimension-values(fn:node-name(),#dimension,#linkrole,#member,#axis),
$value in xfi:fact-explicit-scenario-dimension-value(.,#dimension)
satisfies ($value eq $member)
|
where #axis is equal to the value of the @axis attribute on the filter member.
| Filter dimension | Context element | Filter member 1 |
@axis
|
Selection criteria |
|---|---|---|---|---|
eg:region
|
segment
|
None |
Facts must report a value for the
eg:region dimension that are
identified as domain members for that dimension.
|
|
eg:region
|
segment
|
eg:australasia
|
self
|
Facts must report a value for the
eg:regiondimension that is
the domain member eg:australasia.
|
eg:region
|
segment
|
eg:australasia
|
child
|
Facts must report a value for the
eg:regiondimension that is
one of the domain members with a
domain member relationship from
the domain member eg:australasia.
|
eg:region
|
segment
|
eg:australasia
|
descendant
|
Facts must report a value for the
eg:regiondimension that is
a descendent of the eg:australasia
domain member in a domain-member network.
|
eg:region
|
segment
|
eg:australasia
|
descendant-or-self
|
Facts must report a value for the
eg:regiondimension that is
a descendent of the eg:australasia
domain member in a domain-member network or that
is eg:australasia.
|
1. This example presumes that all members of the dimension are recognised members of the dimension being filtered.
A typed dimension filter is declared by a <df:typedDimension>
element.
The syntax for the <df:typedDimension>
element is defined by the normative schema supplied with this specification.
The typed dimension filter can be used to match facts based upon the value for a typed dimension.
If the typed dimension filter does not contain a
@test attribute, then its implied XPath
expression is specified in the following table.
It depends upon the value of the
@contextElement attribute on the
filter's <df:dimension> child element.
@contextElement attribute value |
Implied XPath expression |
|---|---|
segment
|
xfi:concept-has-segment-dimension(fn:node-name(.),#dimension)
|
scenario
|
xfi:concept-has-scenario-dimension(fn:node-name(.),#dimension)
|
where #dimension is determined as specified
for explicit dimension filters.
If the typed dimension filter does contain a
@test attribute, then its implied XPath
expression is given in the table below.
It depends upon the value of the
@contextElement attribute on the
filter's <df:dimension> child element.
@contextElement attribute value |
Implied XPath expression |
|---|---|
segment
|
xfi:concept-has-segment-dimension(fn:node-name(.),#dimension) and
xfi:fact-typed-segment-dimension-value(.,#dimension)[#test]
|
scenario
|
xfi:concept-has-scenario-dimension(fn:node-name(.),#dimension) and
xfi:fact-typed-scenario-dimension-value(.,#dimension)[#test]
|
where #dimension is determined as specified
for explicit dimension filters and #test is
the value of the @test attribute on the typed
dimension filter.
The implied XPath expression evaluates to true
for a fact if and only if:
@df:dimension element,
and
@test attribute.
| Dimension QName | Context element |
@test
|
Selection criteria |
|---|---|---|---|
eg:altitude
|
segment
|
xs:boolean('true')
|
Facts must be reported with a value
specified for dimension eg:altitude
|
eg:altitude
|
segment
|
eg:height > 0
|
Facts must be reported with a value
specified for dimension eg:altitude
that is the <eg:height> element with
a value that is greater than zero.
|
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/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/dimension-filter.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 |
|---|---|---|
| 23 April 2007 | Geoff Shuetrim |
First internal working draft created, drawing on the use cases provided by Victor Morilla. |
| 03 May 2007 | Geoff Shuetrim |
Incorporated feedback on the implied XPath expression designs from Victor Morilla. |
| 08 May 2007 | Geoff Shuetrim |
Added clarification about the fact aspect covered by the filters defined in this specification. |
| 18 May 2007 | Geoff Shuetrim |
Modified the dimension-member filter to include the inclusive
Boolean attribute and to cover the case where the |
| 29 May 2007 | Geoff Shuetrim |
Changed the target namespace of the normative schema again. Made the QName specification capable of covering static and dynamic QNames. |
| 04 June 2007 | Geoff Shuetrim |
Simplified the implied XPath expression for filters on typed dimensions. |
| 11 June 2007 | Geoff Shuetrim |
Clarified the explanation of the functions required to support the implied XPath expression for the explicit-dimension filter. |
| 25 June 2007 | Geoff Shuetrim |
Modified the information about implicit filter implications of dimension filters to allow for implicit filtering at the individual dimension level. |
| 24 July 2007 | Hugh Wallis |
Edited for public working draft publication. |
| 05 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. Removed the erroneous reference to the
Eliminated default values for attribute values on the dimension member filter. Modified the schema to create a single content model for all QName identifiers. |
| 06 November 2007 | Geoff Shuetrim |
Added the arcrole declaration for the filter-member arcrole to the normative schema for dimension filters. This forces filter-member relationships to be expressed by generic arcs. |
| 12 November 2007 | Geoff Shuetrim |
Linked all of the external terminology references back to bibliographic citations. |
| 27 November 2007 | Jim Richards |
Updated the abstract to include a reference to the Varaibles Spec. Made some minor grammatical changes. |
| 30 November 2007 | Geoff Shuetrim |
Added examples. |
| 06 December 2007 | Geoff Shuetrim |
Added a |
| 20 January 2008 | Geoff Shuetrim |
Made hyperlinks to the normative schema consistent throughout the document. |
| 23 January 2008 | Geoff Shuetrim |
Corrected the reference to a domain member filter instead of a dimension member filter in the definition of a recognised member of a dimension. Corrected the definition of the a recognised member of a dimension to include all domain members in a hierarchy of domain-member relationships rather than just those domain members with a direct domain-member relationship to the dimension.
Corrected the obsolete reference to a As requested by Herm Fischer, the term "associated with" has been eliminated from the introduction because it was too loose. In its place is an explanation of the connection between dimensions and the segments and scenarios used to report them, along with sentences capturing the implications of that connection for the type of dimension aspects that can be covered by the filters in this specification. |
| 24 January 2008 | Geoff Shuetrim |
Made the required |
| 30 January 2008 | Geoff Shuetrim |
Responded to feedback from Herm Fischer and Victor Morilla to simplify the handling of filters that condition on the values of explicit dimensions. Specifically: Removed the existing explicit dimension filter and its reliance on XLink relationships to determine the members being selected by the dimension filtering. Modified the dimensionMember filter to allow dimension member filters to nominate just the identified member rather than the some set of members with domain-member XLink relationships to the identified member. This does not limit the existing ability to nominate such sets of members, however. Change the name of the existing dimension member filter to explicit dimension filter given that it is now the only explicit dimension filter. Simplified the syntax required to identify a dimension member value based upon the value of a specified dimension for another fact variable. Reduced the dependency on boolean and filters to achieve complex selections of members for a given dimension. Clarified the function name for the function that returns the recognised member QNames for a specified dimension QName and linkrole QName. Added an extra parameter to the function that returns the recognised member QNames for a specified dimension QName and linkrole QName so that it internalises the complexity of determining whether to include children domain members or descendant domain members in the filter member set for an filter member in an explicit filter. This significantly reduces the complexity of expressing the implied XPath expression for explicit dimension filters. |
| 31 January 2008 | Geoff Shuetrim |
Renamed the As suggested by Herm Fischer, corrected the erroneous association of the filter linkrole with the linkrole on the extended links that contain arcs that express domain-member relationships and instead associated the filter linkrole with the linkrole on the extended links that contain arcs that express all relationships between primary items and hypercubes. This ensures that the filter linkrole is identifying meaningful domains of permitted domain members for the filter dimension on explicit dimension filters.
Aligned the explanation of the Removed the paragraphs on segment and scenario dimension aspects from the introduction as agreed by the working group.
Changed |
| 01 February 2008 | Geoff Shuetrim |
Fixed the typed dimension filter example as suggested by
Masatomo Goto to use |
| 03 February 2008 | Victor Morilla |
Fixed Removed references not cited. |
| 05 February 2008 | Geoff Shuetrim |
Changed the function signature for the xfi:has-dimension function to conform to the other concept property accessor functions. It now takes the concept QName as an argument rather than an XBRL fact. Further simplified the XBRL functions supporting the explicit dimension filter. |
| 25 February 2008 | Geoff Shuetrim |
Restored the sentence to the introduction of the specification defining which aspects can be covered by explicit and typed dimension filters. This drafting regression, introduced on 23 January 2008, was identified by Herm Fischer. |
| 27 February 2008 | Geoff Shuetrim |
Added a |
| 20 March 2008 | Geoff Shuetrim |
Fixed broken hyperlinks. |
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 28 March 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.