Adding taxonomies to the ZIP Catalog

How to add taxonomies to the catalog, step by step

Introduction

Adding a taxonomy to the ZIP catalog is easy. This document explains how to do it step y step.

Step 1: Collect required data

We need the following information:

Official taxonomy starting URL: This is the part of the taxonomy entry point that is the same for all taxonomy files, for example; for a taxonomy published on the internet in the following location:

http://www.sample-institution.org/xbrl/taxonomies/aaaa-mm-dd/sample-institution-entry-point.xsd
http://www.sample-institution.org/xbrl/taxonomies/aaaa-mm-dd/sample-institution-lab.xml
http://www.sample-institution.org/xbrl/taxonomies/aaaa-mm-dd/sample-institution-ref.xml
http://www.sample-institution.org/xbrl/taxonomies/aaaa-mm-dd/sample-institution-pre.xml
http://www.sample-institution.org/xbrl/taxonomies/aaaa-mm-dd/sample-institution-def.xml
http://www.sample-institution.org/xbrl/taxonomies/aaaa-mm-dd/sample-institution-cal.xml
http://www.sample-institution.org/xbrl/taxonomies/aaaa-mm-dd/balance/balance-pre.xml
http://www.sample-institution.org/xbrl/taxonomies/aaaa-mm-dd/balance/balance-cal.xml
http://www.sample-institution.org/xbrl/taxonomies/aaaa-mm-dd/balance/balance-def.xml
http://www.sample-institution.org/xbrl/taxonomies/aaaa-mm-dd/profit-loss/profit-loss-pre.xml
http://www.sample-institution.org/xbrl/taxonomies/aaaa-mm-dd/profit-loss/profit-loss-cal.xml
http://www.sample-institution.org/xbrl/taxonomies/aaaa-mm-dd/profit-loss/profit-loss-def.xml

The Official taxonomy starting URL is: http://www.sample-institution.org/xbrl/taxonomies/aaaa-mm-dd/
Note the trailing / character has been included in the taxonomy starting URL because that is a good practice although it is not required and will be added automatically if it does not exists

Copy of the taxonomy files: This requires collecting all files published in the official web site maintaining the same structure they have in the target web site. The taxonomy files for our example are:

sample-institution-entry-point.xsd
sample-institution-lab.xml
sample-institution-ref.xml
sample-institution-pre.xml
sample-institution-def.xml
sample-institution-cal.xml
balance/balance-pre.xml
balance/balance-cal.xml
balance/balance-def.xml
profit-loss/profit-loss-pre.xml
profit-loss/profit-loss-cal.xml
profit-loss/profit-loss-def.xml

Note there are 2 sub directories one called balance and the other called profit-loss, then, the root folder contains 6 files and each of the sub-folders contains 3 files.

A name for the taxonomy: We need to provide a name to the entire package that will appear as the taxonomy name under the catalog user interface. In our example, the taxonomy name will be Sample Institution Taxonomy aaaa-mm-dd

Step 2: Prepare the xbrlCacheInfo.properties file

All taxonomy data is stored in a text file with a fixed name the taxonomy catalog subsystem will read the content of that file before generating the user interface. Here is a sample file content:

The file name is xbrlCacheInfo.properties and the content is as follows:

#Reporting Standard Metadata about the taxonomy in the chache
name=Sample Institution Taxonomy aaaa-mm-dd
uriStartString=http://www.sample-institution.org/xbrl/taxonomies/aaaa-mm-dd/

This file must be located in at the root folder of our copy of the taxonomy files. This is the same folder you have stored the sample-institution-entry-point.xsd file.

Every line in that file that starts with the hash sigh # is a comment.

Every line that contains a word, the equal sign = and a sentence is a property.

The name property contains the taxonomy name as we would like to see it in the taxonomy catalog

The uriStartString property contains the official taxonomy entry point

Step 3: Prepare a ZIP file

Create a ZIP file with the directory structure of the target web site and add to the root folder of the ZIP file all files in the target web site and the xbrlCacheInfo.properties file.

Make sure the target ZIP file does not contains one additional root folder. In the root folder of the ZIP there must be the 6 files from the target taxonomy plus the xbrlCacheInfo.properties file.

The ZIP name is not relevant at all, in our example we are going to call it sample-institution.zip

Step 4: Locate the local XBRL Catalog root directory

The XBRL Taxonomy Catalog can be installed in a specific location in your hard drive. If this is the case there must be an environment variable called XBRLCATALOGPATH whose value is the directory where the XBRL Taxonomy Catalog starts. The default location on windows is the value of the %ProgremData% environment variable followed by a folder called ReportingStandardXBRLTools, on windows 7 and beyond, the location is C:\ProgramData\ReportingStandardXBRLTools

In that folder there must be a file called RSZIPCatalog.xml that file contains pointers to all ZIP files that are actually copies of content of official taxonomies in the world. There is one XML Schema with the XML file format and the XML Schema will tell advanced users how to use advanced properties. In our example we are going to add a new entry on that file with the following content:

  <package file="taxonomy-packages/sample-institution.zip"/>

The <package> element contains one attribute called file the attribute value is a relative location of the ZIP file with the taxonomy content. The content of the file attribute is resolved against the RSZIPFile.xml file location.

Step 5: Save the ZIP file in the final folder

The last step is to put the generated ZIP file into the taxonomy-packages folder that is located under the C:\ProgramData\ReportingStandardXBRLTools folder.

Now you should be able to use your local copy of the official taxonomy files from the local taxonomy catalog.

References

XBRL Catalog
The XBRL Taxonomy Catalog
Select Taxonomy From Catalog