In This Chapter
Sorting out common causes of confusion
Providing hard-to-find and often-overlooked key information
Delving into important technical aspects
Such as we want to, we can’t cover every conceivable aspect of XBRL m V W in a topic this size. In this chapter, we help you understand ten or so things that would clutter and complicate a basic explanation of XBRL, but are useful to know.
Covering the Basics of XLink
XBRL makes heavy use of XLink, the XML Linking language. (You can read the XLink specification at www.w3.org/TR/xlink.) You can spend your entire professional career using XBRL and never have to understand anything about XLink. But XLink does provide useful features that may be helpful to you. The XLink specification and what exactly XLink provides can be challenging to grasp. For those who have never worked with XLink, particularly technical people who will need to understand it, an introduction to XLink can help you understand what XLink does and why it’s important.
The hardest thing to understand about XLink is the physical components — lots of details go into making XLink’s functionality work. We don’t go into the details of how XLink physically works; you can get that from the XBRL and the XLink specifications. We do provide the highlights, however.
What XLink provides is actually quite simple: connections between resources. It also is a mechanism for defining resources that add information to an XBRL taxonomy or XBRL instance.
XLink provides a standard way of connecting resources. That standard way is XML. XBRL could have defined its own approach to creating needed connections between resources, but XBRL chose to leverage the standard XLink rather than create its own approach for communicating information about these connections.
You can use the following pieces of XLink to create connections between XBRL concepts (relations) or between an XBRL concept and additional information of some sort (resources):
Linkbases are physical XML files that contain extended links.
Extended links are contained within linkbases, and within an extended link are locators, arcs, and resources. Extended links have an xlink:type attribute value of extended.
Locators point to things — in XBRL’s case, usually concepts — in an XBRL taxonomy and resources within an extended link. However, locators can really point to anything, typically within some XML file. Locators have an xlink:type attribute value of locator.
Arcs connect locators together. Arcs connect two locators forming a relation, or they can do things such as connect a concept to a resource, adding information about a concept. Arcs have an xlink:type attribute value of arc.
Resources contain additional information. Resources have an xlink:type attribute value of resource.
Listing 22-1 shows you what the XML inside a linkbase looks like. Listing 22-1: Guts of a Linkbase
In Listing 22-1, you see a linkbase that contains a labelLink extended link composed of one locator, one arc, and one label resource. We don’t go into more depth because it would mean explaining intimate technical details, which isn’t our goal. We simply want to introduce linkbases should you choose to further explore them.
Knowing How XBRL Uses XLink Roles
The three different types of roles provided by XLink and used by XBRL are commonly confused. For XBRL purposes, XBRL taxonomy schemas define all these roles. XLink requires no such definitions, but XBRL does. Here are the three different types of roles:
Extended link roles: Extended links can have a role attribute, the value of which is called an extended link role. XBRL uses extended link roles to define and differentiate networks of relations or resources.
Resource roles: Resources can have a role attribute, the value of which is referred to as a resource role. Resource roles are used to categorize resources. For example, an English label, such as Cash and Cash Equivalents, would be defined in an XLink resource. That resource can have a role, such
as http://www.xbrl.org/2003/role/terseLabel, that categorizes that label as a specific type of label, a terse label in our example.
Arc roles: Arcs can have a role attribute, the value of which is referred to as an arc role. Arc roles are used to categorize arcs. For example, the relation between Cash and Current Assets would be created by using an XLink arc. That arc role can have a role, such as www.xbrl.org/2003/ arcrole/summation-item on a calculation arc, categorizing that arc.
Comparing XLink Extended
Links and XBRL Networks
Another common mistake is to confuse XLink extended links and XBRL networks. An XBRL network is something that XBRL defines. Extended links are something defined by XLink. XLink extended links are the means, the syntax, used to create an XBRL network.
The difference between the two is this: An XBRL network consists of one or more XLink extended links, all of which have the same XBRL type (presentation, calculation, definition, label, reference, or other type), and all of which have the same extended link role attribute value. You can have only one network of an XBRL type with the same extended link role attribute value within an XBRL DTS. Any number of physical XLink extended links can make up an XBRL network. Don’t make the common mistake of referring to extended links when you’re really referring to an XBRL network of a certain type.
Using Tuples to Express Compound Facts
Simple facts basically hold one value (see Chapter 4). Compound facts are made up of one or more simple facts or other compound facts and are expressed in XBRL in the form of what is known as a tuple. Tuples physically bind facts together to form compound facts. You create this binding within a taxonomy schema. Tuples are XML Schema complex types.
Here’s an example to help you see what tuples do: Suppose that you want to express information about the salary and bonuses paid to a company director. Well, a company can have more than one director. For example, suppose that you have two directors, Clark Kent and Lois Lane. Clark had a salary of $20,000 and bonuses of $10,000. Lois had a salary of $40,000 and bonuses of $20,000. How do you communicate in an XBRL fact which salary and which bonuses go with which director?
Well, that is where tuples come in. Tuples bind the name of the director, that director’s salary, and that director’s bonuses together so that XBRL instances users know which salary and bonuses go with which director. But first you have to create the bindings within a taxonomy schema. Listing 22-2 shows the definition of a tuple within a taxonomy schema.
Listing 22-2: Definition of a Tuple within an Taxonomy Schema
Notice the element Director with the value xbrli:tuple for the substitu tionGroup. That concept binds together the concepts DirectorName, DirectorSalary and DirectorBonuses, which you can see in the preceding taxonomy schema fragment.
The best way to understand the role tuples play is to look at fact values within an XBRL instance. We do so first without and then with tuples to show you the situation tuples address. Listing 22-3 shows a fragment of an XBRL instance without tuples.
Listing 22-3: XBRL Instance Fragment without Tuples
In Listing 22-3, you can see the concepts DirectorName and Director Salary each two times. You’re smart and may be able to figure out which facts go together. But a computer program has no way to understand that the first DirectorName and DirectorSalary go together. Likewise for the second. However, if you look at Listing 22-4, which shows the tuple Director, you can understand which sets go together.
Listing 22-4: XBRL Instance Fragment with Tuples
In Listing 22-4, you can see the physical binding that tuples provide, nesting the facts that go together within the tuple Director.
Creating Segment and Scenario Contextual Information
An area of confusion for many XBRL users is the segment and scenario elements of the context element found in XBRL instances. (Chapters 4 and 16 cover the basics of using these pieces of an XBRL instance’s context.) These two elements act in exactly the same way. Both are quite flexible, allowing literally XML as content other than elements of the XBRL 2.1 Specification namespace.
To express segment and scenario information today, you can use XBRL Dimensions or create your own XML schema, which defines concepts you can use.
The XBRL Dimensions approach for defining the XML that goes into the segment and scenario elements within a context is provided as a module of XBRL (see Chapter 16).
The other approach is to define your own XML schema. You can figure out the details from an example at www.xbrlsite.com/patterns/ 20 0 5-07-07/Basic Calculation-instance.xml.
To avoid having to type these long links. This takes you to a landing page where you can click the link you need.
We’d like you to understand these two key points:
To get anything into the segment and scenario element, you need a user interface. If you can put literally any XML into those concepts, you need what basically amounts to an XML editor to enter that information. Basically, users have to create the XML, which they then somehow use in the segment and scenario elements.
In order to get users to put the correct information into the segment and scenario concepts, you basically have to write a specification to define how a user would do so.
* Only after you define how your XML schema would be used can you then create a mechanism for constraining that information.
Your XML schema won’t be able to express hierarchies of relations between the elements you define that are understandable to XBRL.
Basically, what we’re saying is that if you want to create your own XML schema for the contents of the segment or scenario context elements, you’d literally have to duplicate what XBRL Dimensions has already created.
Listing 22-5 shows an example of a context element that uses XML Schema defined segment and scenario element contents.
Listing 22-5: An Example of a Context Element
XBRL Dimensions solves these and other issues you’d run into in defining an XML schema for segment and scenario element content.
XBRL Dimensions is probably the best alternative to use 99 percent of the time. Rarely will XBRL Dimensions not meet your needs. You can create your own approach, but with flexibility comes responsibility. If you choose not to use XBRL Dimensions, you have a lot of responsibility for making things work correctly.
Another aspect to the use of the segment and the scenario elements is trying to figure out exactly what goes into the segment element and what goes into the scenario element. The XBRL Specification is vague in this area, and people disagree as to what goes where. The fact is that it doesn’t matter which of the two elements you use. For example, the US GAAP Taxonomy Architecture settled on always using the segment element to contain XBRL Dimensions information and never allowing scenario to be used at all. That decision solves the problem of figuring out which to use. Using only one of these elements, segment, or scenario eliminates taxonomy creators from having to figure out whether they should use segment or scenario.
The key point to take away is that providing content that segment or scenario context elements use can be somewhat complicated at this stage of XBRL’s evolution. When in doubt, the best thing to do is use XBRL Dimensions. If that approach doesn’t seem to work, get a really good XBRL consultant to help you figure out how to create a solution that will meet your needs.
Using XBRL Footnotes to Add Comments
XBRL instances can also contain what are basically comments but are referred to in XBRL as footnotes. The XBRL instance uses XBRL footnotes as comments or notations that refer to one or more fact values. These footnotes can contain what amounts to XHTML markup as the comment, which can make for a richly expressed comment.
XBRL footnotes are a resource-type linkbase contained within an XBRL instance. A footnoteLink extended link within a linkbase within the XBRL instance contains footnote resources. This linkbase operates just like any other resource-type linkbase with one slight difference: The locators point to the id attribute of a fact contained within your XBRL instance, rather than a concept within an XBRL taxonomy schema.
Listings 22-6 and 22-7 show an example of an XBRL footnote as it would exist within an XBRL instance. Listing 22-6 shows the facts. Notice the id attributes contained in each fact.
Listing 22-6: Facts with ID Attributes Used by Footnotes
Listing 22-7 shows the resource-type linkbase that expresses the XBRL footnote.
Listing 22-7: Footnotes within an XBRL Instance_
XBRL users have suggested using XBRL footnotes for all sorts of things in many different ways. XBRL instance creation and viewing software supports these uses somewhat inconsistently at this stage of XBRL’s evolution.
Although XBRL footnotes exist, use them with caution.
Using Resources to Add Information
Something commonly missed by XBRL users is the fact that you can define your own linkbase resources using XBRL. You can do so using several different approaches. Examining the reference linkbase offers some clues as to these different approaches as does the Generic Linkbase Specification (see Chapter 16), which provides even more power in the area of adding resources to an XBRL taxonomy.
The first question you may have is why you would even want to add information to an XBRL taxonomy. Well, the reason is that often XBRL taxonomy creators have lots of additional information (metadata) that they’d like to connect to an XBRL taxonomy, but XBRL doesn’t seem to have a spot to hold that information. Well, actually, XBRL does have spots to hold that additional information.
As an example, take a look at how the reference element, which is a linkbase resource, works. Creating a reference will help reveal the pros and cons of some easy approaches and some more sophisticated approaches to adding information to any XBRL taxonomy.
You may want to refer to the section “Covering the Basics of XLink,” earlier in this chapter, to understand what resources are. Also, Chapter 4 is helpful in understanding the coming discussion.
Listing 22-8 shows a simple reference resource, which a reference linkbase would contain.
Listing 22-8: Reference Resource Element
We don’t want to get into a lengthy discussion about the syntax of a reference element within a reference linkbase. We focus here on the parts of a reference. The bold <ref:Name> XML element in Listing 22-8 is a reference part. Reference parts are special XBRL elements that you can use within a reference element.
You know that an element is a reference part because its substitionGroup attribute has the value link:part. You define these parts within a taxonomy schema. For example, the link part in Listing 22-8 was defined in this taxonomy schema made available by XBRL International www.xbrl.org/2 0 04/ref-2004-08-10.xsd.
If you open that URL and look at it, you can find that part element’s definition. Be sure to notice the substitutionGroup, which is how these parts are differentiated from XBRL concepts and other taxonomy schema contents.
Here are the important things for you to understand about different approaches to defining additional information for your XBRL taxonomy:
You can create your own proprietary approach to adding information to your XBRL taxonomy. However, an XBRL processor certainly wouldn’t understand the approach you’ve created, so you have to write code in order to link your additional information to the XBRL taxonomy you’re using. Writing code means getting programmers involved, which takes time and costs money. An example of this approach is to simply put this additional information within a relational database table and somehow connect the relational database table to the XBRL taxonomy.
You can add information by defining your own reference parts. Okay, this approach is a bit of a hack, but we mention it for a specific reason. Reference parts are defined within a taxonomy schema that becomes part of your DTS. After defining a reference part, you can use those reference parts within the reference element. XBRL processors are required to read any reference part that you add; they’ll understand these parts. Therefore, you can define any reference parts you desire, and an XBRL processor will be able to work with those reference parts and the information they contain, connecting them directly to concepts within your XBRL taxonomy. Reference parts don’t have to necessarily relate to references. This is the hack. You can use reference parts to define what would amount to any data table, and you can use XBRL to connect information in that table to an XBRL taxonomy, and then an XBRL processor, without any modification, can use that table! That’s the point. You get a spot to hold your additional information (XBRL will see it as a reference linkbase), but if you’re using what you created, say, internally to your organization, who cares whether you put something else in the reference linkbase? You created a mechanism for adding information to your taxonomy without writing one single line of code or involving a programmer!
You can add information by defining your own resource-type linkbase using the generic linkbase specification. XBRL allows you to actually add any type of information structure you can express in XML as a resource. All you do is define an XML schema for the information model that you want to maintain within your new resource. If you’re familiar with XML Schema, you’ll know how to do this task. But realize two important things if you use the generic linkbase approach. The first is simply the fact that you can express literally anything. The second is that just because you do so doesn’t mean that an XBRL processor will understand the resource you defined, nor is it required to. That means having to involve a programmer and writing code. You’ll write less code than implementing a proprietary approach to connecting to your proprietary information format because XBRL does provide a framework you can leverage.
Time after time, we see creators of XBRL taxonomies desiring to connect additional information to their XBRL taxonomy, but they tend to do it in proprietary ways, commonly using some sort of relational database. That approach is fine in many circumstances, but an easier way is to use XBRL itself to express this additional information. If you’re building an internal system, using the reference linkbase hack we describe can help you achieve what you need — in many cases, without writing a single line of code! If you’re a stickler for creating a solution for adding information to an XBRL taxonomy more by the topic, XBRL can still help you to a large degree; the generic linkbase provides you with helpful functionality for adding information to your XBRL taxonomy. The downside with the generic linkbase approach is that, in many cases, you’ll have to write some code to read that information.
Adding New Types of Relations
Adding new types of relations is easy using the definition linkbase. All you do is define your own arc role to express the type of relation, and you can go to town and express any sort of relation you may desire. If, for some reason, you need a lot more expressive power than the definition linkbase can provide, use the Generic Linkbase Specification.
A great example of using the definition linkbase to add relation information is the XBRL Dimensions Specification. Read that specification at www.xbrl. org/Specification/XDT-REC-2 0 06-0 9-18.htm and look at the XML Schemas that XBRL Dimensions defined. It’s an excellent example of extending the power of XBRL to express new types of relations. If you need to add relations, reverse-engineering XBRL Dimensions is a good guide to getting a quality result.
Expressing Blocks of Information
Representing a discrete fact value is simple using XBRL — for example, the discrete fact value of, say, 1234, for the concept Cash for a specific period. But what about more complex information structures, which are sometimes referred to as blocks of text? Listings 22-9 and 22-10 show two different types of blocks of text that are representative of what you may encounter.
Listing 22-9: Block of Text: A Table of Information
Listing 22-10: Block of Text: A Paragraph of Information
Listing 22-9 is what amounts to a table of information. Listing 22-10 is a paragraph of text, or what is sometimes referred to as prose. You can express both of these blocks of text as discrete values using XBRL, breaking the table or the paragraph into individual pieces and then creating taxonomy concepts to express each individual piece of information. XBRL Dimensions or tuples are helpful in turning tables and prose into discrete information pieces. But sometimes, for some reason, you don’t want to break information into discrete pieces.
These tables or prose are commonly structured in some way. One more complex example is the structure of a table, such as the earlier Listing 22-9. This structure is commonly articulated using markup (angle brackets), such as XHTML, to express the table. But XBRL simple fact values don’t allow markup to be part of the fact value. As such, you can’t include XHTML, other forms of XML, or any other forms of markup within an XBRL simple fact value.
Should you need to express things like tables or prose as blocks of text type information, you can get around this constraint in the following ways:
Use escaped markup: One approach is to change the physical angle brackets into something that doesn’t include angle brackets, thus getting around the no-markup-allowed constraint. Using escape characters to express the markup achieves this goal. For example, we will use escaped XHTML to show how this approach works. You can turn the markup
<p>Hello world</p> into <p>Hello world </p>. What this approach allows you to do is literally put anything that XHTML allows inside an XBRL simple fact value, which is quite a bit because XHTML is quite rich in expressive power. Applications that use the XBRL fact value information can easily convert the escaped XHTML (or whatever format you use) to normal XHTML when presenting the information to a user. Many RSS feeds use this approach for embedding XHTML or just HTML, into the RSS feed. You can find plenty of algorithms for converting to/ from escaped XHTML. And remember, you can use this approach to embed any other form of XML into an XBRL fact value.
Use plain text: Another option is to use formatted plain text within the fact value. The problem with plain text is that maintaining the formatting can be challenging, and you really don’t get that much expressive power. You use invisible tabs, spaces, carriage returns, and line-feed characters to achieve the formatting you desire. This approach can work in many situations, though.
Use JSON: JavaScript Object Notation (JSON) is a data-exchange format that is easy for both humans and computers to work with. A nice characteristic is that it can represent anything that XML can represent. As such, you can express your block of information within JSON in the XBRL instance and then convert it to whatever format you want the user to see when you use the XBRL instance. (For more on JSON, see http://json.org.)
Use base 64: XBRL has a type (data type) called xbrli:base64Binary ItemType. As with other XBRL types, it’s a specialization of an XML Schema type, xs:base64Binary. The binary characters are represented as a limited set of ASCII characters, none of which are the pesky angle brackets that make XML processors think the value is markup. Using base 64 works a lot like the escaped markup approach described previously. You can use reliable algorithms and functions to convert to/ from base 64.
