Taxonomy Caches

XBRL filings contain references pointing to external URLs where taxonomy files are located. In normal circumstances, the referenced URLs are available for access on the internet and reading the taxonomy files is required to process the filing. Reading files from the Internet, however is a slow process and accessing the Internet may not be allowed in some installations.

A taxonomy cache is a local repository of taxonomy files that the Infoset Generator can consume as if they were coming from the Internet. If a taxonomy file is present in the cache it is consumed as if it was read from the official location but the file is read from the hard drive. Caching taxonomy files greatly improves the Infoset Generator performance. Moreover, any filing for which all referenced taxonomy files are present in the cache can be processed offline.

The Infoset Generator supports three main ways to cache taxonomy files, all of which can be used at the same time:

  1. Oasis Taxonomy Catalogs is good to map local files extracted in a directory that exactly matches the structure of the files on an official web site.
  2. XBRL International Taxonomy Packages. If the Taxonomy files are already in the XBRL International Taxonomy Package format, it is the simplest alternative. In this case the user does not need to specify any metadata file.
  3. Reporting Standard Taxonomy Catalog is more complex but allows to store taxonomy files compressed and thus is a good way to distribute taxonomy packages. This method requires the user to define two metadata files. For more information contact 28msec support at support@28.io.

In any case, after updating the cache the Infoset Generator must be restarted as described in the section "Starting/Stopping the Infoset Generator" of the Infoset Generator installation guide.

OASIS Catalog

The overall process is the following:

  1. Copy the taxonomy files to the folder <INFOSETGENERATOR_FOLDER>/taxonomy-cache, creating the folder if necessary and respecting the same structure of the official website.
  2. Create or update the OASIS catalog file <INFOSETGENERATOR_FOLDER>/XBRLCatalog.xml describing the newly added taxonomy files.
  3. Restart the Infoset Generator

For instance, assume that you want to cache the following files:

http://www.xbrl.org/dtr/type/nonNumeric-2009-12-16.xsd
http://www.xbrl.org/dtr/type/numeric-2009-12-16.xsd
http://www.xbrl.org/lrr/arcrole/factExplanatory-2009-12-16.xsd
http://www.xbrl.org/lrr/arcrole/deprecated-2009-12-16.xsd
http://xbrl.ifrs.org/taxonomy/2012-03-29/full_ifrs/ias_8_2012-03-29/rol_ias_8_2012-03-29.xsd
http://xbrl.ifrs.org/taxonomy/2012-03-29/full_ifrs/ias_8_2012-03-29/gla_ias_8_2012-03-29-en.xml

We suggest to store a file whose URI is http://<URI_PATH> at <INFOSETGENERATOR_FOLDER>/taxonomy-cache/<URI_PATH>. Note that usually taxonomy files already come organized in the same structure as their URI, thus in general a single copy command is necessary.

For instance, we would write our files to the following locations:

<INFOSETGENERATOR_FOLDER>/taxonomy-cache/www.xbrl.org/dtr/type/nonNumeric-2009-12-16.xsd
<INFOSETGENERATOR_FOLDER>/taxonomy-cache/www.xbrl.org/dtr/type/numeric-2009-12-16.xsd
<INFOSETGENERATOR_FOLDER>/taxonomy-cache/www.xbrl.org/lrr/arcrole/factExplanatory-2009-12-16.xsd
<INFOSETGENERATOR_FOLDER>/taxonomy-cache/www.xbrl.org/lrr/arcrole/deprecated-2009-12-16.xsd
<INFOSETGENERATOR_FOLDER>/taxonomy-cache/xbrl.ifrs.org/taxonomy/2012-03-29/full_ifrs/ias_8_2012-03-29/rol_ias_8_2012-03-29.xsd
<INFOSETGENERATOR_FOLDER>/taxonomy-cache/xbrl.ifrs.org/taxonomy/2012-03-29/full_ifrs/ias_8_2012-03-29/gla_ias_8_2012-03-29-en.xml

If the file <INFOSETGENERATOR_FOLDER>/XBRLCatalog.xml does not exist, create one with the following content:

<?xml version="1.0" encoding="UTF-8"?>
<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:schemaLocation="urn:oasis:names:tc:entity:xmlns:xml:catalog Catalog.xsd">

  <!-- Add entries here -->

</catalog>

Now we need to define how URIs are mapped to files in the filesystem. We do so through in rewriteURI elements in the <INFOSETGENERATOR_FOLDER>/XBRLCatalog.xml file. These elements define two attributes: uriStartString (e.g.: http://www.xbrl.org/) and rewritePrefix (e.g. taxonomy-cache/www.xbrl.org/). Whenever the Infoset Generator needs to load a taxonomy file it checks whether its URI starts with one of the defined uriStartStrings. If it does, the Infoset Generator replace the matching uriStartString in the URL with the corresponding rewritePrefix. For instance the URI http://www.xbrl.org/dtr/type/nonNumeric-2009-12-16.xsd would be rewritten as taxonomy-cache/www.xbrl.org/dtr/type/nonNumeric-2009-12-16.xsd. If this file exists, it is loaded from disk. Otherwise the file is loaded from the original URI.

To cache the example files we need to add the following two rewriteURI elements.

<rewriteURI uriStartString="http://www.xbrl.org/" rewritePrefix="taxonomy-cache/www.xbrl.org/" />
<rewriteURI uriStartString="http://xbrl.ifrs.org/" rewritePrefix="taxonomy-cache/xbrl.ifrs.org/" />

The resulting <INFOSETGENERATOR_FOLDER>/XBRLCatalog.xml would be:

<?xml version="1.0" encoding="UTF-8"?>
<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xsi:schemaLocation="urn:oasis:names:tc:entity:xmlns:xml:catalog Catalog.xsd">

  <rewriteURI uriStartString="http://www.xbrl.org/" rewritePrefix="taxonomy-cache/www.xbrl.org/" />
  <rewriteURI uriStartString="http://xbrl.ifrs.org/" rewritePrefix="taxonomy-cache/xbrl.ifrs.org/" />

</catalog>

Restart the Infoset Generator as described in the section "Starting/Stopping the Infoset Generator" of the Infoset Generator installation guide. For instance, assuming we created a systemd service during installation:

sudo systemctl stop infoset-generator
sudo systemctl start infoset-generator

XBRL International Taxonomy Packages

To add a ZIP archive compliant to the XBRL International Taxonomy Packages standard you can just create the folder <INFOSETGENERATOR_FOLDER>/xbrl-packages and copy the ZIP archive in it.

Restart the Infoset Generator as described in the section "Starting/Stopping the Infoset Generator" of the Infoset Generator installation guide. For instance, assuming we created a systemd service during installation:

sudo systemctl stop infoset-generator
sudo systemctl start infoset-generator