XBRL Formula 1.0 Specification
Public Working Draft, dated 2006-12-18
Copyright © 2006, XBRL International Inc., All Rights Reserved
This version:
Formula-PWD-2006-12-18.rtf
is NORMATIVE. All other versions and formats are non-normative.
Editors
Name	Contact	Affiliation	
Phillip Engel	Phillip.Engel@morganstanley.com 	Morgan Stanley	
Geoff Shuetrim	geoff@galexy.net	Galexy	
David vun Kannon	david.k.vunkannon@us.pwc.com 	PricewaterhouseCoopers LLP	
Contributors
Name	Contact	Affiliation	
Walter Hamscher	walter@hamscher.com	Standard Advantage / Consultant to PricewaterhouseCoopers LLP	
David Jeffery	david.jeffery@ubmatrix.com	UBmatrix	
Chris Simmons	cps@decisionsoft.com	DecisionSoft	
Abstract
This specification is an extension of the XBRL 2.1 Specification [XBRL].  It enables XBRL taxonomies to include declarations of formulae that operate on XBRL data.
Status
This is a Public Working Draft whose circulation is unrestricted. Comments should be directed to the editor and/or contributors by e-mail.  Recipients of this draft are invited to submit, with their comments, notification of any relevant patent rights of which they are aware and to provide supporting documentation.
In the final version of this document:
•	relevant schema extracts will be included in the text of the specification
•	relevant examples will be included
•	error codes will be included.
To reduce the editorial burden, these aspects of the specification have been omitted for working drafts.
Normative status
This document is normative in the sense that any implementing processor must obey the rules described herein, in order to be considered a conformant processor.
Table of contents
Contributors
Typographic conventions
Formatting conventions
Namespace conventions (normative)
1	Introduction
2	Syntax
2.1	Formula resources
2.1.1	Formula results
2.1.2	Concept identifier
2.1.3	Result context
2.1.4	Result unit
2.1.5	Result precision
2.1.6	Result custom attributes
2.2	Formula variables
2.2.1	Formula-variable relationships
2.2.2	Concept-formula relationships
2.3	Formula preconditions
2.3.1	Precondition declarations
2.3.2	Formula-precondition relationships
3	Processing model
3.1	Input
3.2	Formula evaluation
3.3	Message reporting by formula processors
3.3.1	Syntactic errors in formula declarations
3.3.2	XPath expression evaluation exceptions
3.3.3	Failed or successful variable bindings
3.3.4	Failed or successful formula bindings
3.3.5	Messages about the content of the target instance
Appendices
A	References (Non Normative)
B	Normative error codes
C	Normative schema

Document conventions (non-normative)
Typographic conventions
Comments which are informative, but not essential to the understanding of the point at hand are provided in footnotes. All footnotes are non-normative.
Formatting conventions
The following highlighting is used to present normative technical material in this document:
	
The following formatting is used for non-normative examples in this document:

The following formatting is used for non-normative counterexamples (examples of poor, discouraged or disallowed usage) in this document:

