1 Motivation (non-normative)
To effectively exchange business reporting information between a producing and a consuming application often requires the applications to perform validation on data types and values, apply consistency checks, test data quality, augment the data with calculated values and possibly corrections, and to provide feedback to the producing application that indicates the nature and severity of problems encountered. A producing application may also add calculated values and perform tests on its own outputs before sending results to consuming applications. Applications based on the exchange of spreadsheets that contain both data and formulas are common but present maintenance problems; here the intent is explicitly to separate the representation and location of formulas and validation criteria from a given instance.
These different functions are characteristic of many XBRL-enabled applications. That is because it is a goal of XBRL to allow applications to consume XBRL formatted business information no matter what its original source. Data entry validation (e.g., prohibiting dates such as February 31, 2001 from entering the system) is a familiar example of using a formula to flag errors, but the breadth and scope of formulas is much broader than this. Good information management practice generally recognizes that validations should be tested, adhered to, and corrections made as far “upstream” in an information supply chain as possible – recognizing, of course, that the same tests may be applied repeatedly as data makes its way from its many possible origins, to its many ultimate destinations.
Any general programming language could be used to perform computations on business data. However, there is regularity in business reporting information: regularity that is encoded in XBRL in instance constructs such as “facts,” “periods,” “entities,” and in taxonomies as items, definitions, and other relationships. Furthermore, applications that consume XBRL formatted data should be able to “publish the formulas” that govern documents containing XBRL data, so that producing applications can test and apply those formulas and thereby reduce delay, rework and retransmissions, and smooth and accelerate the flow of business reporting information.
Rule languages—in which rules are expressed as patterns to be matched and actions to be taken when the data matches the pattern—have a rich tradition and are nearly as old as computer science itself ([Newell, 1962]). They enjoyed a heyday in the 1980’s for the programming of “expert systems”, and today rule languages live on in languages such as Prolog, and in commercial products such as the Blaze Rule Engine [HNC] and JRules [ILOG]. Rule languages tend to be fairly compact and concise and resemble a database of logical sentences (“all people are mortal” “if X is a mountain, then the elevation of X must be positive”). They declare the rules to be obeyed, and an interpreter (or compiler) is responsible for efficiently executing the rules (matching patterns and executing actions) correctly when presented with incoming data.
Even if the goal of synthesizing information is set aside so as to merely detect violation of constraints, XML Schema [XSDL] itself is still not sufficient to this task because it allows the validation of individual data elements (“Revenues are a 12-digit nonnegative number”) and structural relationships (e.g., “an invoice must contain a header, a list of items, and an amount”) but does not express constraints between elements, also known as co-constraints (“if more than 10 dependents are claimed then Schedule K must be completed”). Besides, the nature of rules is that they generally compute a whole series of results, some of which may be considered fatal errors, others as warnings, others as merely informational; an XML Schema validator mainly detects fatal errors. Other general programming languages, including XML Schema Transformation [XSLT], could be pressed into service since they have the requisite pattern-action structure, but these neither take any account nor take any advantage of the constrained nature of XBRL instances, taxonomies, and so on.
XBRL-specific formulas are well motivated. The language would be, like XBRL itself, suitable for publishing and transporting between applications; it would exploit the XBRL language itself, and provide a concise and well constrained way of expressing common rules such as “Net Receivables cannot be negative,” “Net revenues are the difference between Gross revenues and Gross expenses,” “Unless income for the previous quarter was zero, income growth for the quarter is the ratio of the change in income between the current and previous quarter, divided by the income of the previous quarter,” and so on. The earliest discussions of XBRL acknowledged the need to express not only specific numeric facts (“1988 Revenue for TLA Inc. was $40m”), but also relationships among those facts (“TLA Inc. revenue consists of TBD Inc. revenue plus BFD Ltd. revenue less eliminations”) and general relationships (“The write down allowance for an asset in any year after 1993 is limited to 25% of its original purchase price”). There has now been sufficient experimentation and implementation experience with XBRL for the exchange of business reporting information in live and planned applications to have illustrated both the need for an extension to the language to meet this need, as well as illustrating deficiencies in schemes used to date and the typical patterns of usage and the limitations on what that language actually needs to cover. This information is advantageous to have because it limits the scope and guides the design of the language.
1.1 Terminology and formatting conventions
Terminology used in XBRL frequently overlaps with terminology from other fields. The terminology used in this document is summarised in Table 1.
Table 1: Terminology
|
abstract element, bind, concept, concrete element, context, Discoverable Taxonomy Set (DTS), duplicate items, duplicate tuples, element, entity, equal, essence concept, fact, instance, item, least common ancestor, linkbase, period, taxonomy, tuple, unit, taxonomy schema, child, parent, sibling, grandparent, uncle, ancestor, XBRL instance, c-equal, p-equal, s-equal, u-equal, v-equal, x-equal, minimally conforming XBRL processor, fully conforming XBRL processor. |
As defined in [XBRL]. |
||||
|
must, must not, required, shall, shall not, should, should not, may, optional |
See [RFC2119] for definitions of these and other terms. These include, in particular:
|
||||
|
expression |
An expression using constants, variables, arithmetic, logical, and functional operators. |
||||
|
formula |
An expression along with criteria that indicate the domain of each variable in that expression and how they are to be bound. |
||||
|
rule |
The term “rule” is not used in this version of the requirement, although it appeared previously as a synonym for “formula”. |
||||
|
variable |
A “variable” appears in expressions as a symbol that the application of a formula binds to a value, so that the expressions of that formula can be evaluated. |
||||
|
argument |
An “argument” of a formula is a formal parameter bound to some portion of an input instance. Some of the arguments will be identified as variables to be used in expressions. |
The following highlighting is used for positive examples:
Example 1: Example of an example
|
|
Counterexamples indicate incorrect or unsupported examples:
Example 2: Example of a counterexample
|
|
Non-normative editorial comments are denoted as follows and removed from final recommendations:
WcH: This highlighting indicates editorial comments about the current draft, prefixed by the editor’s initials.
Italics are used for rhetorical emphasis only and do not convey any special normative meaning.
Distinctively bracketed and coloured numbers {1.2.3} refer to that particular numbered section of the XBRL 2.1 Specification Recommendation [XBRL].
1.2 Normative status
This document is normative in the sense that any formula specification recommendations by XBRL International MUST satisfy the requirements as they are stated here.
This document version depends upon XBRL 2.1 Specification Recommendation [XBRL].
XBRL Specification 2.1 does not depend in any way upon this document.
1.3 Language independence
The official language of XBRL International’s own work products is English and the preferred spelling convention is UK English. Unless otherwise stated, XBRL specifications must not require XBRL users to use English in documentation, item, tuple, entity, scenario or any other elements.
2 Use cases
The general use case for an XBRL formula specification is the externalisation and publication of a set of formulas that will be applied by a consuming application:
· A financial regulator collecting quarterly balance sheets and income statements;
· A statistical agency collecting market valuations of various asset categories;
· A tax authority accepting electronic tax filings;
· A stock exchange accepting registration requests;
· A bank evaluating loan applications or checking loan covenants;
More specifically, there are general use cases that these consuming applications may have:
1. Test XBRL instances for consistency and signalling the failure of a formula, in the same sense that an inconsistent set of fact bindings for the summation-item arcs of a calculation linkbase signals an inconsistency.
2. Test XBRL instances for consistency and provide detailed messages for each formula that failed. In this case, general XML output for further processing and rendering as appropriate by an application is likely to be sufficient.
3. Creating a tuple-free XBRL instance based on existing XBRL instances. In this case, it is sensible for a formula processor to produce a valid XBRL instance. If producing applications verify that their own output will be accepted by those consuming applications, significant efficiencies are possible, particularly in a distributed environment such as the Internet.
4. Transforming, adjusting, or composing XBRL instances. By contrast with use case 3 in which fact order is not relevant, element order can be significant in tuples.
Use case 4 encompasses use case 3, which encompasses use case 2, which encompasses use case 1.
The examples are expressed as “consistent” and “inconsistent” fact sets for use cases 1 and 2, and as “before” and “after” fact sets and instances for use cases 3 and 4, along with a structured description of the relevant generalisation of the behaviour illustrated by that case.
The examples shown in the requirements all depend on a single taxonomy shown in Figure 1 consisting mainly of financial position and performance items.
Figure 1: Items Appearing in Examples
|
@name |
@type |
@periodType |
Label (en, standard) |
|
Assets |
monetaryItemType |
instant |
Assets |
|
CurrentAssets |
monetaryItemType |
instant |
Current Assets |
|
FixedAssets |
monetaryItemType |
instant |
Fixed Assets |
|
Equity |
monetaryItemType |
instant |
Equity |
|
Shares |
sharesItemType |
instant |
Shares |
|
Price |
monetaryItemType |
instant |
Price |
|
Earnings |
monetaryItemType |
duration |
Earnings |
|
AvgShares |
sharesItemType |
duration |
Average Shares |
|
PE |
pureItemType |
instant |
Price-Earnings Ratio |
|
ROE |
pureItemType |
instant |
Return on Equity |
|
EPS |
decimalItemType |
duration |
Earnings per Share |
|
AssetsEquity |
pureItemType |
instant |
Assets-to-Equity Ratio |
|
Rating |
integerItemType |
instant |
Rating |
|
AssetsOkay |
booleanItemType |
instant |
Assets Okay |
|
EquityOkay |
booleanItemType |
instant |
Equity Okay |
|
AssetsMessage |
stringItemType |
instant |
Assets Message |
|
AssetsLB |
booleanItemType |
instant |
Assets in Lower Bound |
|
AssetsUB |
booleanItemType |
instant |
Assets in Upper Bound |
|
AssetsLarge |
booleanItemType |
instant |
Assets not too Large |
|
AssetsSmall |
booleanItemType |
instant |
Assets not too Small |
|
IntangiblesPatents |
monetaryItemType |
instant |
Intangibles (Patents) |
|
IntangiblesClass |
stringItemType |
instant |
Intangibles Class |
|
IntangibleGross |
monetaryItemType |
instant |
Intangible Gross |
|
IntangibleReserve |
monetaryItemType |
instant |
Intangible Reserve |
|
IntangibleNet |
monetaryItemType |
instant |
Intangible Net |
|
IntangibleAsset |
tupleType |
|
Intangible Asset |
|
AutoWriteDown |
tupleType |
|
Automobile Write-Down |
|
AutoName |
tokenItemType |
duration |
Automobile Name |
|
AcquisitionDate |
dateItemType |
duration |
Acquisition Date |
|
WriteDownAllowance |
monetaryItemType |
duration |
Write-Down Allowance |
|
WDVBroughtForward |
monetaryItemType |
duration |
Write-Down Value Brought Forward |
|
UsefulLife |
durationItemType |
duration |
Useful Life |
All facts in the examples have a unitRef and contextRef drawn from the units and contexts shown in Figure 2 and Figure 4, respectively. The namespace prefix si refers to international standard scientific units.
Figure 2: Units Appearing in Examples
|
@id |
measure |
|
usd |
iso4217:USD |
|
gbp |
iso4217:GBP |
|
pure |
xbrli:pure |
|
shs |
xbrli:shares |
|
usdsh |
iso4217:USD/xbrli:shares |
|
gbpsh |
iso4217:GBP/xbrli:shares |
|
year |
si:year |
The namespace prefix co with elements aaa and bbb are used to distinguish segments of entity 444. The elements actual, budgeted and variance are used to distinguish scenarios.
Figure 3: Segments and Scenarios Appearing in Examples
|
prefix |
element |
|
co: |
<aaa/> |
|
co: |
<bbb/> |
|
co: |
<actual/> |
|
co: |
<budgeted/> |
|
co: |
<variance/> |
Figure 4: Contexts Appearing in Examples
|
@id |
entity/ @identifier |
entity/ segment |
period/ instant |
period/ startDate |
period/ endDate |
scenario |
|
c01 |
333 |
|
|
2003-01-01 |
2003-12-31 |
|
|
c02 |
333 |
|
2002-12-31 |
|
|
|
|
c03 |
333 |
|
2003-12-31 |
|
|
|
|
c04 |
444 |
|
|
2003-01-01 |
2003-12-31 |
|
|
c05 |
444 |
|
2003-12-31 |
|
|
|
|
c06 |
333 |
|
2003-12-31 |
|
|
|
|
c07 |
444 |
<geo>ON</geo> |
|
2003-01-01 |
2003-12-31 |
|
|
c08 |
444 |
<geo>ON</geo> |
2003-12-31 |
|
|
|
|
c09 |
444 |
<geo>MI</geo> |
|
2003-01-01 |
2003-12-31 |
|
|
c10 |
444 |
<geo>MI</geo> |
2003-12-31 |
|
|
|
|
c11 |
444 |
|
2003-12-31 |
|
|
<co:actual/> |
|
c12 |
444 |
|
2003-12-31 |
|
|
<co:budgeted/> |
|
c13 |
444 |
|
2003-12-31 |
|
|
<co:variance/> |
|
c14 |
444 |
|
|
1993-01-01 |
1993-12-31 |
|
|
c15 |
444 |
|
|
1995-01-01 |
1995-12-31 |
|
|
c16 |
333 |
|
2001-12-31 |
|
|
|
|
c17 |
444 |
<lob>paper</lob> |
|
2003-01-01 |
2003-12-31 |
|
|
c18 |
444 |
<lob>paper</lob> |
2003-12-31 |
|
|
|
|
c19 |
444 |
<lob>plastic</lob> |
|
2003-01-01 |
2003-12-31 |
|
|
c20 |
444 |
<lob>plastic</lob> |
2003-12-31 |
|
|
|
Note that contexts c06 and c03 are s-equal.
The data type of the content in any UsefulLife fact is assumed to be yearMonthDuration; the XBRL durationItemType does not specify whether fact content is yearMonthDuration or dayTimeDuration.
Each fact in this document also has a unique identifier such as f42; the identifiers are not relevant in any way to processing the facts or formulas, but the identifiers allow them to be referred to in the text.
Expressions are written in XML Path Language 2.0 [XPATH2] and are meant to be transparent for the example at hand, but are not prescriptive as to the expression language to be required. Some cases use the syntax of XML Query Language 1.0 [XQuery] to declare functions; as stated in [XPATH2], “XPath is designed to be embedded in a host language such as XSLT 2.0 or XQuery… XPath per se does not provide a way to declare functions, but a host language may provide such a mechanism.” The host language chosen in the examples is XQuery because it allows users to declare functions of their own.
3 Linkbase-related requirements
The requirements here specify the linkbase features that formulas must support in order to integrate fully with the rest of XBRL.
All these requirements are common to all four use cases.
3.1 A discoverable taxonomy set may include formulas
It must be possible to define a set of formulas in such a way that it can be part of one or more discoverable taxonomy sets {1.4}.
3.2 Formulas may require components of a DTS
Formulas refer to items and tuples defined in taxonomies {3}. Therefore it must be possible for a set of formulas to rely upon the presences of specific taxonomy schemas and linkbases in its processing environment.
It is not sufficient to rely on the schemaRef and linkbaseRef elements of an instance because the formulas may be computing results that are elements from an entirely different taxonomy schema. Example 3 shows a formula linkbase that has inputs from the taxonomy schema MDRM.xsd but computes results that are items in Form031results.xsd. An instance with a schemaRef only to MDRM.xsd is not sufficient for execution of the formulas. In effect the execution of formulas requires a DTS that is the union of its own DTS and the DTS of the instance in question.
Example 3: Relationship of an instance DTS and DTS of a set of formulas
|
|
3.3 Formulas may be partitioned into sets
Formulas maintained in the same taxonomy may provide alternative, possibly incompatible definitions for the same item. A formula is a relationship among two or more facts and so a set of formulas must use the same xlink:role attribute as used in XBRL to indicate which relationships participate in the same networks of relationships based on the value of the role {5.2}.
Example 4: Incompatible formulas are distinguishable.
EPS for some purposes is computed using the average number of shares during the earnings period, and for other purposes using the number of shares at the end of the period.
Formulas:
|
item |
test |
expression |
type |
matching |
|
EPS |
“method 1” |
($Earnings div $AvgShares) |
decimals=7 |
p-equal, c-equal. |
|
EPS |
“method 2” |
($Earnings div $Shares) |
decimals=7 |
p-equal; Shares context period/instant = Earnings context period/endDate. |
Use cases 1 and 2:
Consistent facts:
|
@id |
item |
@contextRef |
@unitRef |
@precision |
[content] |
|
f36 |
Earnings |
c01 |
usd |
INF |
11000 |
|
f11 |
AvgShares |
c01 |
shs |
INF |
55000 |
|
f29 |
EPS |
c01 |
usdsh |
INF |
0.2 |
Inconsistent Facts:
|
@id |
item |
@contextRef |
@unitRef |
@precision |
[content] |
|
f36 |
Earnings |
c01 |
usd |
INF |
11000 |
|
f11 |
AvgShares |
c01 |
shs |
INF |
55000 |
|
f82 |
EPS |
c01 |
usdsh |
9 |
-.183333333 |
Use cases 3 and 4:
Initial facts:
|
@id |
item |
@contextRef |
@unitRef |
@precision |
[content] |
|
f36 |
Earnings |
c01 |
usd |
INF |
11000 |
|
f11 |
AvgShares |
c01 |
shs |
INF |
55000 |
|
f17 |
Shares |
c03 |
shs |
INF |
60000 |
Result facts:
|
@id |
item |
@contextRef |
@unitRef |
@precision |
[content] |
|
f29 |
EPS |
c01 |
usdsh |
INF |
0.2 |
|
f67 |
EPS |
c01 |
usdsh |
9 |
0.183333333 |
In this example, only one of the two results should be computed, depending on whether the (set of) formulas labelled “method 1” or “method 2” is selected for processing. The xlink:role attribute may be an appropriate way to model this, since the evaluation of the condition does not depend in any way on the facts in the instance.
3.4 Formulas MAY be prohibited
An extension taxonomy MAY prohibit a formula in a base taxonomy {3.5.3.9.7.5}. The requirement does imply that formulas require a base/extension scheme like that used in taxonomies.
In order for one formula to prohibit another they must be identical, not just s-equal. Assuming that a formula set is implemented as a linkbase, a prohibiting arc MUST connect the same XML fragments as the original arc, and both the original and the prohibiting arc MAY connect multiple resources (formulas, variables, constants) by making the ID attribute required.
Example 5: Prohibiting a formula.
An extension {3.2} {3.5.3.9.7.5} of a set of formulas may need to change the method by which an item is computed in a base set of formulas. In this example, the simpler calculation of EPS is in the base set of formulas:
Formulas:
|
item |
test |
expression |
type |
matching |
|
EPS |
|
($Earnings div $Shares) |
decimals=7 |
p-equal; Shares context period/instant = Earnings context period/endDate. |
An extension set of formulas then prohibits that formula, and asserts a different one:
Formulas:
|
item |
test |
expression |
type |
matching |
|
|
|
|
|
|
|
EPS |
|
($Earnings div $AvgShares) |
decimals=7 |
p-equal, c-equal. |
Use cases 1 and 2:
Consistent facts:
|
@id |
item |
@contextRef |
@unitRef |
@precision |
[content] |
|
f36 |
Earnings |
c01 |
usd |
INF |
11000 |
|
f11 |
AvgShares |
c01 |
shs |
INF |
55000 |
|
f17 |
Shares |
c03 |
shs |
INF |
60000 |
|
f29 |
EPS |
c01 |
usdsh |
INF |
0.2 |
Inconsistent facts:
|
@id |
item |
@contextRef |
@unitRef |
@precision |
[content] |
|
f36 |
Earnings |
c01 |
usd |
INF |
11000 |
|
f11 |
AvgShares |
c01 |
shs |
INF |
55000 |
|
f17 |
Shares |
c03 |
shs |
INF |
60000 |
|
f83 |
EPS |
c01 |
usdsh |
9 |
.1833333333 |
Use cases 3 and 4:
Input facts:
|
@id |
item |
@contextRef |
@unitRef |
@precision |
[content] |
|
f36 |
Earnings |
c01 |
usd |
INF |
11000 |
|
f11 |
AvgShares |
c01 |
shs |
INF |
55000 |
|
f17 |
Shares |
c03 |
shs |
INF |
60000 |
Result facts:
|
@id |
item |
@contextRef |
@unitRef |
@precision |
[content] |
|
f29 |
EPS |
c01 |
usdsh |
INF |
0.2 |
In this example, the computation based on average number of shares is used and only one value of EPS is calculated.
3.5 Documentation of a formula may be included
Human-readable documentation that explains meaning of a formula in multiple languages may be included in each formula or set of formulas.
3.6 The representation of formulas should not require redundancy
This is a general principle applicable to most if not all representations. By analogy with the unit element in XBRL and the unitRef attribute, where a set of formulas is likely to share common information, the specification will use syntax that allows it to be specified just once and referred to in many formulas.
3.7 Formulas must only appear in linkbases associated with a taxonomy, consistent with the treatment of calculations, and not the instance.
Formulas in an instance are believed to irrevocably render XBRL instances useless from an archival standpoint because of differences in the results that different processors would derive results. The treatment of formulas for archiving must be the same as for calculation arcs.
4 Processing-related Requirements
The requirements here describe the processing semantics of formulas relative to input XBRL instances and outputs.
4.1 The result of applying formulas to an instance that is not XBRL-valid is not defined.
Authors may write formulas in such a way as to presume an XBRL-valid instance with respect to a known taxonomy schema.
This requirement is common to use cases 1, 2, 3, and 4.
4.2 Application of a set of formulas to an XBRL-valid instance MUST either fail or result in a well-formed XML instance.
One and only one processing iteration shall be performed in satisfying this requirement.
This requirement is common to use cases 1, 2, 3, and 4.
4.3 Application of a set of formulas to an XBRL-valid instance MUST either fail or result in another XBRL-valid instance.
Non-local properties of XBRL validity that would apply to the output instance—such as the testing of the requires‑element constraints {5.2.6.2.4}—can be difficult to guarantee on a local, incremental basis, so that in practice a formula processor would almost certainly require an XBRL validity checker.
One and only one processing iteration shall be performed in satisfying this requirement.
This requirement is common to use cases 3 and 4.
4.4 Any number of formulas may compute the value of any item.
Authors may write formulas in such a way as to provide multiple ways to derive a given fact. In practice authors should avoid writing formulas that bind the same set of facts to produce the same result facts, since the result facts may be duplicates or even contradictory.
This requirement is common to use cases 3 and 4.
4.5 All formulas in a DTS must be processed concurrently and without exception without regard to priority.
This requirement is common to use cases 1, 2 and 3, and does not apply to use case 4.
The firing order of formulas is implementation dependent. This cannot affect the semantics of the outcome, given requirement 6.7 below, “Formulas MUST only bind facts that are explicitly present in the input”
Formulas are to be processed one instance at a time. Processing the instances is implementation dependent and cannot affect the semantics of the outcome. There is no dependency between any formula and any other formula.
If formulas had priorities then they could be used to order formula application in cases where more than one formula applies, but since all must be evaluated, and the order of output elements is not relevant in XBRL, the XBRL semantics would not be impacted.
5 Expression-related Requirements
The requirements here refer to the common features needed in all three of:
· expressions that may be used to bind arguments to facts;
· expressions that may form a Boolean precondition of the formula after arguments are bound; and
· expressions that yield the result of processing a formula (use cases 2, 3 and 4).
Where it is not clear from context elsewhere in the document, these are called binding expressions, precondition expressions, and result expressions, respectively.
5.1 There MUST be only one expression language
From an adoption standpoint, it is not desirable to allow multiple expression languages since that would unnecessarily increase the implementation burden on a compliant formula processor.
Other standards (e.g., XSL and XPointer) have frameworks in which different expressions or scripting languages may be used; new recommendations incrementally extend the set of expressions that must be supported.
Therefore, the requirement that there must be only one expression language MAY be relaxed in a future version of the formula specification.
5.2 The expression language MUST be recognisable to a programmer of average skill.
A “programmer of average skill” means a person familiar with infix and functional notations and able to write spreadsheet formulas, SQL queries, or expressions in a 3GL or 4GL programming language.
This requirement will be satisfied if the expression language is a subset of a widely used language such as ECMAScript or XPATH 1.0. Expression syntaxes ruled out by this requirement include those used by APL, FORTH, LISP, PROLOG, etc.
5.3 The expression language MUST include operators that can select any node in the instance accessible from bound facts.
Fact-binding expressions, conditional expressions and result expressions must be able to operate (for example) on the units of measure, the contexts, and other parts of the input instance. This is believed to be difficult for the formula specification and therefore for an implementation, to prevent this accessibility than it is for an implementation to require it.
5.4 Expressions may include constants.
Expressions must be able to express any constant from the value space of XML Schema primitive data types [SCHEMA‑2].
5.5 Expressions MAY include mathematical operations.
Expressions must be able to express the following operations:
· Addition and subtraction of values;
· Division and modulus of values, both integer and real;
· Multiplication of values;
· Determine maxima and minima of a sequence of values;
· The range of string matching and modification operations made possible by regular expressions;
· All of the following relational operations, =, <, >, <=, >=, and != on numeric items and =, != on non-numeric items.
5.6 Expressions MAY include conditional expressions.
Formulas must be able to express the following operations:
· If, Then, Else
· Elseif
· Switch / Case
Conditional expressions and nested conditionals may test several conditions in sequence.
Example 6: Result expression contains a conditional.
In this example a continuous P/E ratio is mapped to one of three discrete values of Rating.
Formulas:
|
item |
test |
result expression |
type |
matching |
|
Rating |
|
if ($PE lt 5) then 1 else if ($PE gt 10) then 2 else 3 |
INF |
|
Use cases 1 and 2:
Consistent facts:
|
@id |
item |
@contextRef |
@unitRef |
@precision |
[content] |
|
f22 |
PE |
c02 |
pure |
INF |
-6.5 |
|
f39 |
Rating |
c03 |
pure |
INF |
3 |
Inconsistent facts:
|
@id |
item |
@contextRef |
@unitRef |
@precision |
[content] |
|
f21 |
PE |
c03 |
pure |
INF |
56 |
|
f84 |
Rating |
c03 |
pure |
INF |
2 |
Use cases 3 and 4:
Input facts:
|
@id |
item |
@contextRef |
@unitRef |
@precision |
[content] |
|
f21 |
PE |
c03 |
pure |
INF |
56 |
|
f22 |
PE |
c02 |
pure |
INF |
-6.5 |
Result facts:
|
@id |
item |
@contextRef |
@unitRef |
@precision |
[content] |
|
f39 |
Rating |
c03 |
pure |
INF |
3 |
|
f40 |
Rating |
c02 |
pure |
INF |
1 |
In principle, any conditional expression could be recast as a series of separate formulas with disjoint conditions (this example would require three formulas, with one having the condition “5 ≤ PE and PE < 10”).
5.7 Expressions MAY determine the minimum and maximum period that appear among the contexts in an instance.
Expressions may determine the latest and earliest startDate, endDate and instant appearing in the instance. This could also include the use of date expressions that include a function such as now() which would return the current instant as an ISO 8601 string.
Example 7: Formula applies only to the latest period in an instance.
Facts may match the formula only if they fall within a time period that is described as the “latest” period in the instance.
Formulas:
|
item |
test |
expression |
type |
matching |
|
AssetEquity |
($Equity gt 0) |
$Assets div $Equity |
precision=18 |
p-equal, u-equal, c-equal; Context must have a period that is the latest occurring in the input instance. |
Use cases 1 and 2:
Consistent facts:
|
@id |
item |
@contextRef |
@unitRef |
@precision |
[content] |
|
f01 |
Assets |
c02 |
usd |
INF |
100000 |
|
f03 |
Equity |
c02 |
usd |
INF |
17000 |
|
f86 |
AssetEquity |
c02 |
usd |
9 |
58.82352941 |
|
f13 |
Assets |
c03 |
usd |
INF |
43000 |
|
f15 |
Equity |
c03 |
usd |
INF |
26000 |
|
f31 |
AssetEquity |
c03 |
pure |
18 |
1.653846153846153846 |
Inconsistent facts:
|
@id |
item |
@contextRef |
@unitRef |
@precision |
[content] |
|
f13 |
Assets |
c03 |
usd |
INF |
43000 |
|
f15 |
Equity |
c03 |
usd |
INF |
26000 |
|
f87 |
AssetEquity |
c03 |
pure |
9 |
58.83252941 |
Use cases 3 and 4:
Input facts:
|
@id |
item |
@contextRef |
@unitRef |
@precision |
[content] |
|
f01 |
Assets |
c02 |
usd |
INF |
100000 |
|
f03 |
Equity |
c02 |
usd |
INF |
17000 |
|
f13 |
Assets |
c03 |
usd |
INF |
43000 |
|
f15 |
Equity |
c03 |
usd |
INF |
26000 |
Result facts:
|
@id |
item |
@contextRef |
@unitRef |
@precision |
[content] |
|
f31 |
AssetEquity |
c03 |
pure |
18 |
1.653846153846153846 |
In this example, one pair of facts (f01 and f03) evaluates the condition to false and the other (f13 and f15) evaluates it to true. The latest period among the inputs is the instance 2003‑12‑31.
This applies to use cases 1, 2, 3, and 4.
5.8 Expressions may test for the presence of a fact for any concept in any context.
The presence or absence of a fact may be tested.
See Example 6 for an example in a conditional expression, Example 24 for an example in binding expressions; Example 23 also indicates that Nil items may be tested for.
This applies to use cases 1, 2, 3, and 4.
5.9 All facts must be bound before an expression is evaluated.
Although in principle, expressions such as or(x,y,z) could be evaluated left-to-right and with x="true", neither y nor z would need to be bound, formula processing does not support this.
Example 8: Expression evaluation requires all facts to be bound.
Formulas:
|
item |
test |
expression |
type |
matching |
|
AssetsOkay |
|
$AssetsUB and $AssetsLB |
Boolean |
p-equal, c-equal. |
Facts:
|
@id |
item |
@contextRef |
@unitRef |
@precision |
[content] |
|
f49 |
AssetsUB |
c03 |
|
|
false |
Result:
|
@id |
item |
@contextRef |
@unitRef |
@precision |
[content] |
In this example, even though AssetsLB is not strictly needed to evaluate the expression, the output still should not contain the result that AssetsOkay is false
5.10 The behaviour of a formula processor MUST be defined in the case of an expression evaluation exception.
A formula will bind arguments to facts, and substitution of the arguments as variables in the expression allows the expression to be evaluated. The formula specification must indicate, in particular, what result if any is produced when the expression throws an exception when evaluated.
A try/catch mechanism would allow the formula author to control the behaviour on a case-by-case basis. This presumably though not always will include the generation of a human-readable error message.
This applies to use cases 1, 2, 3, and 4.
5.11 Constants MAY be named and defined inside a formula and referenced in its expressions.
Formulas often refer to constants that may appear locally.
Example 9: Formula uses a locally defined symbolic constant.
In this formula, lowerTolerance and upperTolerance are constants bound to “-500” and “500” respectively.
Formulas:
|
item |
test |
expression |
type |
matching |
|
AssetsOkay |
|
($lowerTolerance lt ($Assets - ($CurrentAssets + $FixedAssets)) and (($Assets – ($CurrentAssets + $FixedAssets) lt $upperTolerance) |
|
p-equal, u-equal and c-equal; |
Use cases 1 and 2 (AssetsOkay is not an explicit concept):
Consistent facts:
|
@id |
item |
@contextRef |
@unitRef |
Precision |
[content] |
|
f33 |
CurrentAssets |
c03 |
usd |
INF |
8000 |
|
f35 |
FixedAssets |
c03 |
usd |
INF |
35000 |
|
f48 |
Assets |
c03 |
usd |
INF |
43400 |
Inconsistent facts:
|
@id |
item |
@contextRef |
@unitRef |
Precision |
[content] |
|
f33 |
CurrentAssets |
c03 |
usd |
INF |
8000 |
|
f35 |
FixedAssets |
c03 |
usd |
INF |
35000 |
|
f13 |
Assets |
c03 |
usd |
INF |
44000 |
Use cases 3 and 4 (AssetsOkay is an explicit concept):
Input facts:
|
@id |
item |
@contextRef |
@unitRef |
Precision |
[content] |
|
f33 |
CurrentAssets |
c03 |
usd |
INF |
8000 |
|
f35 |
FixedAssets |
c03 |
usd |
INF |
35000 |
|
f13 |
Assets |
c03 |
usd |
INF |
44000 |
Result facts:
|
@id |
item |
@contextRef |
|
|
[content] |
|
f48 |
AssetsOkay |
c03 |
|
|
false |
5.12 Constants may be named and defined outside a formula and referenced in its expressions.
Sets of formulas often refer to constants that appear in several related formulas; there must be a way to define a constant whose scope is an entire set of formulas. There must be a means to limit the scope of such a constant, such as by using the xlink:role attribute.
Example 10: Formula uses a globally defined symbolic constant.
Here, tolerance is bound to “500” globally and so has the identical value in two different formulas, one for testing the upper bound (UB) and one for the lower bound (LB).
Formulas:
|
item |
test |
expression |
type |
matching |
|
AssetsUB |
|
($Assets - ($CurrentAssets + $FixedAssets)) lt $tolerance |
Boolean |
p-equal, u-equal and c-equal; |
|
AssetsLB |
|
$tolerance lt ($Assets - ($CurrentAssets + $FixedAssets)) |
Boolean |
p-equal, u-equal and c-equal; |
Use cases 1 and 2:
Consistent facts:
|
@id |
item |
@contextRef |
@unitRef |
Precision |
[content] |
|
f33 |
CurrentAssets |
c03 |
usd |
INF |
8000 |
|
f35 |
FixedAssets |
c03 |
usd |
INF |
35000 |
|
f13 |
Assets |
c03 |
usd |
INF |
44000 |
|
f49 |
AssetsUB |
c03 |
|
|
false |
|
f50 |
AssetsLB |
c03 |
|
|
true |
Inconsistent facts:
|
@id |
item |
@contextRef |
@unitRef |
Precision |
[content] |
|
f33 |
CurrentAssets |
c03 |
usd |
INF |
8000 |
|
f35 |
FixedAssets |
c03 |
usd |
INF |
35000 |
|
f13 |
Assets |
c03 |
usd |
INF |
44000 |
|
f89 |
AssetsUB |
c03 |
|
|
true |
Use cases 3 and 4:
Input facts:
|
@id |
item |
@contextRef |
@unitRef |
Precision |
[content] |
|
f33 |
CurrentAssets |
c03 |
usd |
INF |
8000 |
|
f35 |
FixedAssets |
c03 |
usd |
INF |
35000 |
|
f13 |
Assets |
c03 |
usd |
INF |
44000 |
Result facts:
|
@id |
item |
@contextRef |
|
|
[content] |
|
f49 |
AssetsUB |
c03 |
|
|
false |
|
f50 |
AssetsLB |
c03 |
|
|
true |
5.13 Functions MAY be named and expressions defined outside a formula and referenced in its expressions
Any function that is not “built in” to the expression language – for example, trigonometric functions – would either have to be defined repeatedly in every formula that needed it, or an intermediate item defined in the taxonomy whose only role would be to hold the result of the formula and then append that result to an instance so that its value could be bound in all formulas that may need it. Examination of UK Inland Revenue Tax Computation use cases, similar items on the FFIEC 031 and 041 forms, and consideration of many financial analysis routines, reveals that the same formulas are used again and again.
Example 11: Formula uses a globally defined function.
In this formula, there is a reference to an externally defined function:
declare function my:withinTolerance( $x as xdt:anyAtomicType, $y as xdt:anyAtomicType ) as xdt:boolean* { fn:abs( $x - $y) lt 500 }
Formulas:
|
item |
test |
expression |
type |
matching |
|
AssetsOkay |
|
my:withinTolerance ($Assets,($CurrentAssets + $FixedAssets)) |
Boolean |
p-equal, u-equal and c-equal; |
Use cases 1 and 2:
Consistent facts:
|
@id |
item |
@contextRef |
@unitRef |
Precision |
[content] |
|
f33 |
CurrentAssets |
c03 |
usd |
INF |
8000 |
|
f35 |
FixedAssets |
c03 |
usd |
INF |
35000 |
|
f13 |
Assets |
c03 |
usd |
INF |
44000 |
Inconsistent facts:
|
@id |
item |
@contextRef |
@unitRef |
Precision |
[content] |
|
f33 |
CurrentAssets |
c03 |
usd |
INF |
8000 |
|
f35 |
FixedAssets |
c03 |
usd |
INF |
35000 |
|
f13 |
Assets |
c03 |
usd |
INF |
44000 |
Use cases 3 and 4:
Input facts:
|
@id |
item |
@contextRef |
@unitRef |
Precision |
[content] |
|
f33 |
CurrentAssets |
c03 |
usd |
INF |
8000 |
|
f35 |
FixedAssets |
c03 |
usd |
INF |
35000 |
|
f13 |
Assets |
c03 |
usd |
INF |
44000 |
Result facts:
|
@id |
item |
@contextRef |
|
|
[content] |
|
f48 |
AssetsOkay |
c03 |
|
|
false |
5.14 Functions MAY have their scope defined to apply to only a subset of formulas in a set
There must be a way to limit the scope of such a function definition to be usable only within a certain set of formulas, such as by using the xlink:role attribute.
Example 12: Different formulas bind the same name to different functions.
In two different formulas, there are references to externally defined functions that apply in different rules within the same set. The rules are not distinguished by an arithmetic test but rather by an indicator such as xlink:role.
|
scope |
function |
|
Taxation Enforcement |
declare function tax:withinTolerance( $x as xdt:anyAtomicType, $y as xdt:anyAtomicType ) as xdt:boolean* { fn:abs( $x - $y) lt 500 }
|
|
Securities Enforcement |
declare function sec:withinTolerance( $x as xdt:anyAtomicType, $y as xdt:anyAtomicType ) as xdt:boolean* { fn:abs( $x - $y) lt 5000000 } |
Formulas:
|
item |
test |
expression |
type |
matching |
|
AssetsOkay |
$Enforcement eq “Securities Enforcement” |
tax:withinTolerance ($Assets,($CurrentAssets + $FixedAssets)) |
Boolean |
p-equal, u-equal and c-equal; |
|
EarningsOkay |
$Enforcement eq “Taxation Enforcement” |
sec:withinTolerance ($Equity,$EquityPrev + $Earnings) |
Boolean |
p-equal, u-equal; “EquityPrev” refers to a context in the year previous to that of “Equity”.
The duration-type period of “Earnings” must begin at the instant represented by “EquityPrev”. |
Both computations have 1000-dollar errors but only one of them results in a false value.
Use cases 1 and 2 (AssetsOkay and EarningsOkay are not explicit concepts):
Consistent facts:
|
@id |
item |
@contextRef |
@unitRef |
Precision |
[content] |
|
f33 |
CurrentAssets |
c03 |
usd |
INF |
8000 |
|
f35 |
FixedAssets |
c03 |
usd |
INF |
35000 |
|
f13 |
Assets |
c03 |
usd |
INF |
44000 |
Inconsistent facts:
|
@id |
item |
@contextRef |
@unitRef |
Precision |
[content] |
|
f03 |
Equity |
c02 |
usd |
INF |
17000 |
|
f09 |
Earnings |
c01 |
usd |
INF |
9000 |
|
f11 |
Equity |
c03 |
usd |
INF |
27000 |
Use cases 3 and 4 (AssetsOkay and EarningsOkay are explicit concepts):
Input facts:
|
@id |
item |
@contextRef |
@unitRef |
Precision |
[content] |
|
f33 |
CurrentAssets |
c03 |
usd |
INF |
8000 |
|
f35 |
FixedAssets |
c03 |
usd |
INF |
35000 |
|
f13 |
Assets |
c03 |
usd |
INF |
44000 |
|
f03 |
Equity |
c02 |
usd |
INF |
17000 |
|
f09 |
Earnings |
c01 |
usd |
INF |
9000 |
|
f11 |
Equity |
c03 |
usd |
INF |
27000 |
Result facts:
|
@id |
item |
@contextRef |
|
|
[content] |
|
f48 |
AssetsOkay |
c03 |
|
|
True |
|
f74 |
EarningsOkay |
c03 |
|
|
False |
5.15 Expression evaluation exceptions MAY be caught to produce a result
The expression language must support a try/catch or other exception handling mechanism and allow the expression to produce a result. The following is only an example result and is not meant to be normative for all formulas.
Example 13: Catching an exception
Formulas:
|
item |
test |
expression |
matching |
|
EPS |
|
Try ($Earnings div $AvgShares) Catch Exception Return <EPS>0</EPS> |
p-equal, c-equal. |
Use cases 1 and 2:
Consistent facts:
|
@id |
item |
@contextRef |
@unitRef |
@precision |
[content] |
|
f36 |
Earnings |
c01 |
usd |
INF |
11000 |
|
f72 |
AvgShares |
c01 |
shs |
INF |
0 |
|
f90 |
EPS |
c01 |
usdsh |
INF |
0 |
Inconsistent facts:
|
@id |
item |
@contextRef |
@unitRef |
@precision |
[content] |
|
f36 |
Earnings |
c01 |
usd |
INF |
11000 |
|
f72 |
AvgShares |
c01 |
shs |
INF |
0 |
|
f37 |
EPS |
c01 |
usdsh |
c01 |
0.16363636 |
Use cases 3 and 4:
Input facts:
|
@id |
item |
@contextRef |
@unitRef |
@precision |
[content] |
|
f36 |
Earnings |
c01 |
usd |
INF |
11000 |
|
f72 |
AvgShares |
c01 |
shs |
INF |
0 |
Result facts:
|
@id |
item |
@contextRef |
@unitRef |
@precision |
[content] |
|
f90 |
EPS |
c01 |
usdsh |
INF |
0 |
Note that the units, context and precision of the result remain the same as if the calculation had not thrown an exception; only its content is different.
6 Fact-binding Requirements
The requirements here refer to the features needed to bind facts to the arguments for the formula as they appear in the condition and result expressions.
6.1 Formulas MAY filter the input facts to which they apply according to relationships between facts in one or more contexts.
The facts bound in a formula may have different contexts.
Contexts are related to one another using the following orderings:
· The relationship “after” that partially orders periods;
· The subset relationship “during” between periods;
· The subset relationship implied between an entity and its segments {4.7.3};
· The subset relationship implied between an empty (universal) scenario and a scenario with additional discriminators {4.7.4}.
Example 14: Formula binds items that are p-equal and u-equal in identical contexts
An important type of formula involves a mathematical operator applied to a pair of items when they are p-equal, c-equal and u-equal.
Formulas:
|
item |
test |
expression |
type[1] |
matching |
|
Assets |
|
$CurrentAssets + $FixedAssets |
INF |
p-equal, c-equal and u-equal |
Use cases 1 and 2:
Consistent facts:
|
@id |
item |
@contextRef |
@unitRef |
Precision |
[content] |
|
f33 |
CurrentAssets |
c03 |
usd |
INF |
8000 |
|
f34 |
FixedAssets |
c03 |
usd |
INF |
35000 |
|
f13 |
Assets |
c03 |
usd |
INF |
43000 |
Inconsistent facts:
|
@id |
item |
@contextRef |
@unitRef |
Precision |
[content] |
|
f33 |
CurrentAssets |
c03 |
usd |
INF |
8000 |
|
f34 |
FixedAssets |
c03 |
usd |
INF |
35000 |
|
f48 |
Assets |
c03 |
usd |
INF |
43400 |
Input facts:
|
@id |
item |
@contextRef |
@unitRef |
Precision |
[content] |
|
f33 |
CurrentAssets |
c03 |
usd |
INF |
8000 |
|
f34 |
FixedAssets |
c03 |
usd |
INF |
35000 |
Result facts:
|
@id |
item |
@contextRef |
@unitRef |
Precision |
[content] |
|
f13 |
Assets |
c03 |