XBRL: just about the complex - Chapter 6. Immersion in XBRL - Part 1. Getting Started

6. Immersion in XBRL

In previous chapters, we touched the water with our finger , figuring out what XBRL is and what can be done with it. With this baggage of knowledge, we are ready for full immersion in real XBRL in our final chapter. We will review the basic steps for creating a taxonomy and a report and show how XBRL looks in real life.

In this chapter, we will show the process of forming a taxonomy and its associated report on an example of a company’s demography that is already familiar to you. As in real life, we will not be able to do everything right from the first attempt, so the process of their formation will be divided into several different versions. The development of most real taxonomies takes from several weeks to several months (and even years).

Note: We will not create a definition linkbase base or reference linkbase base. In real life, you could create at least one of them to describe your concepts in more detail, but they are not needed for the purposes of this chapter. Once you have mastered the link linkbase and presentation linkbase bases, there should be no problem understanding the linkbase of definitions and resources.

6.1. Getting started

Let's start with a simple taxonomy for our example.

6.1.1. Taxonomy scheme

First of all, we need a document containing the taxonomy scheme.

A good practice is to use the taxonomy creation date in the document name to easily distinguish between the taxonomy versions created at different times.

Let's imagine that we begin our small project on the first day of 2006 ( note of the translator: this brochure is over 10 years old ), then we will name the first version of the taxonomy document as follows: 'sample-2006-01-01.xsd'. We will discuss ours in small parts, creating a taxonomy step by step. We agree that each section of this chapter will take one day (for the convenience of versioning).

6.1.1.1. Schema root

As with any XML schema, we start with the root schema element:

 <schema targetNamespace="http://www.sample.com/2006-01-01" 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" xmlns:sample="http://www.sample.com/2006-01-01"> ... </schema> 

Notice the attributes inside the root element:

• targetNameSpace
  Defines the namespace of schema elements. The schema-supporting software that will be used to process the taxonomy or its associated report must use this namespace to refer to the schema or its parts.

The remaining attributes define the prefixes of the schema elements. The prefix indicates which namespace defines the element:

• xmlns
  XML Schema namespace - is the default for all elements without a prefix;
• xmlns:xbrli
  Report Namespace XBRL (instance);
• xmlns:link
  XBRL Link namespace;
• xmlns:xlink
  XML Schema XLink namespace;
• xmlns:sample
  Finally, any elements we define that are in the target namespace will have a sample prefix.

All the documents below have the same namespace definition attributes in the root element. We will not describe them separately for each new element type.

The XBRL specification includes a number of schemas:

• XBRL Instance
  It contains definitions (types, attributes, elements) necessary for the declaration of facts and concepts;
• XBRL Linkbase
  Contains the definitions necessary to ad link from one part of the taxonomy (or base of references) to another;
• XBRL XLink
  Used to declare the linkbase itself, you will need this namespace when creating your own XBRL specification extension;
• W3C XLink
  Namespace for XML Link; Note that the schema for this part of the specification is on xbrl.org, since the W3C does not provide this schema, but is required for the XBRL specification.

6.1.1.2. Import report layout

Our next step is to import the XBRL report schema so that we can use constructs from it in our element definitions.

 <import namespace="http://www.xbrl.org/2003/instance" schemaLocation="http://www.xbrl.org/2003/xbrl-instance-2003-12-31.xsd" /> 

The import element must specify the schema identified by the namespace. The schema document pointed to by the URI in the schemaLocation attribute must actually exist.

The XBRL report schema imports the XBRL Linkbase schema, and it in turn imports the XBRL XLink schema and the W3C XLink schema. This means that we do not need to import these schemas on our own.

The W3C XML Schema namespace is standardized and automatically recognized by software supporting our schema.

6.1.1.3. Concepts

Concepts in our taxonomy are defined as schema elements. From our example, we previously obtained the following concepts:

A concept reflecting the total number of employees is defined as follows:

 <element id="sample_nr_employees_total" name="nr_employees_total" xbrli:periodType="instant" type="xbrli:nonNegativeIntegerItemType" substitutionGroup="xbrli:item" nillable="true" /> 

Let us examine the attributes of the concept:

• id
  This identifier is used to refer to the concept in other documents, such as linkbases. It must be unique within the scheme. For the concept id, we used the prefix 'sample_' to make it globally unique.
• name
  The name specified in this attribute identifies the concept within the taxonomy and the report. It must be unique within the taxonomy.
• xbrli:periodType
  Each concept must have a period type associated with it. In our example, the number of employees is indicated at the beginning and at the end of the period, that is, at the date . For such concepts, the value instant .
• type
  The number of employees is an integer; a part-time employee is also counted as a unit, not a fraction. Since there can be no negative number of employees, we use the nonNegativeIntegerItemType type defined in the XBRL report schema.