Namespace conventions (normative)
This table contains all the prefixes used within the text and the correspondent namespace URI. The prefix column in the table above is non normative. The namespace URI column is normative.
Prefix	Namespace URI	
xbrli	http://www.xbrl.org/2003/instance	
generic	http://xbrl.org/2007/generic	
formula	http://xbrl.org/2007/formula	
Relationship to other work
This specification depends upon XBRL 2.1 Specification [XBRL]. This specification depends upon XBRL Variables 1.0 Specification [VARIABLES].
In the event of any conflicts between this specification and the specifications upon which it depends, this specification does not prevail.
Language independence
The official language of XBRL International’s own work products is English and the preferred spelling convention is UK English.
Terminology
All terminology defined in the XBRL 2.1 Specification and the XBRL Variables 1.0 Specification is used unchanged in this specification.
The following additional terms are used as described in the table below:
Term	Meaning (Normative)	
target instance	The target instance is the XBRL instance containing facts that MAY be bound to variables.	
XPath usage
Some attributes defined by this specification contain values that are evaluated as XPath 2.0 [XPath2.0] expressions. Wherever an XPath expression is mentioned in this specification it refers to an XPath 2.0 expression. The evaluation context for an XPath expression is determined by the attribute that contains the expression. The statically known namespaces used in the expressions are those that are in scope for the element that has the attribute that contains the XPath expression.
XPath expression evaluation is assumed in this specification to be performed without using the XPath 1.0 compatibility mode.
1	Introduction
A formula is way of describing formulaic relationships between XBRL components, mainly XBRL concepts. When evaluated successfully against an XBRL instance, formulae produce new XBRL facts. For example, a simple formula may express the formulaic relationship of current ratio = current assets / current liabilities. The formula describes the use of the XBRL concepts for the current ratio, current assets and current liabilities and that current assets should be divided by current liabilities to result in a value for the current ratio.
The general processing model for a formula is to apply the formula against an XBRL instance document. Formulae may be used to validate information in the instance document or to produce new facts to augment the information in the instance document.
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 those explanations are not already provided in other specifications.
2.1	Formula resources
Formulae are declared using the formula:formula element in an XBRL extended link.  Such a declaration is referred to as a formula.
2.1.1	Formula results
The content of a value attribute on formula is interpreted as an XPath expression.  It is referred to as the formula expression.
When evaluated it MUST produce the value of a single XBRL item.
The formula expression MUST be evaluated using the xbrli:xbrl element of the target instance as the context node.
2.1.2	Concept identifier
Formulae MAY contain a concept identifier. A concept identifier is the concept attribute on the formula itself.  A concept identifier provides a means of determining the concept to be used for an item produced by the formula.  It is suitable for formulae that produce items for more than one concept.
The content of a concept identifier is interpreted as an XPath expression.  It is referred to as the concept identifier expression.
A concept identifier expression identifies a concept if it evaluates to a single QName.  That QName is the QName identifier of the concept.
2.1.3	Result context
When evaluated, formulae produce items, which all require contexts.  Contexts have many different aspects, such as the entity identifier, all of which need to be determined on the basis of the variable bindings used for a formula evaluation.
The context for an item produced by formula evaluation is determined by the result of evaluating the XPath expression in the context attribute on the formula.
2.1.4	Result unit
When evaluated, formulae MAY produce numeric items, which require units.
The unit for an item produced by formula evaluation is determined by the result of evaluating the XPath expression in the unit attribute on the formula.
A formula that constructs numeric items MUST include a unit attribute.
2.1.5	Result precision
If a formula generates numeric values and the formula contains a precision attribute, the precision of a generated value is obtained by evaluating the XPath expression given in the precision attribute of the formula.
If a formula generates a numeric value and the precision attribute is not specified, then the value MUST be reported with zero precision.
Determination of whether a fact generated by a formula is reported using the precision or decimal attribute is not within the scope of this specification.
2.1.6	Result custom attributes
A formula:attribute child element of a formula specifies a value for a custom attribute that MUST be added to any items produced as a result of evaluating the formula.
The namespace of the custom attribute is specified by the value of the namespace attribute on the formula:attribute element.
The namespace prefix to use for the custom attribute is specified by the value of the prefix attribute on the formula:attribute element.
The local name of the custom attribute is specified by the value of the name attribute on the formula:attribute element.
The value attribute is interpreted as an XPath expression.  The value of the custom attribute is determined by evaluation of the value attribute on the formula:attribute element.
2.2	Formula variables
XPath expressions in a formula declaration MAY include references to XPath variables. These variables are resolved to fact variables or to general variables that are related to formulae by formula-variable relationships.
2.2.1	Formula-variable relationships
Formula-variable relationships are expressed using XLink arcs [XLink].  To declare a formula-variable relationship between a formula and a variable, an XLink arc element MUST:
•	be a formula:arc;
•	have an arcrole equal to http://xbrl.org/arcrole/formula-variable;
•	have the formula at the source of the arc; and
•	have either a fact variable or a general variable at the target of the arc.
The order attribute on formula-variable relationships defines the evaluation order of a formula's variables.  For a given formula, the order attribute MUST specify a strict ordering of the formula-variable relationships in each network of such relationships in a DTS.
The value of the name attribute on a formula-variable arc is the QName of the variables defined by the relationships that the arc expresses. This QName MUST be used when referencing the variable from XPath expressions.
2.2.2	Concept-formula relationships
The concept, for which a formula can produce items, is identified by a concept-formula relationship.  Such relationships are referred to as concept-formula relationships.  They are expressed using XLink arcs.
To express a concept-formula relationship from a concept to a formula, an XLink arc element MUST:
•	be a formula:arc element;
•	have an arcrole equal to http://xbrl.org/arcrole/concept-formula;
•	have the concept at the source of the arc; and
•	have the formula at the target of the arc.
In a DTS, a formula MUST not have a concept-formula relationship to more than one concept.
A formula MAY have no concept-formula relationships to concepts.  In such cases, the concept MAY produce facts for any concepts. Which concept a fact is produced for by a successful formula evaluation is then determined by the output concept identifier.
If a formula contains a concept identifier then any concept-formula relationships to the formula MUST be ignored when evaluating the formula.
2.3	Formula preconditions
Formulae MAY be associated with preconditions that declare conditions under which the formula is to be evaluated.
2.3.1	Precondition declarations
A precondition is declared by a formula:precondition element. A precondition specifies the conditions that MUST be determined to be satisfied before a formula is evaluated.
The test attribute on a precondition is interpreted as an XPath expression.  It's content is referred to as a precondition expression.  A precondition is satisfied if the precondition expression evaluates to an XPath effective Boolean value of true.
2.3.2	Formula-precondition relationships
The preconditions for evaluating a formula are identified by formula-precondition relationships. Such relationships are expressed using XLink arcs.  To express a formula-precondition relationship between a formula and a precondition, an XLink arc element MUST:
•	be a generic arc;
•	have an arcrole equal to http://xbrl.org/arcrole/formula-precondition;
•	have the formula at the source of the arc; and
•	have the precondition at the target of the arc.
Generic arcs are defined in the Generic Link 1.0 Specification [GENLINK].
3	Processing model
This section defines the processing model for a formula.
3.1	Input
The input to a formula processor is an XBRL instance, referred to as the target instance.
3.2	Formula evaluation
A formula evaluation entails:
•	First. evaluating of the XPath expressions implied by each of the formula's variables;
•	Second, evaluating the formula's preconditions to ensure that they are satisfied; and
•	Third, evaluating the formula expression if all variables can be evaluated and all preconditions are satisfied.
A formula MUST evaluate variables using the evaluation order indicated by the order attribute on the XLink arcs defining the formula's variables.
An XPath expression has a variable dependency if the expression includes an XPath variable.  An XPath expression cannot be evaluated if it has unresolved variable dependencies.
A variable dependency for an XPath variable is resolved only if a variable with the same QName as the XPath variable being resolved has already been evaluated as part of the formula evaluation.
When evaluating an XPath expression that includes a variable reference, the value to use for that XPath variable depends on whether the variable that is referenced binds as a sequence or as an individual value.
If the bindAsSequence attribute on an arc declaring a formula-variable relationship equals true, then the value of the XPath variable is the result of evaluating the XPath expression that the variable implies.  Otherwise, the value of the XPath variable is any one of the values in the sequence produced by evaluation of the XPath expression implied by the variable.
If a formula can be evaluated to produce an item value, the XPath expressions determining the concept, context, unit and precision of that item MAY also be evaluated.
3.3	Message reporting by formula processors
A broad range of information can be usefully provided by a formula processor.
Such information includes:
1.	Syntactic errors in formula declarations
2.	XPath expression evaluation exceptions
3.	Failed or successful variable bindings
4.	Failed or successful formula bindings
5.	Messages about the content of the target instance
The handling for each of these kinds of messages is addressed below.
3.3.1	Syntactic errors in formula declarations
Syntactic errors in formula declarations are violations of this specification.  Such violations of this specification MUST be reported by a formula processor using the error codes defined in this specification.  See Appendix B.
3.3.2	XPath expression evaluation exceptions
XPath evaluation exceptions MAY be reported by formula processors.  This specification imposes no constraints on the reporting method.
3.3.3	Failed or successful variable bindings
Failed or successful variable bindings MAY be reported by formula processors.  This specification imposes no constraints on the reporting method.
3.3.4	Failed or successful formula bindings
Failed or successful formula bindings MAY be reported by formula processors.  This specification imposes no constraints on the reporting method.
3.3.5	Messages about the content of the target instance
The rules for creation of messages about the content of the target instance MAY be structured as formulae.  If this approach is adopted, then messages about the content of the target instance will be available from a formula processor as XBRL facts.
Appendices
A	References (Non Normative)

