XBRLTaxonomy

[XBRLTaxonomy javadoc page]

Description

An XBRLTaxonomy object represents the content of an XBRL Taxonomy and the surrounding XML Schema. This is:

• the Namespace, and
• all XBRL concept definitions (items and tuples) , and
• all XBRL role types locally defined, and
• all XBRL arcrole types locally defined, and
• all references to imported and included XBRLTaxonomies, and
• all references to XBRLLinkbases, and
• all embedded XBRLLinkbases, and
• all other XML Schema related elements like groups, type declarations, global attribute groups, global attribute declarations and element declarations that are not XBRL concepts.

How to create an instance of an XBRLTaxonomy object

There are several ways depending on what the user needs are:

• If the user have just created a new empty DTSContainer object and the purpose is to read the content of an XBRL taxonomy (and the whole referenced DTS) then the simplest way is to use one of the load methods in the DTSContainer object passing the document URI of the XBRL taxonomy. The returned object is an XBRLTaxonomy that can be casted to an XBRLTaxonomy.

• If the user has already loaded a DTS (from another taxonomy file or an XBRL report) and the purpose is to create a new XBRLTaxonomy (in order to create a taxonomy extension) then, the user can use any of the available constructors. The most commonly used constructor is XBRLTaxonomy(com.ihr.xbrl.om.DTSContainer) that accepts the current DTSContainer as a parameter and allows the user to start adding concepts programatically.

Creation of a XBRLTaxonomy object from a local file name: <syntaxhighlight lang="java"> /**

* Sample, a new XBRLTaxonomy document is read form the file received as a parameter
* After the instance object is obtained, the user can start working with it
*/

public class SampleReadTaxonomy {

 public static void main(String[] args) throws Exception {
   DTSContainer dts = DTSContainer.newEmptyContainer();
   XBRLTaxonomy taxonomy = (XBRLTaxonomy)dts.load(new File(args[0]).toURI());
   // ... rest of the application code goes here
 }

} </syntaxhighlight>

Creation of a new taxonomy document for a DTS after the DTS has been loaded: <syntaxhighlight lang="java"> /**

* Sample, a new instance document is created after the DTS has been loaded
*/

public class SampleCreateTaxonomyExtension {

 public static void main(String[] args) throws Exception {
   DTSContainer dts = DTSContainer.newEmptyContainer();
   dts.load(new File("sampleTaxonomy.xsd").toURI());

   XBRLTaxonomy taxonomy = new XBRLTaxonomy(dts);

   // adds taxonomy default minimum information
   String targetNamespace = "http://www.reportingstandard.com/samples/2009/newTaxonomy";
   tx.setURI(new URI("taxonomyExtension.xsd"));
   tx.setTargetNamespace(targetNamespace);
   tx.addNamespace("tx", targetNamespace);
   dts.addDocumentToDTS(tx);

   // ... rest of the application code goes here

   // Save the Taxonomy extension to disk
   dts.save(true);
 }

} </syntaxhighlight>

The Namespace

XBRL Taxonomies are the containers of concept definitions. Concept definitions must be unique worldwide (assets in the US-GAAP and assets in the IFRS). The mechanism provided by the W3C consortium in order to allow easy distinction between concepts defined in different taxonomies is called namespaces.

Each taxonomy is an XML Schema. An XML Schema may define a Namespace. The namespace is a unique name that may be of a form of a URI (Unique Resource Identifier).

For example:

• IFRS 2009 concepts namespace is: http://xbrl.iasb.org/taxonomy/2009-04-01/ifrs
• US-GAAP 2009 concepts namespace is: http://xbrl.us/us-gaap/2009-01-31

Here is the [link for the Namespaces specification] at the W3C consortium.

Read access

The API call [getTargetNamespace()] gives direct access to the taxonomy namespace.

Write access

The API call [setTargetNamespace(String namespace)] sets or changes the taxonomy namespace.

Working with concept definitions

We can classify XBRL Taxonomies in two categories:

1. Taxonomies that defines new concepts: They are XBRL Taxonomies that contains new concept definitions. A concept definition is an element in the item or tuple substitution group. Normally, Taxonomies that defines new concepts also include references to the labels and reference linkbases.
2. Taxonomies that does not define new concepts: They are XBRL Taxonomies that serves organize the content of the DTS, for example, including a common set of presentation and calculation linkbases together.

Read access

While working with an XBRL Taxonomy, the user may be interested in accessing concepts defined. The XBRLTaxonomy API provides methods for exploring all concept definitions [getConcepts()], [getItems()] and [getTuples()] or access to individual concepts if the concept name is known [getElementDefinitionByName(String name)] or the id [getElementDefinitionById(String id)].

Note: the DTSContainer object contains a method [getConcept(QName qname)] to access to a concept defined in the DTS regardless in which taxonomy the concept is defined. The parameter to that function is the concept QName. Sometimes it is more convenient using that function than having to obtain the XBRLTaxonomy first and ask for the concept later.

Write access

The XBRLTaxonomy API has two methods [addElement(XMLElementDefinition)] and [delElement(XMLElementDefinition)] that allows the user to add or delete concept definitions from an XBRLTaxonomy. The XBRLItem, XBRLTuple and XMLElementDefinition already takes care of calling this methods if the parent argument is properly set. So there should be no need to worry about consistency about what concepts belongs to what taxonomy.

Note: if you change a concept from one taxonomy to another, the concept local name will not be changed, but the concept namespace will no longer be the old namespace.