Table of Contents

1 Introduction

Taxonomy authors sometimes need to add structured information or metadata to taxonomy components. For example, taxonomy authors may want to communicate milestone information such as the effective date, deprecation date, or creation date, for the taxonomy components, or document the applicability of business type, form number, or report type relevant to taxonomy elements. Such structured information facilitates correct reporting by preparers and enables software to enhance the user experience.

For example:

• The concept 'Increase (decrease) in provision for unearned premium' with an expiry date of '2023-01-01' indicates that from that date onwards, the element would be replaced or superseded by amendments to the reporting standard and will no longer be recommended for use in the XBRL report. Software may present such expiry elements differently to draw users' attention. This information may be helpful for preparers to plan the report tagging.
• Marking the concept 'Number of current members' to be reported only by co-operatives conveys valuable metadata of the taxonomy element. Such information can prevent the usage of this tag by entities belonging to another category.

XBRL provides the "property reference" mechanism as a standard way to capture such information in a structured format. Property references use XBRL’s reference mechanism and two standard reference resource roles¹. This document provides guidance on using property references in a taxonomy and discusses alternatives for incorporating such structured information into taxonomies. The document is targeted towards taxonomy architects and authors.

2 Property reference mechanism

XBRL references allow metadata to be attached to taxonomy components, such as concepts and structural elements. References are commonly used to refer to authoritative, external literature, such as an accounting standard, but they can also be used to attach key/value metadata directly to taxonomy components.

An XBRL reference consists of a "reference role", describing the nature of the reference, and one or more "reference parts", providing the content of the reference. Two reference roles are defined in the XBRL Link Role Registry for use when creating references for key/value metadata:

• Property
• Property-with-language

Each reference part consists of a name (key) and a value. The name must correspond to the name of a reference part element defined in the taxonomy.

For example, to indicate that a concept has an "expiry date" of 1st January 2023, we could attach a property reference, as follows:

Key = ExpiryDate
Value = 2023-01-01

To indicate that a concept is applicable only to "co-operatives" we could attach a property reference, as follows²:

Key = EntityType
Value = Co-operatives

The XBRL reference mechanism using the "property" roles is the preferred approach for specifying structured information about taxonomy components. Using this standard approach, referred to as "property references", ensures metadata in taxonomies is captured consistently. Standardisation and consistency enable off-the-shelf XBRL software tools to provide enhanced interactivity with metadata.

2.1 Incorporating property references in taxonomies

The following guidance applies when using "property references" in taxonomies:

• The structured information should be in a key-value pair format as described above.
• The key is required to be defined as a reference part, i.e., an individual component of a reference.
• Datatypes should be used to constrain the type and format of information (value) that can be captured in reference parts (key) to ensure consistency.
• The two property reference roles to be used in defining structured information are
  • Property (https://xbrl.org/2022/role/property) This role is used when the structured information is not language specific. Examples of such information include Expiry date: 2023-01-01 or Form Number: 415
  • Property-with-language (https://www.xbrl.org/2022/role/propertyWithLang) This role is used when the structured information can be specified in multiple languages. An example of such information includes "Entity Type: Co-operatives"
• Each taxonomy component can only have one value for a given key. For example, a taxonomy concept cannot have property references for "Creation Date" as both "2023-01-15" and "2023-01-01". For "property-with-language" multiple values for the same key are allowed, provided that the languages are different. Property references should be unique across all ELRs. These validation constraints on property references will be enforced by software.
• Parts (key-value pairs) for taxonomy components should be grouped together within a single reference resource rather than split into separate references.
• The property references can be used for taxonomy elements or taxonomy components. Technical details of the construction are discussed in the technical section of this document.
• It should be noted that the reference information does not automatically constrain or validate the usage of the taxonomy element. However, the reference syntax information can be used in XBRL Formula Rules to filter facts for validations.

3 Alternative Mechanisms

There are alternative approaches to capturing structured information, described below, that should only be considered if a significant portion of this guidance on using property references cannot be followed:

• Labels using specific role types - The structured information can be specified as a label distinguished using label roles. For example, the deprecation label and deprecation date label convey information about the deprecated concept. However, labels do not provide structured data in the same way that reference parts do and cannot constrain the pattern/format of information captured.
• Custom attributes - The use of custom attributes that are defined by the taxonomy authors are used on the taxonomy elements to convey the metadata — for example, having a custom attribute applied to certain elements that should use "forever" as its period value. However, not all XBRL software supports the use of custom attributes, thus this can harm interoperability.
• External documentation - External documents, including release notes, implementation guides and technical guides, can provide information on conveying information for the users of a taxonomy. However, that information is not embedded in the taxonomy, so it requires additional effort by taxonomy users and can be confusing, particularly when dealing with multiple versions of the taxonomy.
• Generic Linkbase - The Generic Linkbase allows taxonomy authors to associate arbitrary XML with taxonomy artefacts. However, the specific implementation of the generic linkbase is unlikely to be supported by off-the-shelf XBRL software.

Custom attributes and generic linkbases also make taxonomies less consistent, making it potentially challenging to compare similar disclosures across XBRL reports prepared using different taxonomies.

4 Technical notes on property reference construction

As defined in the XBRL 2.1 Specification, references are intended to be used only to link external authoritative literature, such as an accounting standard. The usage of property reference to specify structured information is a minor deviation from this base specification usage requirement; however, this would not flag any technical error.

Although references are most commonly used on taxonomy elements, they may need to be associated with other taxonomy components. When creating property references, the reference linkbase should be used when associating references with taxonomy elements, and generic references should be used elsewhere.