Working with the PresentableFactTree

A previous post introduced the presentable fact tree: a tree of facts from an XBRL instance arranged in parent-child relationships according to the information in a presentation linkbase. This blog post will describe the tree structure returned by a call to XbrlFragment.GetPresentableFactTree().

Presentable Fact Tree

The XbrlFragment.GetPresentableFactTree() method returns an object of a class called PresentableFactTree. The PresentableFactTree class has one property:

List<PresentableFactTreeNode> TopLevelNodes

This property is a list of top-level presentable tree nodes, each of which is represented by a class called PresentableFactTreeNode. Unlike traditional trees in computer science, which have a single “root” node at the top, presentation linkbases do not necessarily define a single “root” top level node. Gepsio, therefore, must prepare for the scenario in which the presentation linkbase has multiple “top-level” nodes and defines a list of top level nodes in a presentable fact tree.

Presentable Fact Tree Nodes

All of the information in a tree is captured in a set of tree node objects of class PresentableFactTreeNode. The PresentableFactTreeNode class has several properties:

  • PresentableFactTreeNode ParentNode
  • Fact NodeFact
  • string NodeLabel
  • List<PresentableFactTreeNode> ChildNode

Let’s look at each one in detail.

ParentNode

The ParentNode property is simply a reference to the current node’s parent in the tree. This value may be null if the current node is a top level node which has no parent.

NodeFact

The NodeFact property is a reference to the XBRL fact represented by this node.

Remember that the Fact class is a base class, and the fact is actually an object of either the Item class (for single-value facts) or Tuple (for multi-value facts). Check the derived class and proceed accordingly, because the base Fact class has no value information at that level.

It is important to understand that the NodeFact property may be null. Some XBRL taxonomies define abstract elements, which have no values. These abstract elements nevertheless appear in presentation linkbases as a soft of “placeholder” for a row in a presentation without a value of its own. Consider the following presentation linkbase fragment:

  <link:presentationLink xlink:type="extended" xlink:role="http://www.aigcorporate.com/role/DisclosureEquity">
    <link:loc xlink:type="locator" xlink:href="http://xbrl.fasb.org/us-gaap/2012/elts/us-gaap-2012-01-31.xsd#us-gaap_StockholdersEquityNoteAbstract" xlink:label="StockholdersEquityNoteAbstract" xlink:title="StockholdersEquityNoteAbstract" />
    <link:loc xlink:type="locator" xlink:href="http://xbrl.fasb.org/us-gaap/2012/elts/us-gaap-2012-01-31.xsd#us-gaap_StockholdersEquityNoteDisclosureTextBlock" xlink:label="StockholdersEquityNoteDisclosureTextBlock" xlink:title="StockholdersEquityNoteDisclosureTextBlock" />
    <link:presentationArc xlink:type="arc" xlink:arcrole="http://www.xbrl.org/2003/arcrole/parent-child" xlink:from="StockholdersEquityNoteAbstract" xlink:to="StockholdersEquityNoteDisclosureTextBlock" xlink:title="presentation: StockholdersEquityNoteAbstract to StockholdersEquityNoteDisclosureTextBlock" use="optional" order="10.0" preferredLabel="http://www.xbrl.org/2003/role/terseLabel" />
  </link:presentationLink>

This fragment is a real world example which references an element called “us-gaap_StockholdersEquityNoteAbstract”. This element is defined in the associated taxonomy as an abstract element, and there is no actual value in the XBRL instance with this element. In this case, the element’s label should be displayed when a fact is null. This brings us to …

NodeLabel

The NodeLabel property contains the label for the tree node. Gepsio automatically pulls this information from the label linkbase, if it exists. If a label cannot be found, then this value is the empty string. This property is always available, regardless of whether or not the NodeFact is populated.

ChildNode

The ChildNode property is a list of child presentable fact tree nodes relative to the current node.

Sample Code

Here is a bit of sample code that walks a presentable fact tree and outputs the facts found in the tree:

public void WalkPresentableTree()
{
    var xbrlDoc = new XbrlDocument();
    xbrlDoc.Load("MyXbrlInstance.xml");
    var firstFragment = xbrlDoc.XbrlFragments[0];
    var tree = firstFragment.GetPresentableFactTree();
    foreach (var currentNode in tree.TopLevelNodes)
        WalkPresentableTreeNode(currentNode, 0);
}

