XBRLInstance
Description
An XBRLInstance object represents the content of an XBRL Report. This is:
- all XBRL facts , and
- all XBRL contexts, and
- all XBRL units, and
- all Footnote Linkbases, and
- all references to XBRLTaxonomies, XBRLLinkbases, XBRLRoleRef and XBRLArcroleRef required for obtaining the DTS.
How to create an instance of an XBRLInstance 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 report (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 report. The returned object is an XBRLDocument that can be casted to an XBRLInstance.
- If the user has already loaded a DTS (from a taxonomy file) and the purpose is to create a new XBRLInstance (in order to populate it with facts) then the user can use any of the available constructors. The most commonly used constructor is XBRLInstance(com.ihr.xbrl.om.DTSContainer) that accepts the current DTSContainer as a parameter and allows the user to start adding facts programatically.
Creation of a XBRLInstance object from a local file name: <syntaxhighlight lang="java"> /**
* Sample, a new instance 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 SampleReadInstance {
public static void main(String[] args) throws Exception {
DTSContainer dts = DTSContainer.newEmptyContainer();
XBRLInstance instance = (XBRLInstance)dts.load(new File(args[0]).toURI());
// ... rest of the application code goes here
}
} </syntaxhighlight>
Creation of a new instance 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 SampleCreateInstanceForDTS {
public static void main(String[] args) throws Exception {
DTSContainer dts = DTSContainer.newEmptyContainer();
dts.load(new File("sampleTaxonomy.xsd").toURI());
XBRLInstance instance = new XBRLInstance(dts);
// ... rest of the application code goes here
}
} </syntaxhighlight>
Working with facts
This section describes two abstract operations that the user can execute on XBRLInstance objects regardless the way they have been created.
The XBRLInstance object is able to automatically change in order to keep consistency during operations. For example, the action of adding a new XBRLFact item to the XBRLInstance may automatically add a new context or may reuse an existing context instead. The same happens with the unit and with the reference to the required taxonomy schema. Removing facts from the XBRLInstance is also an operation that keeps the instance document content consistent while silently removes content that is no longer used (like unused units or contexts etc).
Read access
Read access of facts in an XBRLInstance is an abstract operation implemented in several methods. The content of an XBRLInstance can be accessed in two modes: sequential mode and indexed mode. Both modes serves different purposes while working with data in an XBRLInstance. Both are described in the XBRLFactsList interface.
In this example, the content of the XBRLInstance document is sequentially accessed in document order: <syntaxhighlight lang="java">
Iterator<XBRLFact> iterF = instance.iterator();
while (iterF.hasNext()) {
XBRLFact fact = iterF.next();
// ... do some work with the fact
}
</syntaxhighlight>
Creating new
Creating a fact is a very simple task. The user just need to call the apropriate constructor depending on the type of fact to be created. The final fact types that the user can directly create are:
The API takes care automatically of the consistency inside the XBRLInstance when the user do operations with facts; for example, the action of creating a new fact automatically performs the operation of adding the new fact to the fact container (instance or tuple), take care of the fact context and unit (if it is necessary), add the taxonomy reference to the DTS if it is not in the current DTS, etc. The programmer does not need to worry about how to keep consistency in the content of the XBRLInstance object. Note that consistency does not imply XBRL Validation.
All objects representing facts above are non abstract objects in the fact object hierarchy. Objects up in the hierarchy contains shared functionalty in order to make the non abstract object meaningful. See the javadoc documentation of each one of the objects in order to learn more about the hierarchy.
The following example contains several lines of code in order to create the auxiliary objects first. Then a new XBRLFactNonNumeric fact is created. In the last line of the code, a value is assigned to the new created fact. <syntaxhighlight lang="java">
// create a context for the instant "Begning of year 2008" XBRLEntity ent = new XBRLEntity(dts,"http://www.xbrl.org/scheme","Sample Company",null); XBRLPeriod p = new XBRLPeriod(dts,"2008-01-01"); XBRLContext ctx = new XBRLContext(dts,ent,p,null);
// Obtain the concept definition of concept "A" from the DTS XBRLItem itemA = (XBRLItem)dts.getConcept(new QName(ns,"A"));
// create the Non Numeric (Text) fact item XBRLFactNonNumeric fA = new XBRLFactNonNumeric(instance,ctx,itemA);
// fA is nil until a value is assigned
fA.setValue(new StringValue("sample text value"));
</syntaxhighlight>
In this example, a new XBRLNumericFact is added to the XBRLInstance. The creation of the auxiliary objects has been omitted. <syntaxhighlight lang="java">
// create the Non Numeric (Text) fact item XBRLFactNonNumeric fA = new XBRLFactNonNumeric(instance,ctx,itemA);
// fA is nil until a value is assigned
fA.setValue(new StringValue("test"));
</syntaxhighlight>
Removing
There are several ways to remove a fact from an XBRLInstance:
- By invoking the remove(com.ihr.xbrl.om.instance.XBRLFact) method. This method is part of the XBRLFactsList interface so it is documented there.
- By invoking the XBRLFact clear() method.
- By setting the fact parent to null setParent(com.ihr.xbrl.om.instance.XBRLFactsList)
Managing the elements that compose the DTS
In normal circumnstances the user should never care about dealing with elements that compose the DTS of the XBRLInstance document. The required elements will be added automatically when the user creates the XBRLInstance object using a dts as a parameter and at the time the user adds facts to the instance document.
The only use case that cannot be automatically handled is when the user wants to add a custom existing linkbase to the DTS of the report that is not part of the DTS discovered by the taxonomy schemas already referenced. In this case, it is still possible adding those linkbases using any of the following two methods:
addXBRLDocument(com.ihr.xbrl.om.XBRLDocument, com.ihr.xbrl.om.taxonomy.XBRLRoleAndArcroleTypes)
or
The methods above can be used for adding link:schemaRef elements to the instance document as well
Working with contexts
This section describes the relationships between the context and the instance document. For more information about the context object visit the XBRLContext page.
Adding new
Under normal circumstances the user should not care about manually adding contexts to the XBRLInstance. They are added automatically when new facts are created. If for any reason there is a need to add contexts manually the method that can be used for this purpose is addContext(com.ihr.xbrl.om.instance.XBRLContext).
Read access
Normally the context is obtained from a fact item using the getContext() method of the XBRLFactItem object.
Looking at the contexts that exists in the instance document can be implemented in several ways:
- All contexts are indexed by the context id. The method getContextById(java.lang.String) returns a specific context if you know the id in advance.
- The method getContexts() returns an iterator over all contexts in the instance.
Creating new
Creating new contexts is an independent operation of the instance where the context will be serialized. Read the XBRLContext page in order to get more information about how to create a new Context.
Removing
The method delContext(com.ihr.xbrl.om.instance.XBRLContext) can be used to delete a context and all associated facts in an instance. Although the use of this method is discouraged as the contexts are automatically deleted when they are no longer referenced from facts.
Working with units
This section describes the relationships between XBRL units and the instance document. For more information about the unit object visit the XBRLUnit page.
Adding new
Under normal circumstances the user should not care about manually adding units to the XBRLInstance. They are added automatically when new numeric facts are created. If for any reason there is a need to add units manually the method that can be used for this purpose is addUnit(com.ihr.xbrl.om.instance.XBRLUnit).
Read access
Normally the unit is obtained from a numeric fact item using the getUnit() method of the XBRLFactNumeric object.
Looking at the units that exists in the instance document can be implemented in several ways:
- All units are indexed by the unit id. The method getUnitById(java.lang.String) returns a specific unit if you know the id in advance.
- The method getUnits() returns an iterator over all units in the instance.
Creating new
Creating new units is an independent operation of the instance where the unit will be serialized. Read the XBRLUnit page in order to get more information about how to create a new Unit.
Removing
The method delUnit(com.ihr.xbrl.om.instance.XBRLUnit) can be used to delete a unit and all associated facts in an instance. Although the use of this method is discouraged as the units are automatically deleted when they are no longer referenced from numeric facts.
Working with footnotes
The user can create footnote containers in an XBRLInstance object. Footnote containers will hold all required elements in order to link the footnote text (in plain text or xhtml format) to a particular fact in the instance (the fact can be numeric, non numeric or a tuple).
Creating a footnote requires some initial work on the XBRLInstance:
Create the footnotes container
A footnotes container is an XLink extended link container for XBRL footnotes. In order to create the container the user must first get the desired role type from the DTS and then call the FootnoteLinkbase constructor with the required parameters.
Here is an example about how to get the standard role URI from the DTSContainer object and then create an extended link for footnotes <syntaxhighlight lang="java">
XBRLRoleType role = dts.getStaticRoleTypeByURI(XBRLExtendedLink.standard_role_URI);
// Now create a container for footnotes (Footnote Extended Link) FootnoteLinkbase fl = new FootnoteLinkbase(instance, role);
</syntaxhighlight>
Create the footnote resource
Reporting Standard API does not contain a specific resource type for footnotes. Footnote resources can be created using the base XBRLResource object from the API.
The following example demonstrates how to do it. Note that the creation of the resource requires other parameters that we have just explained how to create in this document. According to the parameters indicated in the example, the resource will be added to the parent footnote extended link container at the moment it is created. See the XBRLResource page for more information about the parameters.
<syntaxhighlight lang="java">
// Create a Footnote resource and add it to the fl container XBRLResource footnoteRes = new XBRLResource(fl,FootnoteLinkbase.lbResource,true);
// As footnotes can have simpleType content and complexType content (xhtml) the default is // complexType content. So we now force the resource to have simple type content. footnoteRes.setSimpleType();
// Footnote resource requires some values to be set
footnoteRes.setValue(new StringValue("Footnote content"));
footnoteRes.setLang("en");
</syntaxhighlight>
Create the relationship linking the fact with the footnote
Finally, a relationship will join the fact in the report with the footnote resource. Creating a relationship requires providing some parameters we have already defined in this page. See the XBRL 2.1 specification for more information about the standard arcroles defined there.
<syntaxhighlight lang="java">
// Create a relationship linking the fact with the footnote. XBRLArcroleType fact_footnote = dts.getStaticArcroleTypeByURI(FootnoteLinkbase.fact_footnote_arcrole_URI); new XBRLRelationship(fl,FootnoteLinkbase.standard_arc,fA,footnoteRes,fact_footnote,null,true);
</syntaxhighlight>
Cheking if a fact contains footnotes
The user can check if a fact in an instance contains footnotes by traversing the existing relationships of which the fact is the source and the arcrole type of the relationship is the standard arcrole for linking facts with footnotes http://www.xbrl.org/2003/arcrole/fact-footnote
The following piece of source code demonstrates how to do it:
<source lang="java" lines="LINES">
// First obtains the standard arcrole type from the DTS Container XBRLArcroleType art = dts.getArcroleType(FootnoteLinkbase.fact_footnote_arcrole_URI);
Iterator<XBRLFact> iterF = instance.iterator();
while (iterF.hasNext()) {
XBRLFact fact = iterF.next();
Iterator<XBRLRelationship> iterR = fact.getFromRelationships(art);
while (iterR.hasNext()) {
XBRLRelationship r = iterR.next();
XMLFragment f = r.getTo();
System.out.println("Fact \""+fact.getElementDefinition().getQName()+"\" has note \""+f.getStringValue()+"\"");
}
}
</source>
Reading footnotes
Alternativelly, the user can use other strategy to access to the content of footnote extended link containers. In this example the user is looking at all footnote extended links first and then navigating from the footnote resources down to the facts.
<syntaxhighlight lang="java">
// Loads the sample taxonomy
DTSContainer dts = DTSContainer.newEmptyContainer();
URI uri = new URI("instance.xbrl");
XBRLInstance instance = (XBRLInstance)dts.load(uri);
// Obtain the arcrole type, it will be used later XBRLArcroleType art = dts.getArcroleType(FootnoteLinkbase.fact_footnote_arcrole_URI);
// Iterate through the footnote extended links
Iterator<XBRLExtendedLink> iterL = instance.getExtendedLinks();
while (iterL.hasNext()) {
XBRLExtendedLink footnotesLink = iterL.next();
// Now iterate through the resources. Note this will return also the
// orphaned footnotes if any exists
Iterator<XBRLResource> iterR = footnotesLink.getResources();
while (iterR.hasNext()) {
XBRLResource footnote = iterR.next();
// Obtains relationships where this footnote is target and
// filter the result for fact-footnote arcrole type
Iterator<XBRLRelationship> iterE = footnote.getToRelationships(art);
if (!iterE.hasNext()) {
System.out.println("Footnote \""+footnote.getStringValue()+"\" is not linked with facts.");
} else {
while (iterE.hasNext()) {
XBRLRelationship rel = iterE.next();
XMLFragment fact = rel.getFrom();
System.out.println("Footnote \""+footnote.getStringValue()+"\" is linked with fact \""+fact.getNodeName());
}
}
}
}
</syntaxhighlight>
