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 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 domain
explicit dimension filter
filter dimension
filter member
filter-member arcrole
filter-member axis
filter-member linkrole
filter-member network
filter-member set
filter-member value
typed dimension filter
xbrldfe:ambiguousFilterMemberNetwork
xbrldfe:invalidDomainMember
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.
The filter dimension is the dimension being filtered by a dimension filter.
This dimension is identified by the
<df:dimension>
child element of the
dimension filter.
All dimension filters have a
<df:dimension>
element.
That element specifies 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/2008/function/instance
|
xbrldi
|
http://xbrl.org/2006/xbrldi
|
xbrldt
|
http://xbrl.org/2005/xbrldt
|
xl
|
http://www.xbrl.org/2003/XLink
|
xlink
|
http://www.w3.org/1999/xlink
|
xs
|
http://www.w3.org/2001/XMLSchema
|
xsi
|
http://www.w3.org/2001/XMLSchema-instance
|
gen
|
http://xbrl.org/2008/generic
|
variable
|
http://xbrl.org/2008/variable
|
iso4217
|
http://www.xbrl.org/2003/iso4217
|
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.
An explicit dimension domain is defined in the context of a given DTS as the set of all domain members in the union of all domains of valid members of the filter dimension.
The explicit dimension filter can be used to match facts with any one of the domain members in an explicit dimension domain as the value for that explicit dimension.
The XPath expression implied by a explicit dimension filter is
determined by its
<df:dimension>
element and
its
<df:member>
elements.
A filter member is a
<df:member>
child element
of an explicit dimension filter.
A filter-member value is the domain member, in the explicit dimension domain, with a QName that is specified by a filter member.
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 explicit dimension domain meet the filter criteria. The implied XPath expression is then:
xfi:fact-has-explicit-dimension(.,#dimension)
Otherwise, when the explicit dimension filter does have one or
more filter members, each filter member in the explicit
dimension filter implies a set of domain members that are
allowed as values of the filter dimension.
For such explicit dimension filters,
the implied XPath expression is constructed by combining, using the
XPath or operator, a set of terms, one for
filter member.
The filter-member set for a filter member is the set of domain members that are allowed, by that filter member, as values of the filter dimension.
A filter-member linkrole is the value of the
<df:linkrole>
child
element of a filter member.
A filter-member arcrole is the value of the
<df:arcrole>
child
element of a filter member.
A filter-member axis is the value of the
<df:axis>
child
element of a filter member.
If a filter member does not contain a filter-member linkrole, arcrole and axis, then the only domain member in its filter-member set is the domain member identified by the filter-member value.
The term in the implied XPath expression for that filter member is then:
xfi:fact-has-explicit-dimension-value(.,#dimension,#member)
Otherwise, the domain members in its filter-member set are determined based upon the network of relationships specified by the filter-member linkrole and the filter-member arcrole.
The filter-member network is the network of relationships expressed by arcs with the filter-member arcrole in extended links with the filter-member linkrole.
Error code xbrldfe:invalidDomainMember MUST be thrown if there are no domain members in the filter-member network that belong to the explicit dimension domain for the filter dimension.
Error code xbrldfe:ambiguousFilterMemberNetwork MUST be thrown if the filter-member network is not uniquely determined from the DTS by the filter-member linkrole and filter-member arcrole.
This error could occur for a DTS in which the same combination of linkrole and arcrole values were being used with two different extended link elements or two different arc elements.
If the
@axis attribute on a filter member equals child,
then the filter-member set includes those domain members
in the explicit dimension domain that are targets of relationships
in filter-member network that run from the domain member identified by
the filter-member value.
If the
@axis attribute on a filter member equals child-or-self,
then the filter-member set includes the domain member identified by the filter-member value
and those domain members in the explicit dimension domain that are targets of relationships
in filter-member network that run from the domain member identified by
the filter-member value.
If the
@axis attribute on a filter member equals descendant,
then the filter-member set includes those domain members
in the explicit dimension domain that are descendants,in the filter-member network,
of the domain member identified by the filter-member value.
If the
@axis attribute on a filter member equals descendant-or-self,
then the filter-member set includes includes the domain member identified by the filter-member value
and those domain members in the explicit dimension domain that are descendants,in the filter-member network,
of the domain member identified by the filter-member value.
The term in the implied XPath expression, for each such filter member is:
(
if (xfi:fact-has-explicit-dimension(.,#dimension))
then (
some $member in
xfi:filter-member-network-selection(#dimension,#member,#linkrole,#arcrole,#axis)
satisfies (xfi:fact-explicit-dimension-value(.,#dimension) eq $member)
)
else fn:false()
)
where #axis is equal to the filter-member axis,
#linkrole is equal to the filter-member linkrole
and #arcrole is equal to the filter-member arcrole.
| Filter dimension | Filter member |
@axis
|
Selection criteria |
|---|---|---|---|
eg:region
|
None |
Facts must report a value for the
eg:region dimension that are
in the explicit dimension domain.
|
|
eg:region
|
eg:australasia
|
Facts must report a value for the
eg:regiondimension that is
the domain member eg:australasia.
|
|
eg:region
|
eg:australasia
|
child
|
Facts must report a value for the
eg:regiondimension that is
one of the domain members with a
relationship from
the domain member eg:australasia
that is in the network specified by the
given filter-member linkrole and arcrole.
|
eg:region
|
eg:australasia
|
descendant
|
Facts must report a value for the
eg:regiondimension that is
a descendant of the eg:australasia
domain member in the network specified by the
given filter-member linkrole and arcrole.
|
eg:region
|
eg:australasia
|
descendant-or-self
|
Facts must report a value for the
eg:regiondimension that is
a descendant of the eg:australasia
domain member in the network specified by the
given filter-member linkrole and arcrole or that is
eg:australasia.
|
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 then:
xfi:fact-has-typed-dimension(.,#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 then:
(
xfi:fact-has-typed-dimension(., #dimension) and
xfi:fact-typed-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 |
@test
|
Selection criteria |
|---|---|---|
eg:altitude
|
xs:boolean('true')
|
Facts must be reported with a value
specified for dimension eg:altitude
|
eg:altitude
|
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. |
| 13 June 2008 | Geoff Shuetrim |
Redesigned the implied XPath expressions for the filters so that exceptions are not being thrown because some facts in the instance being filtered are not permitted to have the dimension being used for filtering. The modification ensures that such facts are rejected by the filter rather than causing variable set evaluation to halt. |
| 25 August 2008 | Geoff Shuetrim |
Eliminated the Changed explicit dimension filters to be more flexible with regard to the way that they can utilise networks of relationships between domain members. Instead of working with domains defined in terms of a single conjunction of hypercubes, an explicit dimension filter defines a single comprehensive domain for the filter dimension and then allows filtrations to be expressed based upon selections from that comprehensive domain, using networks of relationships to determine the relevant selections from that comprehensive domain. These changes were motivated by feedback from the COREP and FINREP taxonomies provided by Victor Morilla. They enable various networks of domain-member relationships to be used for some filtering purposes and when those are not sufficient or are not designed in a way that supports the intended filtering, they allow other kinds of more specialised networks to be exploited to determine filtering behaviour. |
| 27 August 2008 | Geoff Shuetrim |
Fixed the various implied XPath expressions to complete adjustments to the specification to reflect the collapsing of segment and scenario dimension aspects into a single dimension aspect. Also modified the implied XPath expressions to reflect the fact that facts can have dimension aspects independent of the hypercube associations of their concept. These corrections were all made on the basis of feedback from Victor Morilla. |
| 02 September 2008 | Geoff Shuetrim |
Split the xfi:fact-has-dimension function to have one function for typed dimensions and one for explicit dimensions. This way, if the wrong kind of dimension is used for a dimension filter, that will trigger a error code when testing for the dimension. |
| 05 September 2008 | Geoff Shuetrim |
Rearranged paragraphs to ensure that the the definitions are provided before they are used in the explicit dimension filter section. |
| 09 September 2008 | Geoff Shuetrim |
Modified the definition of the explicit dimension domain to be expressed in terms of domains of valid members of explicit dimensions, as defined in [DIMENSIONS]. |
| 14 November 2008 | Geoff Shuetrim |
Corrected references to the XDT specification to use the correct ID. |
| 17 November 2008 | Geoff Shuetrim |
Made the |
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.