Dimension Filters 1.0

Public Working Draft 31 December 2007

Copyright ©2007 XBRL International Inc., All Rights Reserved.

This version:
<http://www.xbrl.org/Specification/dimensionFilters-PWD-2007-12-31.html>
Editors:
Phillip Engel, Morgan Stanley <phillip.engel@morganstanley.com>
Herm Fischer, UBMatrix / Mark V Systems <fischer@markv.com>
Victor Morilla, Banco de España <victor.morilla@bde.es>
Jim Richards, JDR & Associates <jdrassoc@iinet.net.au>
Geoff Shuetrim, Galexy <geoff@galexy.net>
David vun Kannon, PricewaterhouseCoopers LLP <david.k.vunkannon@us.pwc.com>
Hugh Wallis, XBRL International <hughwallis@xbrl.org>
Contributors:
Cliff Binstock, Coyote Reporting <cliff.binstock@coyotereporting.com>
Paul Bull, Morgan Stanley <paul.bull@morganstanley.com>
Mark Goodhand, Decisionsoft <mrg@decisionsoft.com>
Masatomo Goto, Fujitsu <mg@jp.fujitsu.com>
Walter Hamscher, Standard Advantage / Consultant to PricewaterhouseCoopers LLP <walter@hamscher.com>
Ignacio Hernández-Ros, Reporting Estandar S.L. <ignacio@hernandez-ros.com>
Roland Hommes, Rhocon / Consultant to Netherlands Tax and Customs Administration <roland@rhocon.nl>
David Jeffery, UBMatrix <david.jeffery@ubmatrix.com>
Michele Romanelli, Banca d'Italia <michele.romanelli@bancaditalia.it>
Chris Simmons, DecisionSoft <cps@decisionsoft.com>
Masaru Uchida, Fujitsu <m-uchida@jp.fujitsu.com>

Status

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.

Abstract

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.

Table of Contents

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

Appendices

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

Table

1 Namespaces and namespace prefixes

Examples

1 Explicit dimension filters
2 Dimension member filters
3 Typed dimension filters

Definitions

dimension member filter
explicit dimension filter
filter-member relationship
recognised member of a dimension
typed dimension filter

Error code

xbrldfe:invalidDomainMember


1 Introduction

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.

1.1 Background

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

1.2 Relationship to other work

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.

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.

1.5 Document conventions (non-normative)

Documentation conventions follow those set out in the XBRL Variables Specification [VARIABLES].

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

1.7 XPath usage

XPath usage is identical to that in the XBRL Variables Specification [VARIABLES].

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

2.1 Explicit dimension filter

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.

Example 1: Explicit dimension filters
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

eg:brazil

eg:austria

Facts must be reported with either eg:brazil or eg:austria as the value specified for dimension eg:country.

2.1.1 Filter-member relationships

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:

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

2.2 Dimension member filter

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:

  • the <df:member> element is supplied;
  • the @inclusive attribute is false; and
  • the @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:

  • the <df:member> element is supplied;
  • the @inclusive attribute is true; and
  • the @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:

  • the <df:member> element is supplied;
  • the @inclusive attribute is false; and
  • the @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:

  • the <df:member> element is supplied;
  • the @inclusive attribute is true; and
  • the @childrenOnly attribute is false.
Example 2: Dimension member filters
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.

2.3 Typed dimension filter

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:

  • the fact's concept is associated with the typed dimension identified by the QName implied by the typed dimension filter's @df:dimension element, and
  • the fact has a context that contains a value for the specified typed dimension that meets the conditions specified by the @test attribute.
Example 3: Typed dimension filters
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.

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:

  1. 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/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.
  2. 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.