private void WalkPresentableTreeNode(PresentableFactTreeNode node, int depth)
{

    // Indent as necessary, according to depth, so that parent child relationships
    // are shown.
    for (var indent = 0; indent < depth; indent++)
        Debug.Write("    ");

    // If the tree node has a fact, then display it.
    if (node.NodeFact != null)
    {

        // Display item details, if this fact is actually an item.
        // Tuples are not supported in this code sample.
        if (node.NodeFact is Item)
        {
            var nodeItem = node.NodeFact as Item;
            Debug.Write(nodeItem.Name);
            Debug.Write(" ");
            Debug.Write(nodeItem.Value);
        }
    }
    else
    {

        // If there is no fact for this node, then display the label.
        Debug.Write(node.NodeLabel);
    }
    Debug.WriteLine("");

    // Recursively call into this same method for each of the node's
    // child nodes, increasing the depth by one so that the indenting
    // reflects the child nodes.
    foreach (var childNode in node.ChildNodes)
        WalkPresentableTreeNode(childNode, depth + 1);
}

An initial, un-optimized implementation of the presentable fact tree support has been checked in to Codeplex and will be available in binary form when the next CTP is released (tentatively scheduled for Sat 01 Aug 2015).

Advertisements

Introducing the Presentable Fact Tree

At a very high level, XBRL instances are sets of key/value pairs: the key is the fact and the value is the fact’s value:

Fact Value
EntityRegistrantName AMERICAN INTERNATIONAL GROUP INC
EntityCentralIndexKey 0000005272
DocumentType 10-Q
DocumentPeriodEndDate 2013-06-30

There is no inherent structure to the list of facts in an XBRL instance: the instance is simply a large table of facts and values. Gepsio exposes the Facts property from an XbrlFragment object to allow callers to get at this list of facts and their values.

However, from an accounting perspective, these facts do have relationships to each other, and some of the facts are higher level aggregated values representing some lower level facts. When these facts are displayed in forms such as Consolidated Balance Sheets, this relationship between facts is plainly visible. Take a look here at Google’s 10-Q statement from Jun 30 2012. Scroll down to the Financial Statements and see, for example, that Current assets includes

  • Cash and cash equivalents
  • Marketable securities
  • Total cash, cash equivalents, and marketable securities
  • Accounts receivable
  • Inventories
  • Receivable under reverse repurchase agreements
  • Deferred income taxes, net
  • Prepaid revenue share, expenses and other assets

XBRL supports a linkbase called the presentation linkbase, which describes the relationships between facts so that, with some code, the list of facts can be turned into a more presentable table with parent/child fact relationships shown as the facts would be shown on a financial statement. Gepsio has supported the reading of the presentation linkbase in previous CTPs, but never offered away to turn the raw list of facts into a representation of a parent/child relationship model which mirrors the data in the presentation linkbase.

Very shortly, a first cut at a new XbrlFragment method called GetPresentableFactTree() will be added to the Gepsio code. This method will return a tree-like structure that arranges an XBRL instance’s list of facts into a set of parent/child relationships based on the information in a presentation linkbase, all in one line of code (the linear Facts collection in an XbrlFragment will not be modified by this call and will still be available at all times). The code would look something like this:

var xbrlDoc = new XbrlDocument();
xbrlDoc.Load("aig-20130630.xml");
var firstFragment = xbrlDoc.XbrlFragments[0];
var tree = firstFragment.GetPresentableFactTree();

A future blog post will describe the structure returned by GetPresentableFactTree() and how developers can use it to build up fact-based displays which reflect the  information in a parent/child relationship.

Where Did The Segment Property Go?

The following email came into the Gepsio email inbox not long ago:

I upgraded to your latest release btw but it looks like the Segment object was removed. How do I access Dimensions and Segments now?
Thanks

The user had been using the Sep 2013 CTP [version 2.1.0.7] and had been using it to write code like this:

// this item has a dimension (grouped) 
if (item.ContextRef.Segment != null)
{
    foreach (System.Xml.XmlNode node in item.ContextRef.Segment)
    {
        //Insert_Dimension(FactItemID, node.Attributes["dimension"].Value, node.InnerText);
        ddi.NewRow(FactItemID, node.Attributes["dimension"].Value, node.InnerText);
    }
}

