XBRLTaxonomy
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 XBRL Taxonomies, and
- all references to external and embedded XBRL Linkbases, and
- all other XML Schema related constructions like global groups, global type declarations, global attribute groups, global attribute declarations and global 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:
- 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.
- 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.
Working with Role Types
The use of role types in XBRL comes originally from the XLink specification. The idea of the authors of the XLink specification was to allow document authors to put additional information on XLink related elements about the role of the elements (locators, arcs and resources) so the consuming applications can do something with them. In XBRL we did three things:
- we standardize the definition of some role types in the XBRL 2.1 specification
- we allow a standard mechanism in the XBRL 2.1 specification so new role types can be defined in taxonomies
- we provide semantic meaning to the use of role types on different elements like resources and extended links.
In this section about taxonomies we are not going to explore all possibilities about role types, our goal is to let you know that the XBRL API allows you to:
- find role types in the DTS (defined in the XBRL spec or in the loaded taxonomies)
- add new role types to the DTS
- delete existing role types (only if they are not defined in the XBRL spec)
Read access
The method [getRoleTypes()] returns an iterator over all role types XBRLRoleType defined in this taxonomy. The method [getRoleTypeByURI(String URI)] returns a role type XBRLRoleType object if there is a role type defined in this taxonomy for the corresponding URI value.
Note, there is a [getRoleType(String URI)] method in the DTSContainer object that returns a role type XBRLRoleType regardless in which taxonomy the role type is defined or if the role type is a static role type defined in the XBRL 2.1 specification.
Write access
The method [addRoleType(XBRLRoleType newRole)] adds a new role type to the taxonomy. The method [removeRoleType(XBRLRoleType roleType)] removes an existing role from the taxonomy. Both methods are automatically called by the XBRLRoleType class when it is necessary so there should be no need to call this methods manually from XBRL applications.
Working with Arcrole Types
The use of arcrole types in XBRL comes originally from the XLink specification. The idea of the authors of the XLink specification was to allow document authors to put additional information on XLink arcs so the consuming applications can do something with them. In XBRL we did two things:
- we standardize the definition of some arcrole types in the XBRL 2.1 specification
- we allow a standard mechanism in the XBRL 2.1 specification so new arcrole types can be defined in taxonomies
In this section about taxonomies we are not going to explore all possibilities about arcrole types, our goal is to let you know that the XBRL API allows you to:
- find arcrole types in the DTS (defined in the XBRL spec or in the loaded taxonomies)
- add new arcrole types to the DTS
- delete existing arcrole types (only if they are not defined in the XBRL spec)
Read access
The method [getArcroleTypes()] returns an iterator over all arcrole types XBRLArcroleType defined in this taxonomy. The method [getArcroleTypeByURI(String URI)] returns an arcrole type XBRLArcroleType object if there is an arcrole type defined in this taxonomy for the corresponding URI value.
Note, there is a [getArcroleType(String URI)] method in the DTSContainer object that returns an arcrole type XBRLArcroleType regardless in which taxonomy the arcrole type is defined or if the arcrole type is a static arcrole type defined in the XBRL 2.1 specification.
Write access
The method [addArcroleType(XBRLArcroleType newArcrole)] adds a new arcrole type to the taxonomy. The method [removeArcroleType(XBRLArcroleType arcroleType)] removes an existing arcrole from the taxonomy. Both methods are automatically called by the XBRLArcroleType class when it is necessary so there should be no need to call this methods manually from XBRL applications.
Working with Imported Taxonomies
An XBRL Taxonomy (which is an XML Schema) can reference other XBRL Taxonomies (that, in turn are other XML Schemas) using the XML Schema <xsd:import namespace="..." schemaLocation="..."/> statement. This facilitates that all required pieces to make a taxonomy meaningful are always read together. For example; global type definitions can be all defined in separate smaller XML Schemas so they can be reused from one taxonomy version to the next one if there are no changes in the business model that is behind the type definition.
The XBRL API allows the user to get access to the imported schemas of a taxonomy schema and to add and remove imported schemas manually. The surrounding class that represents imports is XBRLImport. That class automatically takes care of consistency.
Read access
The method [getImports()] returns an iterator over all XBRLImport objects of this taxonomy schema. The method [getImport(String namespaceURI)] returns the imported schema that corresponds to the namespace indicated in the parameter or null if the taxonomy schema for that namespace is not found.
Write access
The method [addImport(XBRLImport import)] adds a new import to the current taxonomy schema. The method [removeImport(XBRLImport import)] removes an import from the list of imported schemas on the current taxonomy. The XBRLImport class already takes care of calling addImport and removeImport in the parent object during calls to the [setParent(XBRLTaxonomy parent)] method so there should be no need to call this methods directly from client code.
Working with external and embedded linkbases
XBRL Linkbases are containers of extended links. For more information about this topic visit the wiki page about the XBRLLinkbase document object. An XBRL Taxonomy may contain either references to external linkbases or embeded linkbases. Applications working with the content of an XBRL Taxonomy can explore and change all linkbases that are referenced or embedded in an XBRL Taxonomy using simple API calls.
Read access
A call to the method [getLinkbases()] returns an iterator over all linkbases that are embedded or referenced from this taxonomy schema. The iterator returns objects of the type XBRLLinkbase. An embedded linkbase can be easily diferenciated from a referenced linkbase because the parent of an embedded linkbase is always an XBRL Taxonomy schema and the parent object of a referenced linkbase (external to the taxonomy) is the same referenced linkbase.
Write access
The user can call the method [addLinkbase(XBRLLinkbase newLinkase)] in order to add an embedded or external linkbase to an XBRL Taxonomy. The user can call the method [removeLinkbase(XBRLLinkbase linkbase)] in order to remove an existing external or embedded linkbase from this XBRL Taxonomy. Note the user must explicitly call addLinkbase and removeLinkbase methods in order to create the DTS structure they want.
Working with global XML Schema objects
The semantics of elements of an XBRL Taxonomy are defined on top of the syntax of an XML Schema. For that reason mixing XBRL specific content as XBRL concept definitions with specific XML Schema content as global attributes is valid according to the XBRL Specification. The XBRL API allows users to define global elements to be added to an XBRL Taxonomy and provides also methods for accessing to that content if that content exist on the taxonomy.
The 4 groups of information are:
- global attribute definitions
- global attribute group definitions
- global group definitions
- global type definitions
Read access
For the four groups defined in the previous section:
- The method [getGlobalAttributes()] provides access to an iterator over all defined global attributes. The method [getGlobalAttributeByName(String name)] provides access to a global attribute definition using the attribute name as a key.
- The method [getGlobalAtributeGroups()] provides access to an iterator over all defined global attribute groups. The method [getGlobalAttributeGroupByName(String name)] provides access to a global attribute group definition using the attribute group name as a key.
- The method [getGlobalGroups()] provides access to an iterator over all defined global element groups. The method [getGlobalGroupByName(String name)] provides access to a global group of elements using the group name as a key.
- The method [getGlobalTypes()] provides access to all global types (simple types and complex types). The method [getGlobalTypeByName(String name)] provides access to a global type definition using the type name as key.
Write access
For the four groups defined in the previous section:
- The method [addGlobalAttribute(XMLFragment)] allows the user to add a new global attribute definition to the taxonomy. The method [delGlobalAttribute(String name)] allows the user to remove the definition of a global attribute.
- The method [addGlobalAttributeGroup(XMLFragment)] allows the user to add a new global attribute group. The method [delGlobalAttributeGroup(String name)] allows the user to remove the definition of a global attribute group.
- The method [addGlobalGroup(XMLFragment)] allows the user to add a new global element group to the taxonomy. The method [delGlobalGroup(String name)] allows the user to remove the definition of a global element group.
- The method [addGlobalType(XMLFragment)] allows the user to add a new global type declaration to the taxonomy. The method [delGlobalType(String name)] allows the user to remove an existing type declaration.
