Table of Contents

1 Introduction

This document describes best practices for publishing XBRL taxonomies, including detail on information that should be provided as part of an XBRL Taxonomy Package. This guidance is primarily for taxonomy owners and data collectors who want to make sure that taxonomy users can understand the taxonomies they publish.

2 Taxonomy publication

Taxonomies are usually publicly accessible. They are generally published on an official web site to be freely accessed, read by compliant software applications and used by preparers of XBRL reports. In order to help users of the taxonomy, it is recommended that taxonomies are provided in two formats:

• As XBRL taxonomy files hosted at the "official" location on the taxonomy owner's website; and
• As a Taxonomy Package — a specially formatted ZIP file that provides additional information about the taxonomy.

These formats are described in more detail in the following sections. It is also recommended that published taxonomies are added to the XBRL International Taxonomy Registry.

2.1 Hosting taxonomy files at their "official" location

When an XBRL report is created, it includes a reference to the corresponding taxonomy. This takes the form of one or more URLs pointing to files within the taxonomy known as entry points. XBRL processors use these entry point files to find all other files within the taxonomy that are needed to validate and consume the report.

The URL included in an XBRL report uniquely identifies the taxonomy, and it is important that different reports referencing the same taxonomy use the same URL. In order to ensure this, the taxonomy owner should define an official location from which the taxonomy files can be downloaded directly. For example, if a taxonomy contains a file called, "entry.xsd", the official location might be:

https://xbrl.example.com/my-example-taxonomy/v2.1.0/entry.xsd

The taxonomy owner should ensure that the file is available to be downloaded from that location. Defining an official location and publishing the taxonomy there ensures that XBRL reports using the taxonomy can be opened in any XBRL software tool, and that it may "work" without the need for further configuration. Once taxonomy files are published at their official location, they should never be changed. If changes are needed, a new version must be published.

2.1.1 Use of the "https" protocol for hosting taxonomy files

It is recommended that all new taxonomies are hosted at secure (https) URLs. This has become a default choice for hosting as it ensures the taxonomy is downloaded from the trusted source.

Where taxonomies have already been published using an http URL, it is not recommended that this is updated to https as this constitutes a change to the official location. Such taxonomies can be published in a Taxonomy Package (see section 2.2) which is made available at a secure (https) URL.

2.2 Publishing a Taxonomy Package

In addition to ensuring that the taxonomy files are published at their official locations, it is recommended to also provide them as a Taxonomy Package. This is a ZIP file that makes it easy to download a copy of all files in the taxonomy and includes additional information to make the taxonomy easier to use.

A Taxonomy Package includes additional descriptive information to help users understand the taxonomy, as well as a set of "remappings" that describe, in a structured format, how official URLs can be mapped onto copies of the taxonomy files found within the package. Remappings enable XBRL software to consume XBRL reports that reference official URLs using local copies of files from a Taxonomy Package. Separate guidance on Taxonomy Package discusses the benefits of publishing Taxonomy Packages.

2.2.1 Packages that refer to external taxonomies

If the taxonomy to be published has dependencies on other taxonomies, including those published by third parties, then these should not be included in the Taxonomy Package. For people to use the taxonomy, they will need to download all dependent packages. Separate Taxonomy Packages may also be created for modular parts of the taxonomy for easier maintenance and reuse.

An example of a third-party package is the LEI taxonomy.

If, and only if, no package for the external taxonomy is available from the taxonomy owner, then it is good practice to create and provide one for your users. This should be in its own package. A special case is XBRL International specification schema files; it is expected that these will be built into XBRL software and taxonomy authors should not redistribute these files.

3 Taxonomy Package information

This section describes the information that should be included within a Taxonomy Package.

3.1 Taxonomy description

It is recommended that the information included in the Taxonomy Package be descriptive enough to make the broad purpose and scope of the taxonomy clear to a user who is unfamiliar with the filing system. This is important if it is to be included in the XBRL International Taxonomy Registry.

This best practice recommendation describes a standard way to fill out the Taxonomy Package so that all taxonomies published are presented consistently in the Taxonomy Registry or other compliant viewing tools. Details of each element are described below.

Elements designated as multilingual may be repeated in different languages. The "Identifier" element is mandatory as per the Taxonomy Package specification. Other elements described here are not technically required but it is recommended that they are included.

A taxonomy package can be uploaded to the Taxonomy Registry to see how it will appear in the registry and verify that all required fields are included. It is possible to upload a taxonomy package for validation and preview without adding it to the registry. Please note that this service does not fully validate the package against the Taxonomy Package specification, nor does it check the XBRL validity of its contents. This service is available to members of XBRL International and can be accessed using an XBRL user ID and password.

3.1.1 Identifier [tp:identifier]

The Taxonomy Package identifier [tp:identifier] must be a URI that uniquely identifies a package.