[GENLINK]	Mark Goodhand (editor)
Generic Links in XBRL, Internal Working Draft
	
[VARIABLES]	Phillip Engel, Geoff Shuetrim, David vun Kannon
XBRL Variables 1.0 Specification, Internal Working Draft
	
[XBRL]	Phillip Engel, Walter Hamscher, Geoff Shuetrim, David vun Kannon and Hugh Wallis
Extensible Business Reporting Language 2.1 Recommendation with corrected Errata dated 2005-04-25
http://www.xbrl.org/Specification/XBRL-RECOMMENDATION-2003-12-31+Corrected-Errata-2005-04-25.rtf
	
[XLink]	Steve DeRose, Eve Maler, and David Orchard
XML Linking Language (XLink) Version 1.0
http://www.w3.org/TR/xlink
	
[XPath2.0]	Andreas Berglund et al., editors.
XML Path Language (XPath) 2.0
Working Draft 4 April 2005
http://www.w3.org/TR/xpath20

B	Normative error codes
Normative error codes defined in this specification are listed here.
To be completed.
C	Normative schema
The following is the normative schema for this specification.  

<?xml version="1.0" encoding="UTF-8"?>
<schema 
  xmlns="http://www.w3.org/2001/XMLSchema" 
  targetNamespace="http://xbrl.org/2007/formula"
  xmlns:formula="http://xbrl.org/2007/formula"
  xmlns:expression="http://xbrl.org/2007/expression" 
  xmlns:generic="http://xbrl.org/2007/generic" 
  xmlns:link="http://www.xbrl.org/2003/linkbase" 
  xmlns:xl="http://www.xbrl.org/2003/XLink"
  elementFormDefault="qualified"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  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/expression" 
    schemaLocation="expression.xsd"/>

  <annotation>
    <appinfo>

      <link:arcroleType
        id="concept-formula" 
        cyclesAllowed="none" 
        arcroleURI="http://xbrl.org/arcrole/concept-formula">
        <link:definition>concept-formula</link:definition>
        <link:usedOn>generic:arc</link:usedOn>
      </link:arcroleType>

      <link:arcroleType
        id="formula-variable" 
        cyclesAllowed="none" 
        arcroleURI="http://xbrl.org/arcrole/formula-variable">
        <link:definition>formula-variable</link:definition>
        <link:usedOn>formula:arc</link:usedOn>
      </link:arcroleType>

      <link:arcroleType
        id="formula-precondition" 
        cyclesAllowed="none" 
        arcroleURI="http://xbrl.org/arcrole/formula-precondition">
        <link:definition>formula-precondition</link:definition>
        <link:usedOn>generic:arc</link:usedOn>
      </link:arcroleType>	

    </appinfo>
  </annotation>

  <element name="attribute">
    <complexType>
      <attribute name="id" type="ID" use="optional"/>
      <attribute name="namespace" type="anyURI" use="required"/>
      <attribute name="prefix" type="NCName" use="required"/>
      <attribute name="name" type="NCName" use="required"/>
      <attribute name="value" type="expression:expression" use="required"/>
    </complexType>
  </element>

  <element name="precondition">
    <complexType>
      <attribute name="id" type="ID" use="optional" />
      <attribute name="test" type="expression:expression" use="required" />
    </complexType>
  </element>

  <element name="formula" substitutionGroup="xl:resource">
    <complexType mixed="true">
      <complexContent mixed="true">
        <extension base="xl:resourceType">
          <sequence>
            <element ref="formula:attribute"  minOccurs="0" maxOccurs="unbounded"/>
          </sequence>
          <attribute name="value" type="expression:expression" use="required"/>
          <attribute name="concept" type="expression:expression" use="optional"/>
          <attribute name="context" type="expression:expression" use="optional"/>
          <attribute name="unit" type="expression:expression" use="optional"/>
          <attribute name="precision" type="expression:expression" use="optional"/>
          <anyAttribute namespace="http://www.w3.org/XML/1998/namespace" processContents="lax"/>
        </extension>
      </complexContent>
    </complexType>
  </element>

  <element name="arc" substitutionGroup="xl:arc">
    <complexType>
      <complexContent>
        <extension base="xl:arcType">
          <attribute name="bindEmpty" type="boolean" use="required"/>
          <attribute name="bindAsSequence" type="boolean" use="required"/>
          <attribute name="name" type="QName" use="required"/>
        </extension>
      </complexContent>
    </complexType>
  </element>

</schema>	
D	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).
E	Acknowledgements (non-normative)
This document could not have been written without the contributions of many people including the participants in the XBRL Formula Working Group.
F	Document History (non-normative)
Date	Editor	Summary	
2006-12-18	Geoff Shuetrim	First internal working draft created, drawing extensively on the previous Formula specification drafts.	
2007-02-01	Hugh Wallis	Editorial to reflect Public Working Draft status