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();

###Definition linkbase

The main use for the definition linkbase is to define hypercubes, dimensions, members and primary items.

Expand for details

####Dimensions vs Hypercubes

Definition roles define Dimensions or Hypercubes. Hyppercubes will be used to define the dimensions added to elements that are called Primary Items. Hypercubes can define dimensions. However a taxonomy can define dimensions that are to be included in one or more different hypercube by a reference.

####Locators

Locators is an array representing the elements in the linkbase. The array is indexed by the XLink label while the values are a uri which is made from the schema file name and a fragment which is the id of the in the schema file.

####Hierarchy

Both hypercubes and dimensions include a hierarchy. The hierarchy is a node tree. In the case of the hypercube it describes the dimensions and members associated with the hypercubes.

Dimensions have a hierarchy that defines a root node - the dimension itself - and then a domain and members. Members can be leaf nodes but can also have children. It's possible to tell if a node is a member because the id will be listed in the members array and it will be in the substitution group xbrli:item. Dimensions will be in the dimensions array and will be in the substitution group xbrli:dimensionItem. Dimension domains will be in the substitution group xbrli:dimensionItem. If the member is also the domain it will have an arc role relationship with its parent of dimension-domain.

The hypercube hierarchy is more complex. The root is a container. Within the container will be the hypercube itself and all the primary items. Primary items are that are expected to have values in an instance document. They can have structure. A primary item can have children that are also primary items.

The hypercube has children that define the dimensions associated with the hypercube. The dimension definition can be in-line. That is, the domain and members defined within the hypercube definition. Or the dimension definition can reference a dimension in the same or another taxonomy. If the dimension definition is not in-line then the dimension definition will include a targetRole. This will identify the linkbase role that defines the dimension. The namespace is also available so it is possible to learn in which taxonomy the linkbase is defined.

####Hypercubes

A list of the elements that are hypercubes (have an 'all' or 'not-all' arc role).

####Dimensions

A list of the elements that are dimensions (have an arc role relationship with the hypercube of hypercube-dimension and are in the substitution group xbrli:dimensionItem).

####Members

A list of the elements that are dimension member (have an arc role relationship with the dimension domain of dimension-domain and are in the substitution group xbrli:item).

####Primary items

A list of that are associated with the hypercube.

###Presentation linkbase

The main use for the definition linkbase is to define hypercubes, dimensions, members and primary items.

Expand for details

####Locators

Locators is an array representing the elements in the linkbase. The array is indexed by the XLink label while the values are a uri which is made from the schema file name and a fragment which is the id of the in the schema file.

####Hierarchy

The presentation linkbase defines parent-child relationships between s for each role in a taxonomy. The hierarchy is the manifestation of those parent-child links.

####Paths

This is an index. This is a list of strings, indexed by the id of an element, that describes how to navigate the hierarchy to find a node with the index id. The purpose of this array is to make finding the node(s) much quicker. The alternative is to scan the whole hierarchy which will get slower and slower the more nodes there are to search.