XBRL Template File

From XBRLWiki
Jump to: navigation, search

Description

The XBRL Template file is an XML file that defines events in order to let drivers to capture data that will be used for the generation of a new XBRL report.

The namespace definition of elements in the XBRL Template file is http: //www.reportingstandard.com/map/3

The official location for the schema that corresponds to the indicated namespace is https://www.reportingstandard.com/schemas/mapper/mapper-2011.xsd

Sample file

See the following example file:

<source lang="xml"> <?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?> <xbrlMap xmlns="http: //www.reportingstandard.com/map/3" xmlns:xsi="http: //www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http: //www.reportingstandard.com/map/1 https://www.reportingstandard.com/schemas/mapper/mapper-2011.xsd" xmlns:xbrli="http: //www.xbrl.org/2003/instance" xmlns:xbrldi="http: //xbrl.org/2006/xbrldi"> <datasources> <source id="source0" class="com.ihr.xbrl.mapper.source.StaticSource"/> </datasources> <instance> <dts> <file>taxonomy.xsd</file> </dts> <contexts> <scheme>http: //www.xbrl.org/companyName</scheme> <company>The Sample Company Name</company>

<context id="ctx0i"> <entity> <xbrli:identifier scheme="_">_</xbrli:identifier> </entity> <period> <instant>eoy-P1Y</instant> </period> </xbrli:context>

<context id="ctx0d"> <entity> <xbrli:identifier scheme="_">_</xbrli:identifier> </entity> <period> <startDate>boy-P1Y</startDate> <endDate>eoy-P1Y</endDate> </period> </context> </contexts>

<units> <xbrli:unit id="EUR"> <xbrli:measure xmlns:iso4217="http: //www.xbrl.org/2003/iso4217">iso4217:EUR</xbrli:measure> </xbrli:unit> </units>

<facts xmlns:tx="http: //taxonomy.com/example"> <item sourceRef="source0" contextRef="ctx0i" mapIdentifier="identifier0" concept="tx:A" unitRef="EUR"/> <item sourceRef="source0" contextRef="ctx0d" mapIdentifier="identifier1" concept="tx:B" multi="Single" unitRef="EUR"/> <tuple concept="tx:U"> <item sourceRef="source0" contextRef="ctx0d" mapIdentifier="identifier2" concept="tx:C" multi="1"/> <item sourceRef="source0" contextRef="ctx0d" mapIdentifier="identifier3" concept="tx:D" multi="Single"/> <item sourceRef="source0" contextRef="ctx0d" mapIdentifier="identifier4" concept="tx:E" multi="All" unitRef="EUR"/> </tuple> </facts> </instance> </xbrlMap> </source>

Elements

The root element is xbrlMap

The content of the xbrlMap element is divided in two sections.

  • Definition of data sources
  • Event definitions and associated metadata

Both sections are required in a mapping file and that must occurs only once

Definition of data sources

Data sources are defined using source elements as children of the datasources element.

The source element is an empty element that has three attributes:

  • Required id attribute. Used by item and tuple events (see next section Definition of Events) in order to identify the data source they are linked with.
  • Required class attribute. Used to indicate the driver class. The driver class must be instantiated at runtime (in a dll or in the classpath) and must implement the interface defined in the XBRLDataSource interface.
  • Optional config attribute. Used to point to a file with configuration information for the driver indicated in the class attribute. The content may be a URI relative to the URI of the XBRL Template File and it is resolved using xml:base if it is indicated in the source element or any of it ancestors.

A sample datasources section where two data sources are defined. One is a web form, the other is a connection to a database that requires a configuration file called SQLMapperDriverConfig.xml and is located in the same folder as the XBRL Template file: <source lang="xml">

 <datasources>
   <source id="form" class="com.ihr.xbrl.mapper.source.WebFormDataSource"/>
   <source id="sql" class="com.ihr.xbrl.mapper.source.SQLDataSource" config="SQLMapperDriverConfig.xml"/>
 </datasources>

</source>

Definition of events

The xbrlMap root element must have an instance element that in turn contains four sub-sections:

  • The definition of the instance DTS
  • The definition of the contexts templates
  • The definition of the units
  • The definition of the facts (Here is where the real events are defined. The previous three sections are just meta-data in order to facilitate the definition of the events)

The instance DTS

