Support Added for Calculation Arcs with Destination Labels Referencing Multiple Locators

I have just checked in a change to Gepsio that correctly validates calculation arcs that use destination labels that reference more than one locator.

Take a look at the following calculation link:

<calculationLink xlink:type="extended" xlink:role="http://www.xbrl.org/2003/role/link">

    <loc xlink:type="locator" xlink:href="397-ABC.xsd#A" xlink:label="summationItem" />

    <loc xlink:type="locator" xlink:href="397-ABC.xsd#B" xlink:label="contributingItem" />

    <loc xlink:type="locator" xlink:href="397-ABC.xsd#C" xlink:label="contributingItem" />

    <calculationArc
        xlink:type="arc"
        xlink:arcrole="http://www.xbrl.org/2003/arcrole/summation-item"
        xlink:from="summationItem"
        xlink:to="contributingItem" weight="1"
    />

</calculationLink>

This example, taken from the 397.00 conformance test in the XBRL-CONF-CR3-2007-03-05 conformance suite, defines a calculation arc that arcs from “summationItem” to “contributingItem”. The issue here is that there are two locators that use the “contributingItem” label:

• 397-ABC.xsd#B


• 397-ABC.xsd#C

Both of these locators must participate in the calculation arc. In the current CTP of Gepsio, only the fact referenced by the first locator is used to validate the calculation arc. With the new code, both facts referenced by both locators are used to validate the calculation arc.

This improved functionality will be available in the next CTP to released (which I am currently targeting for release in the next week or so).

Calculation Validation Location Bug Fixed

I have checked in code that fixes a bug in the validation of calculation arc values in Gepsio.

In the current CTP, the value of a xlink:href attribute of a locator element for a calculation arc is used to find the appropriate contributing concept. This is in error; in fact, the xlink:label attribute must be used instead. This bug hasn’t been caught until now because many of the XBRL documents in XBRL-CONF-CR3-2007-03-05 conformance suite use the same value for the xlink:href and label attributes. The 305.07 test, for example, references a calculation linkbase document that includes markup as follows:

<loc
    xlink:type="locator"
    xlink:href="305_07_decimals_test.xsd#decimals_Land"
    xlink:label="decimals_Land"
/>

As you can see, the resource ID of the value of the xlink:href attribute (decimals_Land) matches the value of the xlink:label attribute (decimals_Land), so it didn’t matter which value Gepsio used to find the correct element.

The 395.01 test, however, uses different location markup:

<loc
    xlink:type="locator"
    xlink:href="SummationItem.xsd#CurrentAsset"
    xlink:label="labelCurrentAsset"
    xlink:title="CurrentAsset"
/>

In this markup, the resource ID of the value of the xlink:href attribute (CurrentAsset) does not match the value of the xlink:label attribute (labelCurrentAsset) and Gepsio’s use of the resource ID is in error. Gepsio must use the value of the xlink:label attribute to find the correct element.

This bug has been fixed and will be available in the next CTP of Gepsio (which I am currently planning on releasing on Nov 01 2011).

Essence Alias Support Complete

I have just checked in code that completes Gepsio’s support of the XBRL essence alias concept. All of the essence alias conformance tests found in the XBRL-CONF-CR3-2007-03-05 conformance test suite (numbered with the 392 prefix) now behave as expected when parsed by Gepsio.

The next CTP of Gepsio will include all of this work and will correctly validate essence aliases found in XBRL documents.

Dates Available For Instant Period Contexts

I have just checked in a change to the Context class that will appear in the next CTP. The Context class now includes a public property called InstantDate, which exposes a DateTime value. The value of the InstantDate property for a Context reflects the date given for an instant period. This value is valid only when the Context reflects an Instant period. You will be able to write code like the following:

if(CurrentContext.InstantPeriod == true)
{
    var ContextDate = CurrentContext.InstantDate;
}

Facts, Items and Tuples

The current CTP of Gepsio (which, as of this writing, is the Feb 2011 CTP) exposes a collection of Fact objects as a property in an XbrlFragment. With this arrangement, you can write code like this:

var MyXbrlDocument = new XbrlDocument();
MyXbrlDocument.Load("xbrldata.xml");
foreach(var CurrentFragment in MyXbrlDocument.XbrlFragments)
{
    foreach(var CurrentFact in CurrentFragment.Facts)
    {
        // Ooh! An XBRL fact!
    }
}

I have been working on adding support for tuples in the next CTP, and, in doing so, have come to realize that this scenario is incomplete.

The Fact class in the current CTP is a standalone class. It doesn’t inherit from any other class, nor is it a base class for a derived class. The issue with the current CTP is that the only facts that it reads and exposes are single-value facts. Any tuples in the XBRL document are ignored and not included as a Fact instance.

In actuality, the XBRL specification supports two types of facts:

• single-value facts, called items


• multiple-value facts, called tuples

The next CTP will provide support for tuples, and, as such, Gepsio’s understanding of a fact will be more complete. In the next CTP, the Fact class will remain, but it will serve as a base class for a new class called Item and another new class called Tuple:

public class Fact
{
    // magic happens here
}

public class Item : Fact
{
    // more magic happens here
}

public class Tuple : Fact
{
    // even more magic happens here
}

Fact collections will remain in place, but Fact items can be examined to determine whether they are, in fact, items or tuples. This updated design will allow Gepsio to detect tuples in loaded XBRL documents and perform the appropriate work needed to expose tuples to Gepsio clients.

Rounded Values of Essence Aliased Facts Now Checked

I have just checked in code that will be released with the next CTP of Gepsio. The code validates the rounded values (that is, fact values with any applicable rounding and truncation applied) of essence aliased facts and throws an exception if those values do not match.

For example, consider the following XBRL document:

