Copyright ©2011 XBRL International Inc., All Rights Reserved.
Circulation of this Recommendation is unrestricted. This document is normative. 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 defines an XML syntax that can be used to express XPath 2.0 [XPATH 2.0] implementations of the custom functions defined in [VARIABLES]. The custom function implementations are incorporated into the generic links [GENERIC LINKS] containing the XPath 2.0 [XPATH 2.0] expressions that include calls to the custom functions. Thus, this specification enables consistency of custom function results across supporting processors. It also gives users of custom functions the ability to extend functionality without requiring processor modifications.
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.2 Formatting conventions
1.6 Namespaces and namespace prefixes
1.7 XPath usage
2 Syntax
2.1 Custom function implementations
2.1.1 Input elements
2.1.2 Step elements
2.1.3 Output elements
2.2 Custom function implementation relationships
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 A normative example
2 A non-normative example
3 An example of poor usage
4 Custom function implementations
CFI input
CFI output
CFI step
CFI's signature
Function Implementation Relationship
custom function implementation (CFI)
rfc2119 terminology
xbrlcfie:inputMismatch
xbrlcfie:missingCFIRelationship
xbrlcfie:tooManyCFIRelationships
This specification defines an XML syntax that can be used to express implementations of the custom functions defined in [VARIABLES] using sequences of XPath 2.0 expressions [XPATH 2.0]. The custom function implementations are incorporated into the generic links [GENERIC LINKS] containing the XPath 2.0 [XPATH 2.0] expressions that include calls to the custom functions. Thus, this specification enables consistency of custom function results across supporting processors. It also gives users of custom functions the ability to extend functionality without requiring processor modifications.
The XML syntax that encapsulates custom function implementations enables those custom function implementations to be embedded in XBRL [XBRL 2.1] linkbases, thus making them readily available to processors that are executing XPath 2.0 expressions that include calls to them.
The XBRL Variables Specification [VARIABLES] provides a foundation for a variety of other XBRL Specifications that support evaluation of formulae and assertion testing using the data in XBRL instances. The XBRL Variables Specification and those that build upon it, make extensive use of XPath 2.0 expressions.
Those expressions are permitted, by the XBRL Variables Specification, to contain calls to custom functions. The only requirement is that, when a call to a custom function is used, the Discoverable Taxonomy Set containing the custom function call is required to include a custom function signature declarations for that custom function. The signature is enough to understand the data type of the function arguments and the data type of its output but it does not provide an actual function implementation.
Without actual function implementations, custom function calls will only be possible to evaluate for processors with their own implementations. This imposes an additional workload on those maintaining processors and it increases the scope for inconsistencies in the implementations of the custom functions.
This specification addresses these limitations by defining a syntax that can be used to provide custom function implementations along with the XPath 2.0 expressions that call the custom functions.
Processors that are conformant with this specification will be able to execute custom function implementations where they are available. They will not, however, be required to use such custom function implementations. This is important, for example, to prevent conformant specifications from being limited to inefficient custom function implementations when more efficient alternatives are available.
Also note that conformant processors will not require all custom functions to have custom function implementations. In some cases the custom function implementations can be expected to be unsuitable for implementation using XPath expressions. This specification does not prevent such custom functions from being used.
This specification depends upon the XBRL Specification [XBRL 2.1], the XBRL Variables Specification [VARIABLES], and the Generic Link Specification [GENERIC LINKS]. It is also dependent upon the XPath 2.0 Specification [XPATH 2.0]. 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.
The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL, in this specification, are to be interpreted as described in [IETF RFC 2119].
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 |
|---|---|
cfi
|
http://xbrl.org/2010/custom-function
|
xbrlcfie
|
http://xbrl.org/2010/custom-function/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
|
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
|
XPath usage is identical to that in the XBRL Variables Specification [VARIABLES].
The XPath expressions implied by
<cfi:step> and
<cfi:output>
are evaluated using the <xbrli:xbrl> element of the
input XBRL instance
as the context item.
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.
A custom function implementation (CFI) is an XPath 2.0 implementation of a
custom function that is
encapsulated using the XML [XML] syntax defined in this specification.
A CFI is declared by a <cfi:implementation>
element.
A CFI contains a sequence of child elements that serve to define names for the function inputs, to express the XPath 2.0 expressions that comprise the custom function implementation, and to define the custom function output. These elements are defined in the following sections.
A CFI input is a <cfi:input>
child element of a CFI and it expresses the name for
one of the custom function's input parameters.
The syntax for the <cfi:input>
element is defined by the normative schema supplied with
this specification.
The input parameter name is the QName contained by the @name attribute
on the CFI input.
Error code xbrlcfie:inputMismatch MUST be thrown if a CFI does not contain exactly one CFI input for each input parameter of the custom function.
The names specified by the CFI inputs are applied to the custom function inputs in document order. Thus, the name of the first custom function input is supplied by the first CFI input in the relevant CFI, based on document order. Likewise, the name of the n'th custom function input is supplied by the n'th CFI input in the relevant CFI, based on document order.
A CFI step is a <cfi:step>
child element of a CFI and it expresses a single XPath 2.0 expression
and a name for the result of evaluating that XPath 2.0 expression.
The syntax for the <cfi:step>
element is defined by the normative schema supplied with
this specification.
The result name is the QName contained by the @name attribute
on the CFI step.
The XPath 2.0 expression in a CFI step MUST be evaluated with an evaluation context that includes
@name attribute in the <variable:parameter>
element.
In the case of a conflict between the QName of a parameter in the DTS and a CFI input or a CFI step, the variable of the CFI input or CFI step takes precedence. Thus, the variables of CFI inputs and CFI steps override variables of DTS parameters with the same QName.
A CFI MAY contain more than one CFI step. In such cases, the steps MUST be evaluated in document order.
A CFI output is a <cfi:output>
child element of a CFI and it expresses a single XPath 2.0 expression
that produces the function output when evaluated.
The syntax for the <cfi:output>
element is defined by the normative schema supplied with
this specification.
The XPath 2.0 expression contained by the CFI output MUST be evaluated last (subsequent to all CFI steps in the same CFI) when evaluating a CFI. This expression MUST be evaluated with an evaluation context equivalent to that of CFI steps (the CFI output can be considered the last CFI step in a CFI).
| Explanation | CFI's signature | CFI's implementation |
|---|---|---|
| Trims leading and trailing spaces from the input string. |
eg:trim ($input as xs:string?) as xs:string
|
<cfi:implementation>
<cfi:input name="arg"/> <cfi:output> </cfi:implementation>
replace(replace($arg,'\s+$',''),'^\s+','')
</cfi:output> |
| Return true if and only if the input can be cast to a numeric type. |
eg:isNumeric ($input as xs:anyAtomicType?) as xs:boolean
|
<cfi:implementation>
<cfi:input name="value"/> <cfi:output> </cfi:implementation>
string(number($value)) != 'NaN'
</cfi:output> |
Compute the sum of the values of the facts in an input sequence
checking that all facts are aspect-matched except for a specified
explicit dimension and checking that there is exactly one fact in
the sequence for each domain member of the explicit dimension with
a specified relationship from the explicit dimension domain member
with the specified QName. Throws an exception if the explicit dimension
does not have the specified domain member.
Make sure that the implementation does not throw exceptions if the data types
of any of the input facts are numeric but not xs:decimal.
The axis input determines the nature of the domain member selection strategy.
Valid values for the axis input are
child,child-or-self,
descendant and descendant-or-self.
|
eg:sum ($input as xbrli:item*, $dimension as xs:QName, $member as xs:QName, $linkrole as xs:QName, $arcrole as xs:QName, $axis as xs:string) as xs:decimal
|
<cfi:implementation xlink:type="resource" xlink:label="cust-fn-sum-impl">
<cfi:input name="facts"/> <cfi:input name="dimension"/> <cfi:input name="member"/> <cfi:input name="linkrole"/> <cfi:input name="arcrole"/> <cfi:input name="axis"/> <!-- no way to know if any of these aspects are covered!!! so assume not covered --> <cfi:step name="mismatchedUnitAspects">
for $f1 in $facts[1],
$i in 2 to count($facts),
$fi in $facts[$i] return (
if ( xfi:u-equal($f1,$fi) )
then ()
else concat('unit: ', node-name($f1), '[', $f1/@unitRef, '] -',
node-name($fi), '[', $fi/@unitRef, ']')
</cfi:step><cfi:step name="mismatchedConceptAspects">
for $f1 in $facts[1],
$cn1 in node-name($f1),
$i in 2 to count($facts),
$fi in $facts[$i] return (
if ( $cn1 eq node-name($fi) )
then ()
else concat('concept: ', node-name($f1), '[', $f1/@contextRef, '] -',
node-name($fi), '[', $fi/@contextRef, ']')
</cfi:step><cfi:step name="mismatchedIdentifierAspects">
for $f1 in $facts[1],
$i in 2 to count($facts),
$fi in $facts[$i] return (
if ( xfi:fact-identifier-value($f1) eq xfi:fact-identifier-value($fi) and
xfi:fact-identifier-scheme($f1) eq xfi:fact-identifier-scheme($fi) )
then ()
else concat('identifier: ', node-name($f1), '[', $f1/@contextRef, '] -',
node-name($fi), '[', $fi/@contextRef, ']')
</cfi:step><cfi:step name="mismatchedPeriodAspects">
for $f1 in $facts[1],
$p1 in xfi:period($f1),
$i in 2 to count($facts),
$fi in $facts[$i],
$pi in xfi:period($fi) return (
if ( xfi:is-forever-period($p1) and xfi:is-forever-period($pi) ) then ()
else (
if ( xfi:is-instant-period($p1)
and xfi:is-instant-period($pi)
and xfi:period-instant($p1) eq xfi:period-instant($pi) ) then ()
else (
if ( xfi:is-duration-period($p1) and xfi:is-duration-period($pi)
and xfi:period-start($p1) eq xfi:period-start($pi)
and xfi:period-end($p1) eq xfi:period-end($pi) ) then ()
else (
concat('period: ', node-name($f1), '[', $f1/@contextRef, '] -',
node-name($fi), '[', $fi/@contextRef, ']')
)
)
)
)
</cfi:step><cfi:step name="membersExpected">
(: throws exception if the dimension does not have the domain member so change to
test if the dimension has the member in the relevant network before running the function.
This is probably best encapsulated in a new XFI function that partners the filter-member-network-selection function. :)
distinct-values(
xfi:filter-member-network-selection($dimension,$member,$linkrole,$arcrole,$axis)
)
</cfi:step><cfi:step name="membersReported">
for $f in $facts return
xfi:fact-explicit-dimension-value($f,$dimension)
</cfi:step><cfi:step name="missingDimensionMembers">
for $mem in $membersExpected return
if ( index-of($membersReported,$mem) )
then ()
else concat('missing member: ', node-name($mem) )
</cfi:step><cfi:step name="unexpectedDimensionMembers">
for $mem in $membersReported return
if ( index-of($membersExpected,$mem) )
then ()
else concat('unexpected member: ', node-name($mem) )
</cfi:step><cfi:step name="duplicatedReportedMembers">
for $mem in distinct-values($membersReported) return
if ( count(index-of($membersReported,$mem)) eq 1 )
then ()
else concat('duplicated member: ', node-name($mem) )
</cfi:step><cfi:step name="aspect-issues">
(
$mismatchedUnitAspects,
$mismatchedConceptAspects,
$mismatchedIdentifierAspects,
$mismatchedPeriodAspects,
$missingDimensionMembers,
$unexpectedDimensionMembers,
$duplicatedReportedMembers
)
</cfi:step><cfi:output> </cfi:implementation>
if (empty($facts))
then 0
else (
if (empty($aspect-issues))
then sum($facts)
else error( QName('http://abc.com/test1','aspect-issues'),
string-join( $aspect-issues, ',') )
)
</cfi:output> |
A Function-Implementation relationship is a relationship between a custom function signature and a custom function implementation, expressed by an XLink arc.
To declare a function-implementation relationship an XLink arc MUST:
http://xbrl.org/arcrole/2010/function-implementation
The arcrole value,
http://xbrl.org/arcrole/2010/function-implementation,
is declared in the normative schema for custom function implementations.
Funtion-implementation relationships MUST be expressed by generic arcs. Violations of this requirement can be detected by validation against the XBRL Specification [XBRL 2.1].
Error code xbrlcfie:tooManyCFIRelationships MUST be thrown if a function signature is the source of more than one function-implementation relationship or if a function implementation is the target of more than one function-implementation relationship.
Error code xbrlcfie:missingCFIRelationship MUST be thrown if a function implementation is not the target of a function-implementation relationship.
A CFI's signature is the custom function signature with a function implementation relationship to the CFI.
A CFI MAY include calls to XPath functions. Those XPath functions called as part of the implementation of a the custom function declaration, can be the built-in XPath functions defined in [XPATH AND XQUERY FUNCTIONS]; they can be other custom functions (with their own custom function signatures), or they can be custom function declarations known to the formula processor.
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/2010/custom-function-implementation.xsd.
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/2009/ - 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/2010/custom-function-implementation.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 |
|---|---|---|
| 19 May 2009 | Geoff Shuetrim |
Produced a first internal working draft based upon the use cases and requirements and independent implementation experience captured on the Formula Working Group Wiki. |
| 20 May 2009 | Geoff Shuetrim |
Refined the explanation for how XQuery modules would be contained in CFIs. |
| 17 June 2009 | Geoff Shuetrim |
Corrected schema based on feedback from Andy Harris. |
| 22 June 2009 | Geoff Shuetrim |
Aligned namespaces in specification and schema as suggested by Andy Harris. |
| 11 November 2009 | Herm Fischer |
Per FWG conf call on 2009-11-05, it was decided to go forward with the XPath form of custom function and not XQuery. The specification with XQuery capability is preserved inactively in SVN under the file name custom-function-implementation-with-xquery.xml, to make it easy to access the file before edits to remove the XQuery. This is the XPath version of the custom function spec (not named with suffix -with-xquery), and has all of the XQuery references and discussion removed. Removed XQuery implementation element and renamed the XPath alt-implementation element to implementation. Renamed arcrole for consistency with other formula arcs (that use the names of the from and to elements with a dash between them), so it is now function-implementation. |
| 13 December 2009 | Victor Morilla |
Added paragraph for DTS parameters to be included as in-scope variables, as discussed in the WG Rearranged some paragraphs and section numbers Changed schema xsd:QName types to variable:QName Changed namespaces to 2010 |
| 07 September 2010 | Herm Fischer |
Editorial changes per Hitoshi Okumura.
Changed |
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 24 October 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.