The short answer is that – oops! – the Segment property was moved from public visibility to internal visibility in the Nov 2014 CTP [2.1.0.8], and that change was retained in the May 2015 CTP [2.1.0.9]. It will be moved back to public visibility in the next CTP, but an explanation for the change is in order.

The Segment Property in the Sep 2013 CTP

In the Sep 2013 CTP, the public Segment property was a property of the Context class. It was of type System.Xml.XmlNode and was documented as follows:

The segment node defined for this context. If this context was not marked up with a segment node, then this property will return null.

This property was made available in support of section 4.7.3.2 of the XBRL 2.1 specification, which describes an optional <segment> child element of a <context> element:

The  <segment>  element is an optional container for additional mark-up that the preparer of an XBRL Instance SHOULD use to identify the business segment more completely in cases where the Entity identifier is insufficient. In general, the content of a  <segment>  will be specific to the purpose of the XBRL instance. Elements contained by the  <segment>  element MUST NOT be defined in the http://www.xbrl.org/2003/instance namespace. Also, they MUST NOT be in the substitution group for elements defined in the http://www.xbrl.org/2003/instance namespace. The  <segment>  element MUST NOT be empty.

The XBRL 2.1 specification does not associate any semantics with the <segment> element; therefore, Gepsio could not define an object model around this element, since it is documented as an optional container containing zero or more elements whose semantics were presumably documented elsewhere. Therefore, Gepsio could only expose the element, if it existed, as a generic XmlNode.

Introducing the Interface-Based XML Layer

On 18 July 2014, a changeset was checked in which changed Gepsio’s relationship to the .NET 3.5 XML DOM classes. This change was first published in a build in the Nov 2014 CTP and continued on in the May 2015 CTP. This change removed Gepsio’s direct dependency on the .NET 3.5 XML DOM classes and, instead, moved the support behind a set of internally-defined interfaces. The change introduced interfaces to handle all of the XML work, as well as classes that implemented the interface using the .NET 3.5 XML DOM classes. So, with this design, instead of Gepsio calling something like XmlDocument.Load() to load an XBRL document instance, it called an interface method called IDocument.Load(). The IDocument.Load() interface implementation called XmlDocument.Load() in its implementation.

The rationale behind moving Gepsio’s XML layer behind an interface was to make it easier to support other XML implementations in the future. The future of Gepsio, and its possible reach beyond purely .NET and possibly into other areas, whether it be as a Portable Class Library, as a library that would support Xamarin, or as a library that would support the Universal Windows Platform, means that Gepsio may need to be modified at its lowest level XML layer. For example, The Portable Class Library does not support the .NET 3.5 XML DOM classes. Instead, it supports only the LINQ-to-XML classes. Once XML is loaded, Gepsio is pretty portable, but the XML layer could potentially be a porting problem down the road should the XML runtime need to change.

Moving all of Gepsio’s low level XML needs behind an interface, and implementing the interface in a set of classes that Gepsio would actually be using, makes it easier to change the XML layer later on, should the need arise, without disturbing the rest of the Gepsio code base. Moving, for example, from the .NET 3.5 XML DOM classes to LINQ-to-XML would be a (theoretically) simple matter of implementing the internal XML interfaces in classes that used LINQ-to-XML. Gepsio’s higher levels of code – the XBRL semantics – would not need to change.

Interfaces and the Segment Property

The issue with the interface implementation with regards to the Segment property is that things like System.Xml.XmlNode, which were originally exposed as the type of the Segment property, are now behind an interface. With the XML interface design, Gepsio no longer sees a System.Xml.XmlNode object directly. Instead, it sees an internally-defined INode interface, and System.Xml.XmlNode is hidden behind the implementation of INode. With the interface design change, the Segment property in question would need to have its type changed from System.Xml.XmlNode to INode. The problem there is that INode is defined internally by Gepsio, and external callers, such as the code shown above, have no knowledge of INode. Failing that understanding, the Segment property could not be exposed, so the property was moved to be private in the Nov 2014 CTP.

The Road Forward

Since folks are, in fact, using the Segment property for Dimensions work (and, failing Gepsio’s first-party support for Dimensions, which needs to get on the project roadmap), then the Segment property will once again need to go public. Work will, therefore, progress in getting the XML interfaces documented so that people can use an internally-defined INode implementation to do work with segment nodes. This work is underway now.