• substitutionGroup
  This is a simple concept, not a tuple, so here we specify the item value defined in the XBRL report schema.
• nillable
  It is recommended to always specify concepts as nillable , this allows you to pass on them empty facts.

The rest of the concepts are defined similarly, but each with its own attribute values id and name .

We will also need an abstract concept that will serve as the root of the hierarchy of the presentation of our report. We will (arbitrarily) assign the type xbrli:stringItemType . Abstract concepts are not used for the transfer of facts, so you can specify any type to meet the requirements of the XBRL specification for its presence.

 <element id="sample_presentation_root" name="presentation_root" xbrli:periodType="instant" type="xbrli:stringItemType" substitutionGroup="xbrli:item" abstract="true" nillable="true" /> 

An abstract concept must have an abstract attribute with a value of true .

6.1.1.4. Links database links

If we want to present a full taxonomy or report, we need to provide additional information about concepts in the form of link bases. Let's start with two of them - the database of labels and the database of presentations.

The link to linkbases is indicated in the appinfo element, which is located inside the annotation element:

 <annotation> <appinfo> <link:linkbaseRef xlink:type="simple" xlink:href="sample-2006-01-01-label.xml" xlink:role="http://www.xbrl.org/2003/role/labelLinkbaseRef" xlink:arcrole="http://www.w3.org/1999/xlink/properties/linkbase" /> <link:linkbaseRef xlink:type="simple" xlink:href="sample-2006-01-01-presentation.xml" xlink:role="http://www.xbrl.org/2003/role/presentationLinkbaseRef" xlink:arcrole="http://www.w3.org/1999/xlink/properties/linkbase" /> </appinfo> </annotation> 

The link base link has the following attributes:

• xlink:type
  It always indicates simple .
• xlink:href
  This attribute indicates the link to the database itself. In our example, we refer to the database of labels and presentations, which will be discussed later.
• xlink:role
  The attribute 'role' defines the type of linkbase. We use the labelLinkbaseRef and presentationLinkbaseRef values ​​as defined by the XBRL Linking scheme.
• xlink:arcrole
  The role of the arc to the linkbase always indicates the linkbase value defined in XLink.

6.1.2. Label Link Database

The base of labels contains three types of elements:

• locators for defining taxonomy concepts that are assigned a label;
• resources that contain the labels themselves;
• arcs of labels linking a concept (through its locator) to a label.

These elements are placed inside the labelLink element:

 <?xml version="1.0" encoding="UTF-8"?> <linkbase xmlns="http://www.xbrl.org/2003/linkbase" xmlns:xbrli="http://www.xbrl.org/2003/instance" xsi:schemaLocation="http://www.xbrl.org/2003/instance http://www.xbrl.org/2003/xbrl-instance-2003-12-31.xsd" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:sample="http://www.sample.com/2006-01-01"> <labelLink xlink:type="extended" xlink:role="http://www.xbrl.org/2003/role/link"> ... </labelLink> </linkbase> 

The labelLink element has the following attributes:

• xlink:type
  This is always extended .
• xlink:role
  For links, the link role is used by default.

6.1.2.1. Locator

Locators are placed in loc elements. They point to concepts related to taxonomy.

 <loc xlink:type="locator" xlink:href="sample-2006-01-01.xsd#sample_nr_employees_total" xlink:label="concept_nr_employees_total" /> 

• xlink:type
  The type of the loc element is always specified locator , meaning that it is used as a locator (concepts).
• xlink:href
  Indicates the actual location of the concept. Please note that here we use his id .
• xlink:label
  The locator is assigned a shortcut to access it within the database of links. As the label value, we will use the concept id with the 'concept_' prefix.

6.1.2.2. Shortcuts

The label element is used to define labels.

 <label xlink:type="resource" xlink:label="label_nr_employees_total" xlink:role="http://www.xbrl.org/2003/role/label" xml:lang="en">Total number employees</label> <label xlink:type="resource" xlink:label="label_nr_employees_total" xlink:role="http://www.xbrl.org/2003/role/terseLabel" xml:lang="en">Total</label> <label xlink:type="resource" xlink:label="label_nr_employees_total" xlink:role="http://www.xbrl.org/2003/role/verboseLabel" xml:lang="en">Total number of employees</label> 

• xlink:type
  The type is always the value of 'resource', indicating that the label is a local reference database resource.
• xlink:label
  As in the case of locators, the value of the label attribute provides the ability to access the label within the link database. Notice that each of these labels is associated with the same concept, and all of them use the same attribute value. This allows you to use a one-to-many relationship from concept to its labels. In our example, these are three different types of shortcuts for the concept 'nr_employees_total'.
• xlink:role
  The role determines the type of label used. The XBRL specification provides a large number of predefined roles. In the example we use three types - normal, short and expanded labels. The taxonomy or XBRL report application allows you to select the most appropriate type of shortcuts. Presentation reference databases can also indicate the preferred type of label.
