This document is a review draft. Readers are invited to submit comments to the Taxonomy Architecture Guidance Task Force.
Table of Contents
1 Abstract
A taxonomy component can be assigned multiple labels of different types and in different languages. At a technical level, each type of label is differentiated by a label role. XBRL label roles are used to assign a specific meaning to a label. The XBRL specification provides a default label type known as the "Standard Label". This is used as the default label for the component.
This guidance focuses on the general use of label roles and provides specific recommendations on the use of the label roles provided in the XBRL Standard for taxonomy elements. Specific recommendations on use of the standard label role are available in 'Taxonomy labelling and how to create good standard labels'.
The target audience for this guidance on label roles is taxonomy architects and taxonomy authors.
2 How label roles are used
Labels defined using different label roles are used for a number of different purposes, which are described below.
2.1 Providing more information about taxonomy components
In order to give a more complete definition of a taxonomy component, multiple labels can be provided. The way in which these should be understood is indicated by the type of the label. The taxonomy does not explicitly describe where and how these types of labels should be displayed.
An example of providing more information is to add a documentation label. In one taxonomy, the concept with standard label 'Profit (loss) on ordinary activities after tax' has a documentation label that states 'Typically only required when an extraordinary profit or loss is reported'.
2.2 Controlling the presentation of taxonomy elements
The presentation tree has a mechanism (known as the preferred label mechanism) to show different labels for the same element at different points in the tree.
In the example below, the same concept is used to give the balance at the beginning and the end of a period. A "period start label" and "period end label" are assigned to the concept and marked as the preferred label in the appropriate locations in the presentation tree. The standard label for the concept is "Property, plant and equipment".
- Property, plant and equipment at beginning of period (period start label)
- Increase (decrease) in property, plant and equipment
- Additions, property, plant and equipment
- Depreciation, property, plant and equipment
- Decrease, property, plant and equipment
- Property, plant and equipment at end of period (period end label)
2.3 Controlling the presentation of values
When XBRL reports are being shown according to a taxonomy's presentation tree, it may be necessary to select different values for a concept, or present the value with a different sign, based on its location within the tree. The preferred label mechanism can be used to achieve this. For example, by selecting period start and period end labels using the preferred label mechanism shown above, it is also possible to select the appropriate current period or prior period value for a concept when displaying an XBRL report.
2.4 Enabling label selection based on the sign of reported values
The naming conventions of some taxonomy concepts may change depending on the sign of the reported value. For example, in the case of the concept 'Profit (loss)', if the value is positive it may be referred to simply as 'Profit' and if it is negative it is referred to as 'Loss'. Specific labels to be displayed in such cases can be defined.
3 Guidance on specific label roles
This section describes each label role standardised by XBRL International 1 (complete at the time of writing) and provides recommendations for when to use them. The roles have been organised into a number of separate tables according to their purpose.
3.1 Label roles that provide more information
| Label Role | Purpose and behaviour | Example | Recommendation |
|---|---|---|---|
| Documentation label | Documentation of taxonomy component, providing an explanation of its meaning and its appropriate usage and any other documentation deemed necessary. |
"The amount of liabilities related to the entity's leases. Lease is a contract, or part of a contract, that conveys the right to use an underlying asset for a period of time in exchange for consideration."
(Documentation Label for 'Leases Liabilities') |
It is recommended that documentation labels are provided in order to provide a clear and unambiguous definition of the purpose of the concept. The guidance for standard labels recommends that standard labels are kept concise, so documentation labels provide the opportunity for a more complete description of the concept. Taxonomy authors can also use references to provide structured links from the taxonomy back to external authoritative literature. |
| Terse label | Short label, often omitting text that should be inferable when the concept is reported in the context of other related concepts. | "Dividends paid"
(Terse Label for 'Dividends paid, classified as financing activities') |
Terse labels may be included where taxonomy authors wish to make views of the taxonomy, such as those provided by the presentation tree or table structure, more readable by using short labels. Use of terse labels allows standard labels to remain unique and contextless, as recommended in the guidance for standard labels. |
| Verbose label | An extended label | Use of verbose labels is not generally required, as the standard label should provide a label that uniquely identifies the concept, and a more complete definition of the concept should be provided by the documentation label. | |
| Definition guidance | The label for additional guidance related to the definition of a taxonomy concept | These roles are not in common use but may be used to directly include more comprehensive guidance for concepts drawn from the underlying authoritative literature, such as an accounting standard. Taxonomy authors can also use references to provide structured links from the taxonomy back to external authoritative literature. | |
| Disclosure guidance | An explanation of the disclosure requirements relating to the concept. For example, where the disclosure is mandatory or recommended. | ||
| Presentation guidance | An explanation of the rules guiding presentation (placement and labelling) of this concept in the context of other concepts in one or more specific types of business reports. | ||
| Measurement guidance | An explanation of the method(s) required to be used when measuring values associated with this concept in business reports. | ||
| Commentary guidance | Any other general commentary on the concept that assists in determining definition, disclosure, measurement, presentation or usage. | ||
| Examples guidance | An example of the type of information intended to be captured by the concept. |
3.2 Label roles that control the presentation of elements or fact values
As discussed in controlling the presentation of taxonomy elements and controlling the presentation of values, these label roles can be selected using the preferred label mechanism in order to control the presentation of taxonomy elements and report values.
| Label Role | Purpose and behaviour | Example | Recommendation |
|---|---|---|---|
| Period start label | The label for the taxonomy concept when it is being displayed as a start of period value | "Equity at beginning of period"
(Period Start Label for 'Equity') |
These are recommended for when the taxonomy is describing a roll-forward to differentiate this as being a label suitable for the start of the period. Period start labels should be defined only for numeric concepts with instant period type. |
| Period end label | The label for the taxonomy concept when it is being displayed as an end of period value | "Goodwill at end of period"
(Period end Label for 'Goodwill') |
These are recommended for when the taxonomy is describing a roll-forward to differentiate this as being a label suitable for the end of the period. Period end labels should be defined only for numeric concepts with instant period type. |
| Total label | The label for the taxonomy concept when it is being displayed as the total of a set of other values | "Total Comprehensive income"
Total Label for 'Comprehensive income' |
These are recommended for when the taxonomy is describing a roll-up and the same concepts are included as part of a calculation as well as the total of a calculation. Total labels should be defined only for numeric concepts. |
| Net label | The label for a concept for use in presenting values associated with the concept when it is being reported as the net of a set of other values. Net labels allow for expressing different labels than the one which would be used as |
"Net increase (decrease) in cash and cash equivalents"
(Net label for 'Increase (decrease) in cash and cash equivalents') |
Net labels should be defined only for numeric concepts. |
| Negated label | The label for a taxonomy concept that is used to indicate that a value should be displayed with the opposite sign to that with which it is reported in XBRL. This is described in more detail in separate guidance on positive and negative values in XBRL. | "Finance Cost"
(Negated Label for 'Finance Cost'') Note here that the sign of the fact value will be flipped when this label is used. |
Negated labels should be used where the presentation tree is being used to drive the presentation of reported values and it is necessary to control the sign convention used to present values. Negated labels should be defined only for numeric concepts. |
3.3 Label roles that enable label selection based on the sign of reported values
| Label Role | Purpose and behaviour | Example | Recommendation |
|---|---|---|---|
| Positive label | The label for the taxonomy concept that can be used when the value is positive. | "Profit"
(Positive Label for 'Profit (loss)') |
It is recommended that standard labels are defined to clearly describe the meaning of both positive and negative values. Where this is done, separate positive and negative value labels are not generally necessary. These labels should be defined only for numeric concepts. |
| Negative label | The label for the taxonomy concept that can be used when the value is negative. | "Loss"
(Negative Label for 'Profit (loss)') |
|
| Zero | The label for the taxonomy concept that can be used when the value is zero | It is recommended that this label is not used. |
3.4 Miscellaneous label roles
| Label Role | Purpose and behaviour | Example | Recommendation |
|---|---|---|---|
| Deprecated label | The label for a concept indicating that the concept has been deprecated, with further explanation as needed. If the deprecated date label is also present then the concept is only considered deprecated after that date. |
"Element was deprecated because the guidance from which this element is derived is no longer applicable." | This label should only be used on concepts that are being withdrawn from use. The exact circumstances under which it is acceptable to use a deprecated concept will be implementation specific. |
| Deprecated date label | The label for a concept containing only the date as of which the concept was deprecated. | "2018-01-31" | This label should only be used on concepts that are being withdrawn from use. The exact circumstances under which it is acceptable to use a deprecated concept will be implementation specific. The specification does not specify a format but it is recommended that ISO 8601 format without a timezone is used (i.e. YYYY-MM-DD) |
| Restated label | The label for a concept when presenting values that have been restated from their value as originally reported. | "Reserves, Restated Balance"
(Restated label for 'Reserves') |
It is recommended that this label is not used as inclusion may lead to confusion about the fundamental meaning of the concept, which cannot be changed using different labels. Restated values should be differentiated from other values using a dimension. |
3.5 Label role combinations
In addition to the label roles listed above, certain combined roles are provided, for example "negated total". Such roles are recommended to be used if the individual parts of the role are recommended in the section above.
4 New label roles
A new label role should be created only when none of the predefined label roles match the business requirement. If the taxonomy author considers the new label role might have a wider application, then the new role can be submitted for inclusion in the XBRL Link Role Registry (LRR) making it available for other taxonomy authors2.
The following points should be considered when deciding whether to create a new role:
- New label roles help to represent the content in more appropriate manner.
- If added to the registry, the label roles are available for other taxonomy developers.
- Addition of label roles makes the taxonomy less standard.
- New roles may not be understood by consumers of the taxonomy or off-the-shelf software.
5 General Considerations for label roles
Each label attached to an element should convey new information such as providing the label in a new language, or providing additional information how the concept should be used. Care should be taken that labels do not change the definition of the element or contradict other labels.
Multiple labels with the same role and language are considered to be duplicate labels. Duplicate labels can be confusing to users and software, and should be avoided.
- Choose a label role that best meets the business requirements using the purpose and behaviour presented for each role in this guidance.
- Prefer to use label roles that have already been defined.
- Do not create new label roles when predefined roles can be used.
- Consider submitting new label roles to the registry2.
- For each role, consider whether a specific convention for how labels are constructed should be defined and followed.
- Do not create duplicate labels.
- Ensure labels do not change the definition of the element or contradict other labels.
-
Standardised label roles are defined in either the XBRL Specification or the Link Role Registry ↩
-
The process for adding new label roles to the registry is documented here ↩↩
This document was produced by the Taxonomy Architecture Guidance Task Force.
Published on 2019-06-11.
