Copyright ©2007 XBRL International Inc., All Rights Reserved.
Circulation of this Public Working Draft is unrestricted. This document is normative. Other documents may supersede this document. Recipients are invited to submit comments to the authors and contributors, and to submit notification of any relevant patent rights of which they are aware and to provide supporting documentation.
This specification is an extension to the XBRL 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.1.1 Filter-member relationships
2.2 Dimension member filter
2.3 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 Dimension member filters
3 Typed dimension filters
dimension member filter
explicit dimension filter
filter-member relationship
recognised member of a dimension
typed dimension filter
This specification is an extension to the XBRL Variables Specification [VARIABLES]. It defines XML syntax [XML] for filters that can condition on dimensions [DIMENSIONS] when selecting facts from XBRL instances.
All of the filters defined in this specification can
cover segment dimension aspects or
scenario dimension aspects.
If the dimension being filtered is associated with the segment
of the context fact, then the filter can cover the dimension identified
by the filter's @dimension attribute in the segment. If the dimension
being filtered is associated with the scenario of the context fact,
then the filter can cover the dimension identified by the filter's
@dimension attribute in the scenario. All of the filters in this
specification have a @dimension attribute.
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], the XBRL Functions Specification [XBRL FUNCTIONS], 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/2007/filter/dimension
|
xbrldfe
|
http://xbrl.org/2007/filter/dimension/error
|
eg
|
http://example.com/
|
fn
|
http://www.w3.org/2006/xpath-functions
|
link
|
http://www.xbrl.org/2003/linkbase
|
xbrli
|
http://www.xbrl.org/2003/instance
|
xfi
|
http://www.xbrl.org/2005/function/instance
|
xbrldi
|
http://xbrl.org/2006/xbrldi
|
xbrldt
|
http://xbrl.org/2005/xbrldt
|
xl
|
http://www.xbrl.org/2003/XLink
|
xlink
|
http://www.w3.org/1999/xlink
|
xs
|
http://www.w3.org/2001/XMLSchema
|
xsi
|
http://www.w3.org/2001/XMLSchema-instance
|
generic
|
http://xbrl.org/2007/generic
|
variable
|
http://xbrl.org/2007/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 an <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 based upon the value taken by an explicit dimension. Facts that are not reported with the specified explicit dimension do not match the selection criteria of an explicit dimension filter.
The value for the specified explicit dimension may be provided explicitly as part of a fact's context, or it may be implied as a default value for the specified explicit dimension if that dimension is associated with the fact's concept and has a default value.
An explicit dimension filter MAY be related to domain member declarations by Section 2.1.1.
The XPath expression implied by an explicit dimension filter
is determined by its <df:dimension> element and its
filter-member relationships.
If an explicit dimension filter has no filter member relationships, then its implied XPath expression is:
xfi:has-dimension(.,#dimension)
where #dimension is the value of the
<df:qnameExpression>
element if it is contained by the
<df:dimension> element and
#dimension is given by
xs:QName(#namespace, #name) if the
<df:qname> element is contained by the
<df:dimension> element.
#namespace is the namespace for the QName specified
as the content of the <df:qname> element and
#name is the local name for the QName specified as the
content of the <df:qname> element.
If an explicit dimension filter has filter member relationships, the implied XPath expression restricts the allowed values for the specified explicit dimension by being constructed as follows:
For each filter-member relationship from an explicit dimension filter to a domain member declaration, the implied XPath expression will contain a term with the form:
xfi:has-explicit-dimension-value(.,#dimension, #member)
where #dimension is determined as specified above
and #member is the QName of the domain
member declaration.
The complete implied XPath expression is obtained by combining
these terms using the XPath or operator.
| Dimension QName | Domain members with filter-member relationships to the filter | Selection criteria |
|---|---|---|
eg:country
|
none
|
Facts must be reported with a value
specified for dimension eg:country.
No restrictions are imposed on what value
is reported for the dimension.
|
eg:country
|
eg:brazil
|
Facts must be reported with the value eg:brazil
specified for dimension eg:country.
|
eg:country
|
|
Facts must be reported with either eg:brazil
or eg:austria as the value
specified for dimension eg:country.
|
A filter-member relationship is a relationship between an explicit dimension filter and a domain member declaration expressed by an XLink arc.
To declare a filter-member relationship an XLink arc MUST:
http://xbrl.org/arcrole/2007/filter-member
The arcrole value,
http://xbrl.org/arcrole/2007/filter-member,
is declared in
the normative schema
for dimension filters.
Filter-member relationships MUST be expressed by generic arcs . Violations of this requirement can be detected by validation against the XBRL Specification [XBRL 2.1].
A dimension member filter is declared by a <df:dimensionMember>
element.
The syntax for the <df:dimensionMember> element is defined by
the normative schema supplied with
this specification.
The dimension member filter can be used to match facts that report any one of a specified set of domain members for a specified explicit dimension.
The XPath expression implied by a dimension member filter is
determined by its <df:dimension> element,
its <df:member> element,
its <df:linkrole> element,
its @childrenOnly attribute, and its
@inclusive attribute.
A recognised member of a dimension
is defined in the context of a domain member filter.
It is any member with a domain-member relationship to
the dimension that has been expressed by an XLink arc
in an XLink extended link with an @xlink:role
attribute value that is equal to the value of the
<df:linkrole> element on the dimension member
filter.
Facts are only matched by a dimension member filter if they have
a value for the dimension specified by the filter that are recognised
members of the dimension, given the value of the <df:linkrole>
element in the filter.
In the implied XPath expressions below:
#dimension is determined as specified
for explicit dimension filters;
#member is determined from the content of the <df:member> element
in the same manner as #dimension is determined from the content of the
<df:dimension> element; and
#linkrole is the value of the <df:linkrole>
element in the dimension member filter.
If the <df:member> element is omitted, then all recognised members of
the dimension specified by the <df:dimension> element are permitted as
values for the dimension. The implied XPath expression is:
If the <df:member> element is omitted the
dimension member filter's implied XPath expression is:
some $member in xfi:get-member-qnames(.,#dimension,#linkrole),
$value in xfi:dimension-value(.,#dimension)
satisfies ($value=$member)
If the <df:member> element is supplied, it implies a set of
recognised domain members that are allowed as values of the explicit
dimension being filtered.
If the @inclusive attribute has a value of true, then
the allowed values for the explicit dimension
include the domain member specified by the
<df:member> itself. If the @inclusive
attribute has a value of false, then the allowed values for
the explicit dimension exclude the domain member specified by the
<df:member> itself.
[Error:
Error code xbrldfe:invalidDomainMember
MUST
be thrown if the domain member specified by the <df:member> element
is not a recognised member of the dimension being filtered.
]
The dimension member filter's implied XPath expression is:
some $member in xfi:get-child-member-qnames(.,#dimension,#member,#linkrole),
$value in xfi:dimension-value(.,#dimension)
satisfies ($value=$member)
if:
<df:member> element is supplied;@inclusive attribute is false; and@childrenOnly attribute is true.The dimension member filter's implied XPath expression is:
some $member in (#member,xfi:get-child-member-qnames(.,#dimension,#member,#linkrole)),
$value in xfi:dimension-value(.,#dimension)
satisfies ($value=$member)
if:
<df:member> element is supplied;@inclusive attribute is true; and@childrenOnly attribute is true.The dimension member filter's implied XPath expression is:
some $member in xfi:get-descendant-member-qnames(.,#dimension,#member,#linkrole),
$value in xfi:dimension-value(.,#dimension)
satisfies ($value=$member)
if:
<df:member> element is supplied;@inclusive attribute is false; and@childrenOnly attribute is false.The dimension member filter's implied XPath expression is:
some $member in (#member,xfi:get-descendant-member-qnames(.,#dimension,#member,#linkrole)),
$value in xfi:dimension-value(.,#dimension)
satisfies ($value=$member)
if:
<df:member> element is supplied;@inclusive attribute is true; and@childrenOnly attribute is false.| Dimension QName | Member QName 1 |
@childrenOnly
|
@inclusive
|
Selection criteria |
|---|---|---|---|---|
eg:region
|
None |
true
|
false
|
Facts must report a value for the
eg:region dimension that are
identified as domain members for that dimension.
|
eg:region
|
eg:australasia
|
true
|
false
|
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
|
eg:australasia
|
false
|
false
|
Facts must report a value for the
eg:regiondimension that is
a descendent of the eg:australasia
domain member in a domain-member hierarchy.
|
eg:region
|
eg:australasia
|
false
|
true
|
Facts must report a value for the
eg:regiondimension that is
a descendent of the eg:australasia
domain member in a domain-member hierarchy 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:
xfi:has-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:
xfi:has-dimension(.,#dimension) and
xfi: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
|
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/2007/ - during the drafting process for
this specification this directory should contain a copy of the
most recent published version of the schema at
http://www.xbrl.org/2007/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 |
This appendix contains a list of the errata that have been incorporated into this document. This represents all those errata corrections that have been approved by the XBRL International Formula Working Group up to and including 31 December 2007. Hyperlinks to relevant e-mail threads may only be followed by those who have access to the relevant mailing lists. Access to internal XBRL mailing lists is restricted to members of XBRL International Inc.
No errata have been incorporated into this document.