URIs use the same structure as the URLs commonly used to identify resources on the internet, but unlike URLs they do not necessarily describe the location of a resource, they merely provide a unique identifier. URIs have the following format:

scheme://authority/path

It is common (although not particularly logical) practice to use https as the scheme. In order to ensure uniqueness, it is recommended that the authority section be based upon an internet domain name that is under the control of the taxonomy author, and that the path includes both the name and version of the taxonomy.

For example, a taxonomy owner owning the domain name "example.com" might use an identifier of the form:

https://xbrl.example.com/my-example-taxonomy/v2.1.0

3.1.2 Name [tp:name] (multilingual)

The concise, official name of the taxonomy.

This can be provided in multiple languages. The name should not include the version of the taxonomy. This should be included in the separate version element, and including it in the name will cause it to be repeated when the package information is shown. (e.g. the name should be provided as "ABC Taxonomy" rather than "ABC Taxonomy 2020")

3.1.3 Version [tp:version]

The version of the taxonomy. (e.g. "2020" or "v2.7.1")

The format of the version number is not constrained; taxonomy owners are free to use whatever versioning scheme is appropriate for their taxonomy.

3.1.4 Description [tp:description] (multilingual)

A description of the purpose and scope of the taxonomy.

The description should provide a high-level description of the purpose and scope of the taxonomy, and where applicable, should refer to the regulation or standard it is based on. The description should describe the taxonomy in terms that will make sense to a consumer who is unfamiliar with the jurisdiction or filing program to which it relates. This is where the issuer can provide the reason for publishing a new version and indicate what architecture is used.

3.1.5 License [tp:license]

Link to licensing terms for the taxonomy. The license element contains a link to the license documentation, the format of which is not restricted. It also provides for a human-readable name for the license.

3.1.6 Publisher name [tp:publisher] (multilingual)

The name of the taxonomy owner.

3.1.7 Publisher URL [tp:publisherURL]

The primary website URL of the taxonomy owner. If the same entity publishes multiple taxonomies, the same URL should be used in all Taxonomy Packages published by that entity.

3.1.8 Publisher Country [tp:publisherCountry]

The country or region of the taxonomy owner, represented as an alpha-2 code as defined by ISO3166-1.

This should record the location of the taxonomy owner, which is not necessarily the region to which the taxonomy is applicable. Where a taxonomy is applicable to an international region, this can be specified separately when uploading a taxonomy to the XBRL International Taxonomy Registry.

3.1.9 Date of issue [tp:publicationDate]

The date on which the taxonomy was published.

3.1.10 Entry point [tp:entryPoint]

A Taxonomy Package may provide an ordered list of taxonomy entry points.

A taxonomy entry point is a set of URLs that define a logical starting point for the DTS discovery process, as defined in the XBRL Specification. If more than one entry point is defined, the document order in which they are defined should be used to provide a default ordering when presenting the contents of the Taxonomy Package.

Each entry point can be documented with:

3.1.10.1 Entry point name [tp:name] (multilingual)

This field should provide a concise, human-readable name for the entry point (e.g., "Full IFRS and Management Commentary")

3.1.10.2 Entry point description [tp:description] (multilingual)

A human-readable description for the entry point (e.g., "This is the entry point for viewing the taxonomy for full IFRS reporting with management commentary").

3.1.10.3 Entry point version [tp:version]

A version identifier for the entry point. This field is typically omitted, as taxonomies are typically versioned at the package level. If entry points share the same version number as the package in which they appear, this field should be omitted, rather than duplicating the version number of the package.

3.1.11 Superseded Taxonomy Packages

When a Taxonomy replaces an older taxonomy or merges multiple other taxonomies, the Taxonomy Package for that taxonomy should reference the other Taxonomy Packages that are superseded. It is recommended to list only the most recent Taxonomy Packages that are superseded.

3.2 Remapping of taxonomy files

The Taxonomy Package specification also provides remapping that allows XBRL tools to treat the contents of the package as an offline copy of taxonomies published at an Internet location, without the need for additional configuration. This function will rewrite the URI (Uniform Resource Identifier: string of characters used to identify a resource) address of the taxonomy files. In order to avoid overlaps with different taxonomy versions, it is recommended that:

• The remapping is provided for individual subdirectories rather than for the root URI of the taxonomy. (e.g., instead of remapping the whole of http://example.com, each subdirectory should be remapped: http://example.com/part1/, http://example.com/part2/); and
• The remapped URI include some form of version identifier (e.g. http://example.com/part1/2016-01-01, http://example.com/part2/2016-01-01). This may result in a larger number of more granular remappings, but this is preferable to having remappings between packages that overlap.

4 Example Taxonomy Package

A good example of a taxonomy package that follows the recommendations in this document is the Legal Entity Identifier (LEI) taxonomy published by XBRL International:

• LEI Taxonomy