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.

Expand for details

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.

Expand for details

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.

	"context" : {
		"labels" : { ... },
		"labelLinkRoleRefs" : { ... },
		"labelRoleRefs" : { ... }
	}

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.

Element	Comment
labels	This element contains a series of entries, though usually only one, for each labelLinkRoleRef. The link roles are usually defined once per schema in the schema document (.xsd) or in the label link base. "labels" : { "http://www.xbrl.org/2003/role/documentation" : { "en" : { "uk-common_NotApplicable_lbl" : { "text" : "Indicates ..." }, }, }, }, Within each link role ref labels themselves are grouped by label role, in this case 'documentation' and then language. Each label (description) is indexed by it's locator label (xlink).
labelLinkRoleRefs	This is the definition of the label link role in the taxonomy. Usually there is only one link role with the uri http://www.xbrl.org/2003/role/link. "labelLinkRoleRefs" : { "http://www.xbrl.org/2003/role/link" : { "type" : "simple", "href" : ".../a_taxonomy/tax-2009-09-01-label.xml", "roleUri" : "http://www.xbrl.org/2003/role/link" } },
labelRoleRefs	Label roles define the different types of role being used by the taxonomy. There are 22 default roles though typically only 3 or 4 are used. "labelRoleRefs" : { { ... }, "http://www.xbrl.org/2003/role/terseLabel" : { "type" : "simple", "href" : "uk-gaap-2009-09-01.xsd#terseLabel", "roleUri" : "http://www.xbrl.org/2003/role/terseLabel" }, "http://www.xbrl.org\/2003\/role\/verboseLabel" : { "type" : "simple", "href" : "uk-gaap-2009-09-01.xsd#verboseLabel", "roleUri" : "http://www.xbrl.org/2003/role/verboseLabel" }, { ... } }

###Schemas

The schemas element of the compiled file represents an array that contains the details of all the taxonomies found in the DTS indexed by the taxonomy's namespace. So for each namespace there are taxonomy details like those shown below.

"schemas" : {
	"http://www.xbrl.org/uk/gaap/core/2009-09-01" : {
		"elementIndex" : { ... },
		"elementHypercubes" : [ ... ],
		"elementDimensions" : [ ... ]
		"schemaLocation" : "/some path/my schema.xsd",
		"namespace" : "https://my.company.org/a-namespace",
		"roleTypes" : { ... },
		"linkbaseTypes" : { ... },
		"definitionRoleRefs" : { ... },
		"calculationRoleRefs" : [],
		"presentationRoleRefs" : { ... },
		"referenceRoleRefs" : [],
		"documentPrefixes" : { ... }
	},
	...
}

Expand for details

In this section the elements used in each member of the schema array will be reviewed.

Element	Comment
elementIndex	The element index is the master list of all s defined in the taxonomy schema document indexed by the id of the elements. `Here is an example. These values are repeated wherever information about a specific element is require - for example in the presentation hierarchy. <pre>` "uk-gaap_AccountTypeDimension-AppliesToAllDataHeading" : { "id" : "uk-gaap_AccountTypeDimension-AppliesToAllDataHeading", "name" : "AccountTypeDimension-AppliesToAllDataHeading", "type" : "xbrli:stringItemType", "substitutionGroup" : "xbrli:item", "abstract" : 1, "nillable" : 1, "periodType" : "duration" },
elementHypercubes	This a list of element ids that represent hypercubes in the definition link base.
elementDimensions	This a list of element ids that represent hypercube dimensions in the definition link base.
schemaLocation	This is the physical location of the schema file (.xsd)
namespace	The namespace given to this taxonomy
roleTypes	The taxonomy will usually define the role types used in different linkbases. In the current implementation only definition and presentation linkbases are used so only these roles are recorded. `Generally, the definition linkbase roles define hypercubes or maybe dimensions. Presentation linkbase roles define the different sections or statements supported by the taxonomy. <pre>` "roleTypes" : { "link:presentationLink" : { "http://mytaxonomy/role/ProftAndLossAccount" : { "definition" : "10 - Profit and Loss Account", "roleURI" : "http://mytaxonomy/role/ProftAndLossAccount", "taxonomy" : "some.xsd", "id" : "IncomeStatement" }, { ... }, }, "link:definitionLink" : { "http://mytaxonomy/role/Dimension-GroupAndCompany" : { "definition" : "100 - Group and Company", "roleURI" : "http://mytaxonomy/role/Dimension-GroupAndCompany", "taxonomy" : "some.xsd", "id" : "Dimension-GroupAndCompany" }, { ... }, }, }
linkbaseTypes	The linkbase types are taken from the schema document where they identify the type of the linkbase (what linkbase role it has) and the location of the file containing linkbase definition. Standard linkbase roles include calculation, definition, presentation and reference. `The block below shows typical information contained in a linkbaseType: <pre>` "linkbaseTypes" : { "http://mytaxonomy/role/definitionLinkbaseRef" : [{ "type" : "simple", "href" : "some-definition.xml", "role" : "http://www.xbrl.org/2003/role/definitionLinkbaseRef", "arcrole" : "http://www.w3.org/1999/xlink/properties/linkbase", "title" : "Definition Links, all" }], { ... } }
definitionRoleRefs	This section is very important and will be covered in its own section. In the meantime here is a review of a section showing summary information for one role. `<pre>` "http://mytaxonomy/role/Hypercube-IncomeDataAllDimensions" : { "href" : "some.xsd#Hypercube-IncomeDataAllDimensions", "roleUri" : "http://mytaxonomy/role/Hypercube-IncomeDataAllDimensions", "type" : "simple", "locators" : { ... }, "hierarchy" : { ... }, "members" : [], "hypercubes" : { ... }, "primaryitems" : { ... }, "dimensions" : { ... }, "paths" : { ... } } This information can be accessed using the 'XBRL' class function getDefinitionRoleRefs. `<pre>` $taxonomy->getDefinitionRoleRefs();
calculationRoleRefs	This is not currently used
presentationRoleRefs	This section is very important and will be covered in its own section. In the meantime here is a review of a section showing summary information for one role. `<pre>` "presentationRoleRefs" : { "http://mytaxonomy/role/ProftAndLossAccount" : { "type" : "simple", "href" : "some.xsd#IncomeStatement", "roleUri" : "http://mytaxonomy/role/ProftAndLossAccount", "hierarchy" : { ... }, "locators" : { ... }, "path" : { ... } }, { ... } } This information can be accessed using the 'XBRL' class function getPresentationRoleRefs. `<pre>` $taxonomy->getPresentationRoleRefs();
referenceRoleRefs	This is not used
documentPrefixes	This is an array of the namespaces in the taxonomy schema document indexed by their prefix in the the schema. Because this is stored code can access the original namespaces and this array by calling: `<pre>` $taxonomy->getDocumentNamespaces(); `If the prefix is known - which is often the case because the prefix is part of the element id - the namespace for a specific prefix can be retrieve using another function on the 'XBRL' class: <pre>` $taxonomy->getNamespaceForPrefix();