<xbrl xmlns="http://www.xbrl.org/2003/instance" xmlns:link="http://www.xbrl.org/2003/linkbase" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:example="http://example.com/xbrl/taxonomy/EssenceAlias" xmlns:iso4217="http://www.xbrl.org/2003/iso4217" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://example.com/xbrl/taxonomy/EssenceAlias EssenceAlias.xsd">
    <link:schemaRef xlink:href="EssenceAlias.xsd" xlink:type="simple"/>
    <unit id="u1">
        <measure>iso4217:USD</measure>
    </unit>
    <context id="c1">
        <entity>
            <identifier scheme="www.example.com">example</identifier>
        </entity>
        <period>
            <instant>2003-03-31</instant>
        </period>
    </context>
    <example:CurrentDeferredIncomeTaxExpense contextRef="c1" unitRef="u1" precision="4">100.0</example:CurrentDeferredIncomeTaxExpense>
    <example:ForeignDomesticIncomeTaxExpense contextRef="c1" unitRef="u1" precision="3">100</example:ForeignDomesticIncomeTaxExpense>
    <example:TaxExpense contextRef="c1" unitRef="u1" precision="3">200</example:TaxExpense>
</xbrl>

Now suppose that the CurrentDeferredIncomeTaxExpense and TaxExpense facts are paired in an essence alias relationship, as shown in the following linkbase document:

<?xml version="1.0" encoding="UTF-8"?>
<linkbase xmlns="http://www.xbrl.org/2003/linkbase" xmlns:xbrll="http://www.xbrl.org/2003/linkbase" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.xbrl.org/2003/linkbase ../lib/xbrl-linkbase-2003-12-31.xsd">
    <definitionLink xlink:type="extended" xlink:role="http://www.xbrl.org/2003/role/link">
        <loc xlink:type="locator" xlink:href="EssenceAlias.xsd#TaxExpense" xlink:label="labelTaxExpense" xlink:title="TaxExpense"/>
        <loc xlink:type="locator" xlink:href="EssenceAlias.xsd#ForeignDomesticIncomeTaxExpense" xlink:label="labelForeignDomesticIncomeTaxExpense" xlink:title="ForeignDomesticIncomeTaxExpense"/>
        <loc xlink:type="locator" xlink:href="EssenceAlias.xsd#CurrentDeferredIncomeTaxExpense" xlink:label="labelCurrentDeferredIncomeTaxExpense" xlink:title="CurrentDeferredIncomeTaxExpense"/>
        <definitionArc xlink:type="arc" xlink:arcrole="http://www.xbrl.org/2003/arcrole/essence-alias" xlink:from="labelTaxExpense" xlink:to="labelCurrentDeferredIncomeTaxExpense" priority="0"/>
        <definitionArc xlink:type="arc" xlink:arcrole="http://www.xbrl.org/2003/arcrole/essence-alias" xlink:from="labelTaxExpense" xlink:to="labelForeignDomesticIncomeTaxExpense" priority="0"/>
    </definitionLink>
</linkbase>

The XBRL document is invalid, because the two facts are in an invalid essence alias relationship. The relationship is invalid because the rounded values of the facts differ. In the current CTP, this issue is not reported by Gepsio. Starting with the next CTP, this issue will be reported during validation through an XbrlException thrown back to the caller. The exception will contain a message describing the mismatched values. For the document above, Gepsio will provide a message that reads as follows:

Facts named TaxExpense are defined as being in an essence alias relationship with facts named CurrentDeferredIncomeTaxExpense. However, the fact with ID  has a rounded value of 200, which differs from the fact with ID , which has a rounded value of 100. These two facts are therefore not in a valid essence alias relationship.

(Gepsio will include the fact IDs in the message. The document shown above has no IDs for the facts, so that part of the message is empty.)

Calculation Arc Validation Errors Are Common?

I ran across this tweet from a gentleman named Tom Gleeson about Gepsio's support for calculation arcs. Gepsio was failing to validate one of Oracle's XBRL documents posted through EDGAR. Although the Feb 2011 Gepsio CTP has passed the the Section 320 Calculation Binding tests in the XBRL-CONF-CR3-2007-03-05 conformance suite, I was initially confident in Gepsio's calculation arc validation code, though I wouldn't be surprised to find an issue that the tests don't cover. I'm certainly not smug enough to say "Gepsio must be right and the document must be wrong".

In this follow-up tweet, Tom alludes to the fact that Gepsio failed to validate one of the document's calculation arcs but also mentions that this is a "unfortunately very common" problem. In another follow-up tweet, he mentions that this same data is viewable in Arelle without any problems.

I was intrigued by Tom's comment that calculation arc validation errors are a common problem. Since I am still learning about XBRL and the community in which it lives, I wanted to open some questions for discussion:

1. Are calculation arc validation errors a common problem within documents generated by the XBRL community, or is this simply an issue that will resolve itself as Gepsio matures?
2. Would it be beneficial, as Tom suggests in a post, for Gepsio to support various "levels of correctness" whereby, in a more lenient validation mode, validation errors are overlooked?

Your comments are welcome and encouraged! Simply add a comment to this blog post.

I will mention that, in the general case, Gepsio validates the document after most (if not all) properties have been populated. This implies that, if you place a try exception block around the code that loads an XBRL document into Gepsio, and the catch block catches an XbrlException instance that references a problem with the validation, your code may still be able to carry on with at least some of its work, since many of the XbrlFragment properties will be populated and ready for use. The XbrlDocument instance should, in the general case, be in a known, stable state that will allow for its continued use in code. (This suggests that Gepsio should distinguish between exceptions that keep the XbrlDocument instance in a stable state from exceptions that have destabilized the loaded object model - I'll consider that idea for a future version of Gepsio.)

Special thanks to Tom for trying Gepsio and for alerting me to the issue!