<schema xmlns:df="http://xbrl.org/2007/filter/dimension" xmlns:generic="http://xbrl.org/2007/generic" xmlns:variable="http://xbrl.org/2007/variable" xmlns="http://www.w3.org/2001/XMLSchema" xmlns:link="http://www.xbrl.org/2003/linkbase" xmlns:xl="http://www.xbrl.org/2003/XLink" targetNamespace="http://xbrl.org/2007/filter/dimension" elementFormDefault="qualified" xsi:schemaLocation="http://www.w3.org/2001/XMLSchema http://www.w3.org/2001/XMLSchema.xsd http://www.xbrl.org/2003/linkbase http://www.xbrl.org/2003/xbrl-linkbase-2003-12-31.xsd">
<import namespace="http://www.xbrl.org/2003/XLink" schemaLocation="http://www.xbrl.org/2003/xl-2003-12-31.xsd"/>
<import namespace="http://xbrl.org/2007/variable" schemaLocation="variable.xsd"/>
<annotation>
<appinfo>
<link:arcroleType id="filter-member" cyclesAllowed="none" arcroleURI="http://xbrl.org/arcrole/2007/filter-member">
<link:definition>
filter has domain member
</link:definition>
<link:usedOn>
generic:arc
</link:usedOn>
</link:arcroleType>
</appinfo>
</annotation>
<complexType name="qname.model">
<choice>
<element name="qname" type="QName"/>
<element name="qnameExpression" type="variable:expression"/>
</choice>
</complexType>
<element id="xml-explicit-dimension-filter" name="explicitDimension" substitutionGroup="variable:filter">
<complexType mixed="true">
<complexContent mixed="true">
<extension base="variable:resource.type">
<sequence>
<element name="dimension" type="df:qname.model"/>
</sequence>
</extension>
</complexContent>
</complexType>
</element>
<element id="xml-dimension-member-filter" name="dimensionMember" substitutionGroup="variable:filter">
<complexType mixed="true">
<complexContent mixed="true">
<extension base="variable:resource.type">
<sequence>
<element name="dimension" type="df:qname.model"/>
<element name="member" type="df:qname.model" minOccurs="0"/>
<element name="linkrole" type="anyURI"/>
</sequence>
<attribute name="childrenOnly" type="boolean"/>
<attribute name="inclusive" type="boolean"/>
</extension>
</complexContent>
</complexType>
</element>
<element id="xml-typed-dimension-filter" name="typedDimension" substitutionGroup="variable:filter">
<complexType mixed="true">
<complexContent mixed="true">
<extension base="variable:resource.type">
<sequence>
<element name="dimension" type="df:qname.model"/>
</sequence>
<attribute name="test" type="variable:expression" use="optional"/>
</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 (Public Working Draft)"
Mark Goodhand, Ignacio Hernández-Ros, and Geoff Shuetrim.
(See http://www.xbrl.org/Specification/XGL-PWD-2007-04-24.rtf)
VARIABLES
XBRL International Inc.. "XBRL Variables 1.0, Public Working Draft"
Phillip Engel, Herm Fischer, Victor Morilla, Jim Richards, Geoff Shuetrim, David vun Kannon, and Hugh Wallis.
(See variables-PWD-2007-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-2006-12-18.htm)
XBRL FUNCTIONS
XBRL International Inc.. "XBRL Functions 1.0, Public Working Draft"
Cliff Binstock, Philip Engel, Herm Fischer, Ignacio Hernández-Ros, Chris Simmons, David vun Kannon, Hugh Wallis, and Paul Warren.
(See http://www.xbrl.org/SpecPWDs/)
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/)

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)

DateAuthorDetails
23 April 2007Geoff Shuetrim

First internal working draft created, drawing on the use cases provided by Victor Morilla.

03 May 2007Geoff Shuetrim

Incorporated feedback on the implied XPath expression designs from Victor Morilla.

08 May 2007Geoff Shuetrim

Added clarification about the fact aspect covered by the filters defined in this specification.

18 May 2007Geoff Shuetrim

Modified the dimension-member filter to include the inclusive Boolean attribute and to cover the case where the <member> element is omitted. The changes were based on feedback on limitations of the filter identified in Herm Fischer's preparations for the 2007 Munich conference.

29 May 2007Geoff Shuetrim

Changed the target namespace of the normative schema again. Made the QName specification capable of covering static and dynamic QNames.

04 June 2007Geoff Shuetrim

Simplified the implied XPath expression for filters on typed dimensions.

11 June 2007Geoff Shuetrim

Clarified the explanation of the functions required to support the implied XPath expression for the explicit-dimension filter.

25 June 2007Geoff Shuetrim

Modified the information about implicit filter implications of dimension filters to allow for implicit filtering at the individual dimension level.

24 July 2007Hugh Wallis

Edited for public working draft publication.

05 November 2007Geoff 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 @dimension attribute in the typed dimension filter XPath explanation.

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 2007Geoff 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 2007Geoff Shuetrim

Linked all of the external terminology references back to bibliographic citations.

27 November 2007Jim Richards

Updated the abstract to include a reference to the Varaibles Spec.

Made some minor grammatical changes.

30 November 2007Geoff Shuetrim

Added examples.

06 December 2007Geoff Shuetrim

Added a <df:linkrole> element to the dimension member filter to ensure that all members are being selected from among those with domain-member relationships to the dimension that have the the specified link role. This prevents the filter from mixing up different networks of domain members for the one dimension.

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