Friday, September 30, 2011

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.

Thursday, September 29, 2011

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.)