View source for Adding taxonomies to the ZIP Catlog

==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:

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

The Official taxonomy starting URL is:
{{color|blue|<nowiki>http://www.sample-institution.org/xbrl/taxonomies/aaaa-mm-dd/</nowiki>}}<br/>
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:

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

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 {{color|blue|''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:
<pre>
#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/
</pre>

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:

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

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]]<br/>
[[The XBRL Taxonomy Catalog]]<br/>
[[Select Taxonomy From Catalog]]<br/>