The instance DTS defines the schemas and linkbases that will be included in the new XBRL report in link:schemaRef and link:linkbaseRef elements. In the template file it is not required distinguishing between linkbase files and schema files. Both will be documented as simple files. The API will detect the file type and will include the required elements in the final XBRL report automatically.

The first child of the instance element must be a dts element that, in turn, contains an unlimited number of file elements each one of them indicating a relative or absolute file that will be included in the instance document during instance document generation phase. It is strongly recommended using official absolute file names of taxonomy or linkbase files in order to produce XBRL reports than can be opened everywhere. If you believe this is against performance, you may know that mapping external files on the Internet to local files is supported by almost all serious XBRL software vendors. Reporting Standard S.L. has implemented this feature using the XBRL Catalog and providing user friendly tools in order to help maintaining the local taxonomy catalog.

This is a sample dts section definition for the IFRS taxonomy: <source lang="xml">

   <dts>
     <file>http: //xbrl.iasb.org/taxonomy/2009-04-01/ifrs/ias_1_2009-04-01/cal_ias_1_2009-04-01_role-210000.xml</file>
     <file>http: //xbrl.iasb.org/taxonomy/2009-04-01/ifrs/label/lab_ifrs-en_2009-04-01.xml</file>
     <file>http: //xbrl.iasb.org/taxonomy/2009-04-01/ifrs/ias_1_2009-04-01/pre_ias_1_2009-04-01_role-210000.xml</file>
     <file>http: //xbrl.iasb.org/taxonomy/2009-04-01/ifrs/ias_1_2009-04-01/def_ias_1_2009-04-01_role-210000.xml</file>
   </dts>

</source> Note that this example is not including the IFRS taxonomy schema. This is not an error. The required schema will be added automatically by the tool in order to produce a valid XBRL report during the document creation phase.

Contexts templates

The contexts (in plural) element is a container for context templates. Context templates looks like xbrl contexts but most of the elements are in the namespace defined in the mapper schema rather than the XBRL namespace.

The content of some parts of the context container can be parameterized in order make them dynamic. The dynamic content will be calculated at the time the report is generated. The calculated value will be used in the resulting document in the part that corresponds according to the template.

Context templates may have dimensions in the segment and scenario containers.

This is a very simple example of contexts inside the template file: <source lang="xml">

 <contexts>
   <scheme>http: //www.xbrl.org/companyName</scheme>
   <company>The Sample Company Name</company>
   <context id="ctx0i">
     <entity>
       <xbrli:identifier scheme="_">_</xbrli:identifier>
     </entity>
     <period>
       <instant>eoy-P1Y</instant>
     </period>
   </xbrli:context>
   <context id="ctx0d">
     <entity>
       <xbrli:identifier scheme="_">_</xbrli:identifier>
     </entity>
     <period>
       <startDate>boy-P1Y</startDate>
       <endDate>eoy-P1Y</endDate>
     </period>
   </context>						
 </contexts>

</source>

The first two elements of the contexts element are scheme and company. The value of those elements is any string value for company and a valid URI value for the scheme element. The values indicated here will be used in order to substitute the content of the XBRL identifiers in the real contexts. When the value of the scheme attribute in the identifier elements is an underscore character "_", the mapper processor will substitute the underscore character by the value indicated in the scheme element. When the processor find an underscore character are the value of the identifier element, it will be substituted by the value of the company element.

The dates on instant, startDate and endDate elements in the context can also be parameterized. The valid values are:

  • a date; in this case it is not parameterized, it is just a fixed date, or
  • the token "boy" (Beginning Of the Year) optionally followed by a + or - sign and the declaration of a period using XML Schema notation. "boy" will be dynamically substituted by the date of the beginning of the current year, or
  • the token "eoy" (End Of the Year) optionally followed by a + or - sign and the declaration of a period using XML Schema notation. "eoy" will be dynamically substituted by the last date of the current year, or
  • the token "now" that indicates current date.

Each context here must have a context id that will be referenced from item elements declaring item generation events.

Units

The next part of the instance template document after the contexts element is the units (in plural) element. This element wraps all units used by item data events.

The content of the units elements are xbrl units as they appear in XBRL reports.

This is an example of a units element with content: <source lang="xml">

 <units>
   <xbrli:unit id="Euros">
     <xbrli:measure xmlns:iso4217="http: //www.xbrl.org/2003/iso4217">iso4217:EUR</xbrli:measure>
   </xbrli:unit>
 </units>

