Compiled taxonomy structure

The output of the taxonomy compilation process is a file that can be loaded quickly by the PHP engine complete with indexes for efficient processing in memory.

###JSON

Taxonomy data is stored in the file using the JSON format using the PHP function json_encode. This function is called by the 'XBRL' function toJSON.

This project almost exclusively uses arrays to represent taxonomy information but usually these are indexed (or associative) arrays. In other languages such as C# or Java these arrays would be knows as 'dictionaries' or 'hashtables'. In JSON such arrays are represented as objects (data enclosed in curly braces). In JSON arrays (data enclosed in square brackets) are arrays without an index.

When a compiled taxonomy is loaded the internal function fromJSON is called which uses the PHP function json_decode. The first parameter of json_decode is the name of a string variable containing the JSON content to load (or a filename). The parameter second controls how PHP will load JSON objects (data enclosed in curly braces). By default or if the second parameter is 'false' then PHP will create 'StdClass' instances for all objects. If the second parameter is 'true' then objects are loaded as indexed (or associative) arrays. The function fromJSON sets the second parameter to 'true' so JSON objects are loaded as indexed arrays.

Top level items

When using JSON the outer container is almost always an object so the high level items can be identified by name. In a compiled file there are four top level items as depicted in this snippet:

{
	"schemas" : { ... },
	"context" : { ... },
	"mainNamespace" : "http:\/\/blah.blah.blah/...",
	"baseTaxonomy" : null
}

A review of the content of the 'schemas' and of the 'context' object can found below as these are the most important items.

'mainNamespace' identifies which of the schemas defined in the 'schemas' object will be the default taxonomy after the load is completed.

'baseTaxonomy' is used by extension taxonomies to identify the namespace of the taxonomy they extend.

There is an implication here specifically for extension taxonomies but also more generally for all compiled taxonomies. The implication is that the 'XBRL' class descendant which was used to create the compiled taxonomy file is available on the system in which the file is being loaded. If a compiled file is moved from one machine to another and the machine to which the file is moved does not contain an 'XBRL' instance that defines the namespace specified by the 'baseTaxomony' item, it will not be possible to load the compiled taxonomy.

This is because this code will attempt to identify the correct taxonomy class ('XBRL' descendant) by looking up the namespace given in the compiled file to discover the name of the concrete class to use. If the class used to compile the taxonomy does not exist, then the lookup cannot succeed.

So it is important that not only is the compiled file moved from one machine to another but the concrete 'XBRL' implementation for the respective taxonomy is moved as well.

###Discoverable Taxonomy Set (DTS)

Before going on, it's worth emphasising that most major taxonomies are a collection of sub-taxonomies each representing a component that contributes a part of the whole. But any single user of the taxonomy may only require a subset of the possible components. For example, in the US GAAP taxonomy there are 26 possible statements and 77 disclosures. Each is a separate taxonomy with its own schema (.xsd) file and, possibly, presentation, definition and calculation linkbases. In the UK GAAP taxonomy there are schemas to represent countries, currencies, exchanges, languages and common business terms.

However the taxonomies are structured, the collection of main and sub-taxonomies are collectively known as a discoverable taxonomy set or DTS.

##Context

In memory each component taxonomy (each of which is part of the larger DTS) is represented by an 'XBRL' descendant instance. Potentially, each component taxonomy will need to know about the other taxonomies because there is often a lot of cross-referencing. There are rule about the limits to this cross-referencing in the specification but this is not intended to be a specification tutorial. What is important is to know that the context provides the mechanism by which one taxonomy component instance ('XBRL' descendant instance) is able to locate as access information in another instance.

Imported Schema

The context is a singleton object shared by all 'XBRL' descendant instances so one instance can find another if the need arises.

In memory the context includes an array of 'XBRL' instances called 'importedSchemas'. This array is indexed by namespace so any one XBRL instance is able to access any other instance if they know the namespace.

Labels

Another important purpose of the shared context is to hold labels from taxonomies across the DTS. In XBRL the term 'label' is ambiguous because it can either mean a description of something, such as an element, or it can mean an XLink identifier. In this case it is synonymous with 'description.

In the compiled file, the top level item called 'context' is the part of the in-memory shared context that stores labels.

For anyone element there can be multiple labels. Of course, language is one reason to have different labels but even within one language it can be helpful for an element to have multiple labels with each label having a different 'role' such as 'verbose', 'terse', 'example', etc.. There are a set of pre-defined roles but taxonomies are free to define their own additional roles if needed.

###Schemas