Copyright © 2011, 2017 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 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 input XBRL instances.
The filters defined in this specification facilitate selection of facts based on dimension information in both the input XBRL instance and in its supporting DTS. Both typed and explicit dimensions can be used to filter facts in the input 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.5.1 Typographic conventions
1.5.1.1 Definition notation
1.5.1.2 Footnote notation
1.5.1.3 Element and attribute notation
1.5.1.4 Error code notation
1.5.2 Formatting conventions
1.6 Namespaces and namespace prefixes
1.7 XPath usage
2 Syntax
2.1 Explicit dimension filter
2.1.1 Dimension Relationship Set Axes
2.2 Typed dimension filter
A Normative schema
A.1 dimension-filter-1.1.xsd
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 A normative example
2 A non-normative example
3 An example of poor usage
4 Explicit dimension filters
5 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
Publication URL
typed dimension filter
xbrldfe:DRSaxisFilterSpecifiesArcrole
xbrldfe:DRSaxisMissingFactVariableReference
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 input 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.
All of the filters defined in this specification can cover the dimension aspect for their 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 input 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.
Comments which are informative, but not essential to the understanding of the point at hand, are provided in footnotes. All footnotes are non-normative.
When referring to a specific element, it will be identified by
its namespace prefix and local name. For example, the root
element for a specification container element would be referred to as
<variable:generalVariable> .
Attributes are also identified by their local name and, where
appropriate, their namespace prefix. Attributes are
distinguished from elements by prefixing them by an
@
symbol. Thus,
@id
refers to the attribute with the name id.
When referring to any attribute, so long as it has a specific
namespace, the local name is replaced by an asterisk (
*).
Thus, the notation @xml:* specifies any attribute
in the namespace
http://www.w3.org/XML/1998/namespace.
The following highlighting is used for normative technical material in this document:
Text of the normative example.
The following highlighting is used for non-normative examples in this document:
Text of the helpful example.
Next paragraph of the helpful example.
Example 3 shows the formatting for non-normative examples of poor, discouraged or disallowed usage.
The example itself.
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/PWD/2017-01-11/filter/dimension-1.1 |
xbrldfe |
http://xbrl.org/PWD/2017-01-11/filter/dimension-1.1/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 set of domain members, in the explicit dimension domain, with QNames that are 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 sequence 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 each
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 domain members in its filter-member set are the domain members identified by the filter-member value.
The term in the implied XPath expression for that filter member is then:
some $member in #member satisfies
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.
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 any of the domain members 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 members 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 any of the domain members 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 any of the domain members 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 members identified by the filter-member value
and those domain members in the explicit dimension domain that are descendants,in the filter-member network,
of any of the domain members 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 #member satisfies (
some $domainmember in
xfi:filter-member-network-selection(#dimension,$member,#linkrole,#arcrole,#axis)
satisfies (xfi:fact-explicit-dimension-value(.,#dimension) eq $domainmember)
)
)
else fn:false()
)
where #axis is equal to the filter-member axis,
#linkrole is equal to the filter-member linkrole,
#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 is
in the explicit dimension domain.
|
|
eg:region
|
eg:australasia
|
Facts must report a value for the
eg:region dimension that is
the domain member eg:australasia.
|
|
eg:region
|
eg:australasia, eg:europe
|
Facts must report a value for the
eg:region dimension that is either of
the domain members eg:australasia or
eg:europe.
|
|
eg:region
|
eg:australasia
|
child
|
Facts must report a value for the
eg:region dimension 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, eg:europe
|
descendant
|
Facts must report a value for the
eg:region dimension that is
a descendant of one or both of the
eg:australasia and eg:europe
domain members 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:region dimension 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.
|
Two additional values for the axis attribute are provided for filtering relationships of a Dimension Relationship Set (DRS) [DIMENSIONS Def,3]. For these axes, filter-member network is the set of relationships between valid members of the effective domain [DIMENSIONS Def,14] for the filter dimension in the DRS.
The relationship source is determined by the fact bound to the
fact variable
named by the QName value of the
<df:member> element child <df:variable> . If that variable is not bound to a fact, (e.g.,
it has an atomic fallback value, then the filter-member network is empty.
Error code xbrldfe:DRSaxisMissingFactVariableReference
MUST be thrown if a <df:member> element with a DRS axis
omits a child <df:variable>
element, or if the value of the <df:variable> element is not a QName of a
fact variable.
The primary item of the relationship source [DIMENSIONS Def,1] is the bound variable fact's concept.
The relationship target is determined by a candidate fact that is the context item of the filter. The primary item of the relationship target is the candidate fact's concept. The candidate fact's dimension member value is the relationship target member for the DRS-axis relationship.
Primary items (plural) refers to the relationship source bound fact variable's concept and context item of the filter candidate fact's concept.
If a <df:linkrole> element is present, then it specifies the base set in which the primary items
are associated to the combination of hypercubes that is the 'head' of the DRS, e.g., the relationship source
primary item concept is the DRS head primary item or inherits hypercubes from it, and the effective domain is
consecutively related to that base set's hypercubes.
If the <df:linkrole> element is absent, then all DRS link roles that connect the primary items and
specified dimension's domain contribute to the effective domain.
The <df:arcrole> element is not relevant for DRS relationship axes. The filter-member network is determined
by the DRS network arcroles, for the relationships from the primary items, to the
relationship source and target dimension member. If there are
Error code xbrldfe:DRSaxisFilterSpecifiesArcrole
MUST be thrown if a <df:member> element with a DRS axis
has a child <df:arcrole> .
If the @axis attribute on a filter member equals DRS-child,
then the filter-member set includes those domain members
in the explicit dimension domain that are valid child consecutive-relationship targets.
If the @axis attribute on a filter member equals DRS-descendant,
then the filter-member set includes those domain members
in the explicit dimension domain that are valid descendant consecutive-relationship targets.
The filter member network includes all domain-member consecutive relationships (child or descendant) in the effective domain, from the relationship source's dimension member (valid for the relationship source primary item), to the relationship target's dimension member (valid for the context item fact's primary item).
The term in the implied XPath expression, for each such filter member may be (but is not suggested for implementation, as this is unlikely to be as efficient as an API-based implementation):
(
if (xfi:fact-has-explicit-dimension(.,#dimension))
then (
some $member in
xfi:filter-member-DRS-selection(
#dimension,
node-name(.),
xfi:fact-explicit-dimension-value(#variable,#dimension),
#linkrole,
#axis)
satisfies (xfi:fact-explicit-dimension-value(.,#dimension) eq $member)
)
else fn:false()
)
where #axis is equal to the filter-member axis,
#variable is equal to the fact bound to the
variable named by the QName value of the <df:variable> element,
#linkrole is equal to the filter-member linkrole
if a <df:linkrole> element is present, otherwise an empty sequence.
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.
|
This section contains XML files that form part of this specification. Each document has a standard Publication URL, at which the normative copy of the document is published. A non-normative copy of each document is included in this appendix for convenience.
All references to these documents made for the purposes of DTS Discovery MUST resolve to the Publication URL, after applying XML Base processing (where applicable) and resolving any relative URLs.
It should be noted that the path component of a URL is case-sensitive, and so must match exactly. Further, alternative hosts and schemes that happen to resolve to the same location are not considered equivalent and may not be used. See [URI] for more details on URL equivalence.
The requirement to reference documents by Publication URL does not prevent processors from substituting local copies of the documents for performance or other reasons.
The Publication URL for this schema is http://www.xbrl.org/PWD/2017-01-11/dimension-filter-1.1.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 |
|---|---|---|
| 20 July 2011 | Herm Fischer |
Public Working Draft of v1.1, adding Discoverable Relationship Set (DRS) functionality to Dimensions Filters v1.0. |
| 11 January 2017 | Stuart Barker |
Second Public Working Draft of Dimension Filters v1.1 |
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 10 March 2011. 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.