No Semantics to Context References

This email came into the Gepsio inbox recently:

I’ve been playing around with the library. My first exercise for myself is trying to reconstruct the financial statements. I thought I’d group Facts by time periods. The ContextRefNames were not what I expected. There were overlaps in names like FD2015XXX, D2015XXX, I2015XXX. Do you know the difference between the prefixes? I’m using Whole Foods https://www.sec.gov/Archives/edgar/data/865436/000086543615000177/0000865436-15-000177-index.htm

Is there a particular convention that the contextrefnames follow? I had a look at Walmart and they use a similar, but different convention.

Unfortunately, the answer is “no”.

Context IDs and references have no meaning. They are syntax, not semantics. Context reference names are arbitrary and have meaning only to link items within the individual document instances.

Section 4.7.1 of the XBRL 2.1 specification discusses the “id” attribute of a <context> element:

Every  <context>  element MUST include the  @id attribute. The content of the  @id attribute MUST conform to the [XML] rules for attributes with the ID type (http://www.w3.org/TR/REC-xml#NT-TokenizedType). The  @id attribute identifies the context (see  Section 4.7) so that it may be referenced by item elements.

The specification does not impose any semantics on the contents of the ID attribute.

Instance Documents, Schemas, and Linkbase Documents

A Gepsio user writes:

So reading through your blog and the discussions, I’ve come to realize one big thing that I’ve probably been missing so far — the other documents (Calculations, Schema, Definitions, Label, Presentation) that are listed on the EDGAR site are valuable to the comprehension of the XBRL document, correct? Is there some tutorial on how to load all of the documents into one session and use the corresponding references between them to produce a more robust result?

The short answer is that Gepsio detects and reads all of those ancillary files (called linkbase documents) for you, without you having to do anything but load the XBRL instance. Gepsio does the rest.

Let’s take some time and explore the longer answer. First, we will take a look at how XBRL defines the relationship between instance documents, schemas, and linkbase documents. That will be followed up with a look at how Gepsio uses and exposes the data from the various linkbase documents.

XBRL Relationship Between Instance Documents, Schemas, and Linkbase Documents

An XBRL document instance contains a reference to a schema 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:dei="http://xbrl.us/dei/2009-01-31"
    xmlns:xbrli="http://www.xbrl.org/2003/instance"
    xmlns:fds="http://www.factset.com/2010-11-30"
    xmlns:iso4217="http://www.xbrl.org/2003/iso4217"
    xmlns:us-gaap="http://xbrl.us/us-gaap/2009-01-31"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
>
  <link:schemaRef xlink:type="simple" xlink:href="fds-20101130.xsd" />

The schema, in turn, contains references the various linkbase documents:

<schema
  xmlns="http://www.w3.org/2001/XMLSchema"
  xmlns:xbrli="http://www.xbrl.org/2003/instance"
  xmlns:link="http://www.xbrl.org/2003/linkbase"
  xmlns:xlink="http://www.w3.org/1999/xlink"
  targetNamespace="http://www.factset.com/2010-11-30"
  xmlns:fds="http://www.factset.com/2010-11-30"
  elementFormDefault="qualified"
  attributeFormDefault="unqualified"
  xmlns:us-types="http://xbrl.us/us-types/2009-01-31"
>
  <annotation>
    <appinfo>
      <!-- snip -->
      <link:linkbaseRef
          xlink:type="simple"
          xlink:href="fds-20101130_pre.xml"
          xlink:role="http://www.xbrl.org/2003/role/presentationLinkbaseRef"
          xlink:arcrole="http://www.w3.org/1999/xlink/properties/linkbase"
          xlink:title="Presentation Links, all"
      />
      <link:linkbaseRef
          xlink:type="simple"
          xlink:href="fds-20101130_cal.xml"
          xlink:role="http://www.xbrl.org/2003/role/calculationLinkbaseRef"
          xlink:arcrole="http://www.w3.org/1999/xlink/properties/linkbase"
          xlink:title="Calculation Links, all" 
      />
      <link:linkbaseRef
          xlink:type="simple"
          xlink:href="fds-20101130_lab.xml"
          xlink:role="http://www.xbrl.org/2003/role/labelLinkbaseRef"
          xlink:arcrole="http://www.w3.org/1999/xlink/properties/linkbase"
          xlink:title="Label Links, all"
      />
    </appinfo>
  </annotation>

The XBRL instance document is the “starting point” of this chain. The XBRL instance document references the schema, and the schema references the linkbase documents.

Gepsio Loading Instance Documents, Schemas, and Linkbase Documents

Because the XBRL instance document is the “starting point” of the document relationship chain, Gepsio can figure out all of the references when the XBRL instance document is loaded. Gepsio users load an XBRL instance document with the following code:

var MyXbrlDoc = new XbrlDocument();
MyXbrlDoc.Load("MyXbrlDoc.xml");

Gepsio does all of the work to load any referenced schemas and linkbase documents during the loading process automatically. (This is part of the appeal of Gepsio: freeing developers from having to chase down all of these references manually.)

Gepsio Exposing Data from Instance Documents and Schemas

Gepsio’s automatic loading of referenced schemas and linkbase documents is fine, but the real key is to be able to see the loaded reference data.

Referenced schemas are available as a collection in the loaded document’s fragments:

var MyXbrlDoc = new XbrlDocument();
MyXbrlDoc.Load("MyXbrlDoc.xml");
foreach(var currentFragment in MyXbrlDoc.XbrlFragments)
{
    foreach(var currentSchema in currentFragment.Schemas)
    {
        // schema information is available in the
        // "currentSchema" object
    }
}

Once the schema is available, information from the various linkbase documents is available in various collections found on the schema object.

Gepsio Exposing Data from Calculation Linkbases

Information from referenced calculation linkbases are available as a collection in the schema:

var MyXbrlDoc = new XbrlDocument();
MyXbrlDoc.Load("MyXbrlDoc.xml");
foreach(var currentFragment in MyXbrlDoc.XbrlFragments)
{
    foreach(var currentSchema in currentFragment.Schemas)
    {
        var currentCalculationLinkbase = currentSchema.CalculationLinkbase;
        if(currentCalculationLinkbase != null)
        {
            foreach(var currentCalculationLink in currentCalculationLinkbase.CalculationLinks)
            {
                // calculation link information is available in the
                // "currentCalculationLink" object
            }
        }
    }
}

Each calculation link in the calculation linkbase document is available from this collection.

Gepsio Exposing Data from Definition Linkbases

Information from referenced definition linkbases are available as a collection in the schema:

var MyXbrlDoc = new XbrlDocument();
MyXbrlDoc.Load("MyXbrlDoc.xml");
foreach(var currentFragment in MyXbrlDoc.XbrlFragments)
{
    foreach(var currentSchema in currentFragment.Schemas)
    {
        var currentDefinitionLinkbase = currentSchema.DefinitionLinkbase;
        if(currentDefinitionLinkbase != null)
        {
            foreach(var currentDefinitionLink in currentDefinitionLinkbase.DefinitionLinks)
            {
                // definition link information is available in the
                // "currentDefinitionLink" object
            }
        }
    }
}

Each definition link in the definition linkbase document is available from this collection.

Gepsio Exposing Data from Label Linkbases

Information from referenced label linkbases are available as a collection in the schema:

var MyXbrlDoc = new XbrlDocument();
MyXbrlDoc.Load("MyXbrlDoc.xml");
foreach(var currentFragment in MyXbrlDoc.XbrlFragments)
{
    foreach(var currentSchema in currentFragment.Schemas)
    {
        var currentLabelLinkbase = currentSchema.LabelLinkbase;
        if(currentLabelLinkbase != null)
        {
            foreach(var currentLabelLink in currentLabelLinkbase.LabelLinks)
            {
                // label link information is available in the
                // "currentLabelLink" object
            }
        }
    }
}

Each label link in the label linkbase document is available from this collection.

Gepsio Exposing Data from Presentation Linkbases

Information from referenced presentation linkbases are available as a collection in the schema:

var MyXbrlDoc = new XbrlDocument();
MyXbrlDoc.Load("MyXbrlDoc.xml");
foreach(var currentFragment in MyXbrlDoc.XbrlFragments)
{
    foreach(var currentSchema in currentFragment.Schemas)
    {
        var currentPresentationLinkbase = currentSchema.PresentationLinkbase;
        if(currentPresentationLinkbase != null)
        {
            foreach(var currentPresentationLink in currentLabelLinkbase.PresentationLinks)
            {
                // presentation link information is available in the
                // "currentPresentationLink" object
            }
        }
    }
}

Each presentation link in the presentation linkbase document is available from this collection.

Working With the IFRS for SME Taxonomy

The following message just came in to the Gepsio Facebook page:

Hello, I am a student and I am writing a simple XBRL application for my thesis. I am new at XBRL and I have some questions and I thought maybe you could help me.

I want to create an XBRL instance document using IFRS SME taxonomy. My first question is – do I have to create my own XBRL schema or can I just connect my instance document with the official IFRS taxonomy file? If so how does it connect to calculation and presentation linkbases? I don’t see any references in IFRS .xsd file. In the example provided by the organisation they created schema for the example, as well as presentation/calculation/definition/label xml files. Do I have to do the same? What is the point of using the official taxonomy If I have to create everything myself? I thought that I create my own files only when I want to extend the existing taxonomy.

And when I finally create my own xbrl file can I validate it with gepsio? Or does it only allow me to parse the XBRL file and get all it’s elements but later I have to validate it myself?

Thank you very much for any help. If you don’t have time to answer me maybe you can point me to someone/some place where I can find answers. I am trying to find answers in the internet but for someone who is just starting with XBRL it is very confusing.

Let’s start with a quick review of a couple of terms before answering the questions.

IFRS stands for International Financial Reporting Standards.  The IFRS Foundation is an independent, not-for-profit organization working in the public interest. Their primary mission is to develop a single set of high quality, understandable, enforceable and globally accepted International Financial Reporting Standards (IFRS) based upon clearly articulated principles. The organization maintains a Web site here.

SME stands for Small and Medium-Sized Entities. SMEs do not need to worry about certain reporting concepts, such as earnings per share, interim financial reporting, and segment reporting. SMEs also do not typically need an option to revalue property, equipment, or intangibles. The IFRS believes that about 95% of the companies around the world fall into this category. The IFRS maintains a Web site for SMEs here.

Back to the questions:

do I have to create my own XBRL schema or can I just connect my instance document with the official IFRS taxonomy file?

You will probably want to create your own schema file (a standard XSD file) and import the IFRS for SME schema into your schema file. The IFRS publishes the IFRS for SME schema at http://xbrl.ifrs.org/taxonomy/2014-03-05/ifrs_for_smes_entry_point_2014-03-05.xsd, and recommends a namespace of ifrs-smes. You should be able to import it from within your own project’s schema. Your project’s schema will look something like this:

<xsd:schema ... xmlns:ifrs-smes="http://xbrl.ifrs.org/taxonomy/2014-03-05/ifrs-smes">
    <xsd:import
        namespace="http://xbrl.ifrs.org/taxonomy/2014-03-05/ifrs-smes"
        schemaLocation="http://xbrl.ifrs.org/taxonomy/2014-03-05/ifrs_for_smes_entry_point_2014-03-05.xsd" />
    ...
</xsd:schema>

Your XBRL instance could import the IFRS for SME schema directly, but creating your own schema file gives you a place to import additional schemas, should your project need to do so later on. Your XBRL instance will reference your schema, which will import the IFRS for SME schema as shown above.

If so how does it connect to calculation and presentation linkbases?

The linkbases are referenced in a schema as well. If you will be creating your own schema, as recommended above, then you already have a place to put these additional references. Linkbase references of any kind are placed in the <appinfo> section of a schema file and are referenced with a <linkbaseRef> element. Here is a real-world example:

<xsd:schema
    targetNamespace="http://www.aigcorporate.com/20130630"
    attributeFormDefault="unqualified"
    elementFormDefault="qualified"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:aig="http://www.aigcorporate.com/20130630"
    xmlns:us-gaap="http://fasb.org/us-gaap/2012-01-31"
    xmlns:us-roles="http://fasb.org/us-roles/2012-01-31"
    xmlns:ref="http://www.xbrl.org/2006/ref"
    xmlns:xbrldt="http://xbrl.org/2005/xbrldt"
    xmlns:nonnum="http://www.xbrl.org/dtr/type/non-numeric"
    xmlns:xl="http://www.xbrl.org/2003/XLink"
    xmlns:us-gaap-att="http://xbrl.us/us-gaap/attributes"
    xmlns:currency="http://xbrl.sec.gov/currency/2012-01-31"
    xmlns:link="http://www.xbrl.org/2003/linkbase"
    xmlns:invest="http://xbrl.sec.gov/invest/2012-01-31"
    xmlns:num="http://www.xbrl.org/dtr/type/numeric"
    xmlns:xlink="http://www.w3.org/1999/xlink"
    xmlns:country="http://xbrl.sec.gov/country/2012-01-31"
    xmlns:us-types="http://fasb.org/us-types/2012-01-31"
    xmlns:negated="http://www.xbrl.org/2009/role/negated"
    xmlns:stpr="http://xbrl.sec.gov/stpr/2011-01-31"
    xmlns:attributeFormDefault="unqualified"
    xmlns:dei="http://xbrl.sec.gov/dei/2012-01-31"
    xmlns:xbrli="http://www.xbrl.org/2003/instance"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
>
    <xsd:annotation>
        <xsd:appinfo>
            <link:linkbaseRef
                xlink:type="simple"
                xlink:href="aig-20130630_pre.xml"
                xlink:role="http://www.xbrl.org/2003/role/presentationLinkbaseRef"
                xlink:arcrole="http://www.w3.org/1999/xlink/properties/linkbase"
            />
            <link:linkbaseRef
                xlink:type="simple"
                xlink:href="aig-20130630_cal.xml"
                xlink:role="http://www.xbrl.org/2003/role/calculationLinkbaseRef"
                xlink:arcrole="http://www.w3.org/1999/xlink/properties/linkbase"
            />
            <link:linkbaseRef
                xlink:type="simple"
                xlink:href="aig-20130630_def.xml"
                xlink:role="http://www.xbrl.org/2003/role/definitionLinkbaseRef"
                xlink:arcrole="http://www.w3.org/1999/xlink/properties/linkbase"
            />
            <link:linkbaseRef
                xlink:type="simple"
                xlink:href="aig-20130630_lab.xml"
                xlink:role="http://www.xbrl.org/2003/role/labelLinkbaseRef"
                xlink:arcrole="http://www.w3.org/1999/xlink/properties/linkbase"
            />

Combining this answer with the previous answer, you should create a schema that will reference any linkbases you might want and will import the IFRS for SME schema, like this:

<xsd:schema ... xmlns:ifrs-smes="http://xbrl.ifrs.org/taxonomy/2014-03-05/ifrs-smes" ...>
    <xsd:annotation>
        <xsd:appinfo>
            <!-- linkbase references go here -->
        </xsd:appinfo>
    </xsd:annotation>
    <xsd:import
        namespace="http://xbrl.ifrs.org/taxonomy/2014-03-05/ifrs-smes"
        schemaLocation="http://xbrl.ifrs.org/taxonomy/2014-03-05/ifrs_for_smes_entry_point_2014-03-05.xsd" />
    ...
</xsd:schema>

Do I have to do the same? What is the point of using the official taxonomy If I have to create everything myself? I thought that I create my own files only when I want to extend the existing taxonomy.

You’re not creating your own schema to rebuild everything from scratch. You’re creating your own schema to pull all of these references together into a single package. Your schema simply becomes a “container” for all of these import statements and references. You don’t need to go through the work of redefining everything that these documents already define; instead, you can simply reference the work that has already been done by others. Your schema imports these items to leverage the existing work.

And when I finally create my own xbrl file can I validate it with gepsio? Or does it only allow me to parse the XBRL file and get all it’s elements but later I have to validate it myself?

Gepsio reads, and validates, XBRL. It reads the XBRL in as standard XML, and then applies all of the semantic rules defined by XBRL to ensure that what was imported is valid, not only according to XML standards, but also to all of the semantics defined by the XBRL specification. No, you won’t have to validate the XBRL yourself. Gepsio does all of that and reports on any validation errors that it finds.

Discovering Relationships between Revenue Facts

I recently came across the following XBRL question on Stack Overflow:

How can we know beforehand the number of names that can a business fact in XBRL receive on XBRL instance documents?

For example if we want to find the Revenue of companies by looking into XBRL instances for this business fact alone we can meet different names for this same fact as:

us-gaap:Revenues

us-gaap:SalesRevenue

us-gaap:SalesRevenueNet

The target is to find out a finite amount of names that every business fact can receive and then for every business fact loop all these names until we fine the one that is in the instance document.

is there a lexicon if you will where it has all of these names into one file? This is a theoretical question but requires technical expertise.

And most importantly since there are many lookalike names for a business fact can a name in one XBRL instance mean one fact and on the other instance document mean another business fact?

After a bit of prodding, I discovered that the root question was “why is revenue represented by many different facts in the taxonomy?”

The elements are different because they refer to different things. The SalesRevenueNet element is defined as follows:

Total revenue from sale of goods and services rendered during the reporting period, in the normal course of business, reduced by sales returns and allowances, and sales discounts.

The Revenues element is defined as follows:

Amount of revenue recognized from goods sold, services rendered, insurance premiums, or other activities that constitute an earning process. Includes, but is not limited to, investment and interest income before deduction of interest expense when recognized as a component of revenue, and sales and trading gain (loss).

(I can’t find an element in the US GAAP taxonomy named SalesRevenue, so I can’t comment on that one.)

The SalesRevenueNet element is a value summed from other elements, including Sales Revenue, Goods, Net, Shipping and Handling Revenue, Sales Revenue, Shipping, Net, and several other elements. The SalesRevenueNet element is, in turn, an item in the summation of the Revenues element, which also includes elements such as Financial Services Revenue. In algebraic terms, the calculation of the SalesRevenueNet item looks like this:

SalesRevenueNet = SalesRevenueGoodsNet + ShippingAndHandlingRevenue + ... 

The calculation of the Revenue item looks like this:

Revenue = SalesRevenueNet + FinancialServicesRevenue 

The XBRL Taxonomy Viewer is a helpful tool for providing a better view into some of these relationships. To see more, start the Taxonomy Viewer and do the following:

  1. When the XBRL Taxonomy Viewer is first launched, an “Open Taxonomy” dialog will appear. The dialog will contain a tree view listing all of the taxonomies supported by the viewer. The root of the tree is a folder labeled “XBRL US Public”, and one of the nodes beneath the root node is called “SEC Approved Taxonomies”.
  2. Expand the “SEC Approved Taxonomies” node, if it is not already expanded. Several child nodes will be listed, and one of the child nodes is labeled “2013 US GAAP Taxonomy (2013-01-31)”.
  3. Expand the “2013 US GAAP Taxonomy (2013-01-31)” node, if it is not already expanded. Several child nodes will be listed, and one of the child nodes is labeled “All Taxonomies”.
  4. Select the “All Taxonomies” node and click the “Open” button. The site will refresh with information about the taxonomy you have selected.
  5. At the bottom of the page, in the “Search” tab of the “Tools” pane, type in the name of an element (such as SalesRevenueNet) and click the “Search” button.
  6. Click on the element name in the Search Results list. After a bit of time, the pane in the upper right will refresh with information about the element you selected, such as labels, references, and calculation information.