</source>

Units must have an id that will be referenced from item data events.

Events

Linking all together; the most important part of the instance template document are the events. Events are defined in order to obtain data from drivers and according to the mapper to driver data exchange dialog. The facts element wraps the content of all events defined in an XBRL Template File.

The following piece of XML code is the declaration of an event in order to obtain data for an item fact. All required information for the event definition is stored in attributes. Part of the information is required and other parts are optional. <source lang="xml">

   <item sourceRef="source0" contextRef="ctx0i" mapIdentifier="identifier0" concept="tx:A" unitRef="Euros"/>

</source>

The attributes defined in a fact item data capturing event are:

  • required sourceRef, this attribute content must match with the id of the source to be informed about the event.
  • required contextRef, this attribute content must match with the id of one of the contexts defined in the contexts section.
  • required mapIdentifier, this attribute holds the event name and will be used by drivers. See the mapper to driver data exchange dialog wiki page for more information.
  • required concept, this attribute hold the concept QName this item refers to. The concept must be defined in a taxonomy schema that is part of the DTS declared in the DTS section.
  • optional unitRef, this attribute content must match with the id of one of the units defined in the units section. The attribute is optional because non numeric concepts does not require units. If the used does not add this optional attribute in a numeric fact then the driver would be responsible of adding a unit. If the driver does not add a unit then the produced instance document may not be valid
  • optional multi, this attribute defines the behavior of the engine generating the report when the driver returns more than one value for this event and the element is inside a tuple. Possible values are "All", "Single", "Prev" or an integer. See the mapper to driver data exchange dialog wiki page for more information.

The following piece of XML code is the declaration of a sample event in order to obtain data for a tuple fact. <source lang="xml">

 <tuple concept="tx:T">
   ... here goes the tuple specific events; they are other item events or tuple events. Events can be nested in order to represent tuple structures in the instance document ...
 </tuple>

</source>

The declaration of events in order to populate content for tuples contains the following attributes:

  • required concept, this attribute holds the concept QName this tuple refers to. The concept must be defined in a taxonomy schema that is part of the DTS declared in the DTS section.
  • optional mapIdentifier, this attribute holds the event name and will be used by drivers. Due to the reason that tuple content are items or other tuples, the mapIdentifier here is optional. If there is no mapIdentifier attribute declared none of the drivers will be informed about the event for generating a tuple, one instantiation of the tuple will be created automatically in order to populate the tuple content.
  • optional multi, this attribute defines the behavior of the engine generating the report when there is a nested tuple inside a parent tuple and there are more than one fact tuples to be created in the report. See the mapper to driver data exchange dialog wiki page for more information.
  • optional sourceRef, if the attribute exist its content must match with the id of the source to be informed about the event. If the attribute exists, the driver will be responsible of calculating the number of fact tuples that the final instance document will contain. See the mapper to driver data exchange dialog wiki page for more information.

An event is declared and named using the mapIdentifier attribute in either a tuple or an item element. The content of that attribute is a string that identifies the event name. Other GUI tools and drivers will use the content of the mapIdentifier attribute in order to match it with the function that obtains values from the data source.

Sample content of a facts element: <source lang="xml">

 <facts xmlns:tx="http: //taxonomy.com/example">
   <item sourceRef="source0" contextRef="ctx0i" mapIdentifier="identifier0" concept="tx:A" unitRef="Euros"/>
   <tuple concept="tx:T">
     <tuple concept="tx:T">
       <item sourceRef="source0" contextRef="ctx0i" mapIdentifier="identifier1" concept="tx:B" multi="Single" unitRef="Euros"/>
       <item sourceRef="source0" contextRef="ctx0dim" mapIdentifier="identifier3" concept="tx:C" multi="2" unitRef="Euros"/>
     </tuple>
     <item sourceRef="source0" contextRef="ctx0i" mapIdentifier="identifier1" concept="tx:B" multi="All" unitRef="Euros"/>
   </tuple>
   <tuple concept="tx:U">
     <item sourceRef="source0" contextRef="ctx0i" mapIdentifier="identifier2" concept="tx:B" multi="1" unitRef="Euros"/>
   </tuple>
   <item sourceRef="source0" contextRef="ctx0dim" mapIdentifier="identifier3" concept="tx:C" unitRef="Euros"/>
 </facts>

</source>

Navigation

Main Page | XBRLmapper