• xml:lang
  This attribute indicates the language of the label. In the example we use only English, but you can include labels in any languages ​​in the linkbase.

6.1.2.3. Arcs of shortcuts

Finally, after defining the locators for concepts and label resources, we can link them using label arcs.

 <labelArc xlink:type="arc" xlink:arcrole="http://www.xbrl.org/2003/arcrole/concept-label" xlink:from="concept_nr_employees_total" xlink:to="label_nr_employees_total" /> 

• xlink:type
  Type always specify 'arc', arc ( who would have thought ).
• xlink:arcrole
  The role of the arc determines the type of connection. For labels, the 'concept-label' is specified, the arc between the concept and the label.
• xlink:from
  Indicates one of the sides of the arc, in our case, the concept. We use label locator as the value of this attribute.
• xlink:to
  Indicates the second side of the arc, label resources, also using the resource label .

Since we used the same label for three different labels, our arc forms a one-to-many relationship between the concept and its labels.

6.1.3. Presentation reference database

Presentations contain two types of elements:

• Locators of taxonomy concepts used in the view hierarchy;
• Arcs of views linking concepts to each other through their locators.

All of them are located inside the presentationLink element:

 <?xml version="1.0" encoding="utf-8"?> <linkbase xmlns="http://www.xbrl.org/2003/linkbase" xmlns:link="http://www.xbrl.org/2003/linkbase" xmlns:xbrli="http://www.xbrl.org/2003/instance" xsi:schemaLocation="http://www.xbrl.org/2003/instance http://www.xbrl.org/2003/xbrl-instance-2003-12-31.xsd" xmlns:xhtml="http://www.w3.org/1999/xhtml" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" > <presentationLink xlink:type="extended" xlink:role="http://www.xbrl.org/2003/role/link" > ... </presentationLink> </linkbase> 

6.1.3.1. Locators

Here, everything is the same as the link base of labels, we will not repeat.

6.1.3.2. Presentation arcs

Presentation arcs connect concepts in a parent-child hierarchy ( tree ):

 <presentationArc xlink:type="arc" xlink:arcrole="http://www.xbrl.org/2003/arcrole/parent-child" xlink:from="concept_presentation_root" xlink:to="concept_nr_employees_total" order="1" priority="0" use="optional" preferredLabel="http://www.xbrl.org/2003/role/label" /> <presentationArc xlink:type="arc" xlink:arcrole="http://www.xbrl.org/2003/arcrole/parent-child" xlink:from="concept_presentation_root" xlink:to="concept_nr_employees_male" order="2" priority="0" use="optional" preferredLabel="http://www.xbrl.org/2003/role/terseLabel" /> <presentationArc xlink:type="arc" xlink:arcrole="http://www.xbrl.org/2003/arcrole/parent-child" xlink:from="concept_presentation_root" xlink:to="concept_nr_employees_female" order="3" priority="0" use="optional" preferredLabel="http://www.xbrl.org/2003/role/terseLabel" /> ... 

• xlink:type
  As before, 'arc'.
• xlink:arcrole
  The role of the presentation arc is 'parent-child', which indicates that the reference base of the presentations is a hierarchical structure.
• xlink:from
  Indicates the parent concept of a hierarchy through its locator. In our example, there was no suitable concept, so for the root of the hierarchy we use the abstract concept 'presentation_root'.
• xlink:to
  Indicates a child hierarchy concept through its locator. In our example, all concepts are located under the root concept of 'presentation_root'.
• order
  This attribute specifies the order of the children under the common parent element.
• priority
  Used to override linkbases. In our example, we are not doing this (for now).
• use
  By specifying an optional value, we denote that the concept can be part of a network of presentations. It is common practice to indicate this value, although it is also used by default in the absence of an attribute.
• preferredLabel
  Previously, we have created several types of labels in our tag reference database. Here we see how in the base of the links of presentations the preferred type of label for the child (to) concept arc is indicated.

Note: Since the preferredLabel attribute can be specified only for child concepts, the root element of the presentation hierarchy cannot have a preferred label type.

6.1.4. XBRL report

Having created a taxonomy, we can use it to create a report.

The XBRL report document contains the following kinds of elements:

• Links to taxonomy schema;
• Contexts for facts;
• Units of measure for numerical facts;
• The very values ​​of the facts.

All these elements are placed inside the xbrl element:

 <?xml version="1.0" encoding="utf-8"?> <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:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:iso4217="http://www.xbrl.org/2003/iso4217" xmlns:s="http://www.sample.com/2006-01-01"> ... </xbrl> 

6.1.4.1. Taxonomy schema reference

The link to the schema is specified in the schemaRef element:

 <link:schemaRef xlink:type="simple" xlink:href="http://www.sample.com/2006-01-01/sample-2006-01-01.xsd" /> 

• xlink:type
  Specify the connection type 'simple'.
• xlink:href
  The link is specified as an href attribute. It indicates the location of the taxonomy scheme on its creator’s site.

6.1.4.2. Context

We have two contexts in the example - the beginning of the reporting period and the end of the reporting period:

 <context id="c_start"> <entity> <identifier scheme="http://www.statistics.org">12-34567</identifier> </entity> <period> <instant>2016-01-01</instant> </period> </context> <context id="c_end"> <entity> <identifier scheme="http://www.statistics.org">12-34567</identifier> </entity> <period> <instant>2016-12-31</instant> </period> </context> 

• id
  Used to associate a fact with a context. This value must be unique within the report.
• entity
  Here you specify the organization, according to which the report is compiled.
  
  • identifier
    This element uses a scheme to determine which organization is the report for. In our example, we use a non-existent scheme on a fictional site.
• period
  The period or date of the context is indicated here.
  
  • instant
    In our example, we have two instant contexts, for the dates of the beginning and end of the reporting period, respectively.

The link specified in the identifier element refers to a non-existent statistical organization that publishes the identifiers of the reporting organizations. Our imaginary company has the identifier '12 -34567 '. In the real world, we would use, for example, the stock exchange ticker or organization identifier in a national tax authority.

6.1.4.3. Units

For all numerical facts, the units of measure should be indicated:

 <unit id="u_person"> <measure>Person</measure> </unit> 

• id
  Used to associate a fact with a unit of measure. This value must be unique within the report.
• measure
  Identifies the unit of measure. In our example, we have defined our own unit of measure - 'Person'.

6.1.4.4. Data

Now we have finally reached the final goal of our entire exercise - the transmission of facts:

 <s:nr_employees_total contextRef="c_start" unitRef="u_person" decimals="0">35</s:nr_employees_total> <s:nr_employees_total contextRef="c_end" unitRef="u_person" decimals="0">41</s:nr_employees_total> <!--  --> <s:nr_employees_male contextRef="c_start" unitRef="u_person" decimals="0">23</s:nr_employees_male> <s:nr_employees_male contextRef="c_end" unitRef="u_person" decimals="0">27</s:nr_employees_male> <s:nr_employees_female contextRef="c_start" unitRef="u_person" decimals="0">12</s:nr_employees_female> <s:nr_employees_female contextRef="c_end" unitRef="u_person" decimals="0">15</s:nr_employees_female> <!--   --> <s:nr_employees_age_up_to_20 contextRef="c_start" unitRef="u_person" decimals="0">5</s:nr_employees_age_up_to_20> <s:nr_employees_age_up_to_20 contextRef="c_end" unitRef="u_person" decimals="0">9</s:nr_employees_age_up_to_20> <s:nr_employees_age_21_to_40 contextRef="c_start" unitRef="u_person" decimals="0">23</s:nr_employees_age_21_to_40> <s:nr_employees_age_21_to_40 contextRef="c_end" unitRef="u_person" decimals="0">21</s:nr_employees_age_21_to_40> <s:nr_employees_age_41_and_up contextRef="c_start" unitRef="u_person" decimals="0">7</s:nr_employees_age_41_and_up> <s:nr_employees_age_41_and_up contextRef="c_end" unitRef="u_person" decimals="0">11</s:nr_employees_age_41_and_up> 

Each fact is a separate element associated with the concept. The value of the element is the value of the fact.

• contextRef
  Each fact refers to its context through the context id . Our example contains facts for each concept in each context.
• unitRef
  Since for all numerical facts the units of measure must be indicated, in our example we fill in here 'u_person'.
• decimals
  For numeric facts, one of the attributes must be specified - decimals (decimals) or precision (precision). In our example, all the facts are integer, therefore we specify decimals with the value '0'.

6.1.5. We are proud to present you our XBRL report.

After all the work done, we would like to see how our report is formed in relation to the taxonomy and, in particular, to the link bases of presentations and labels.

To do this, we use a simple tool that creates a web page for our report with the fact in tabular form. It arranges the contexts in the columns of the table, and the labels of the concepts from the base of links of the labels - to its left. The concept hierarchy defined in the presentation reference database defines the order and indents for the facts.

The result obtained by us looks approximately as follows:

Well, we have worked well today!

Chapter navigation

• Comment from the translator
• Chapter 1. Introduction
• Chapter 2. What is XBRL?
• Chapter 3. Anatomy of taxonomy
• Chapter 4. XBRL Report
• Chapter 5. Discovering New Dimensions
• Chapter 6. Immersion in XBRL
  
  • Part 1. Getting Started
  • Part 2. Improving the result
  • Part 3. Calculations and validation
  • Part 4. How to make life easier
  • Part 5. New measurements
  • Part 6. Multidimensionality
• PS from translator