View source for XBRL Template File

==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 '''<nowiki>http://www.reportingstandard.com/map/2</nowiki>'''

The official location for the schema that corresponds to the indicated namespace is '''<nowiki>http://www.reportingstandard.com/schemas/mapper/mapper-2009.xsd</nowiki>'''

==Sample file==

<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<!-- 
This is a simple configuration file for Reporting Standard XBRL Mapping engine.

(C) Reporting Standard S.L. 2007-2009 - All rights reserved

This file has been created for the purposes to show a simple use case for the mapper

The namespace for this file is "http://www.reportingstandard.com/map/2"
The "official location" of the schema is "http://www.reportingstandard.com/schemas/mapper/mapper-2009.xsd"
The mapping engine already provides an internal copy of the schema for the purposes of validating the
configuration file. The mapping engine does not need to have interner access.
-->
<xbrlMap 
	xmlns="http://www.reportingstandard.com/map/2" 
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
	xsi:schemaLocation="http://www.reportingstandard.com/map/1 http://www.reportingstandard.com/schemas/mapper/mapper-2009.xsd" 
	xmlns:xbrli="http://www.xbrl.org/2003/instance" 
	xmlns:xbrldi="http://xbrl.org/2006/xbrldi">
	
	<!-- 
	section 1. identify the data source drivers that will be used to obtain the data related to this intace document template 
	there may be more than one data source driver.
	each data source driver is identified by its id
	the class MUST be in the classpath of the mapping Java Virtual Machine
	-->
	<datasources>
		<source id="source0" class="com.ihr.xbrl.mapper.source.StaticSource"/>
	</datasources>
	
	<!-- 
	section 2. this section provides data for the instance template
	-->
	<instance>
		<!--
		This is the set of files that compose the DTS of the instance document.
		One or more files can be specified here.
		The files may be either XBRL 2.1 Schemas or XBRL 2.1 Linkbases
		-->
		<dts>
			<file>taxonomy.xsd</file>
		</dts>
		<!--
		Templates for contexts. Contexts may be overwritten by the data source driver. but default contexts for facts
		will be generated using the templates in this section.
		-->
		<contexts>
			<scheme>http://www.xbrl.org/companyName</scheme>
			<company>The Sample Company Name</company>
			
			<!--
			Template for instant contexts
			-->
			<context id="ctx0i">
				<entity>
					<xbrli:identifier scheme="_">_</xbrli:identifier>
				</entity>
				<period>
					<instant>eoy-P1Y</instant>
				</period>
			</xbrli:context>
			
			<!--
			Template for duration contexts
			-->
			<context id="ctx0d">
				<entity>
					<xbrli:identifier scheme="_">_</xbrli:identifier>
				</entity>
				<period>
					<startDate>boy-P1Y</startDate>
					<endDate>eoy-P1Y</endDate>
				</period>
			</context>						
		</contexts>
		
		<!--
		Units used by the facts below
		-->
		<units>
			<xbrli:unit id="EUR">
				<xbrli:measure xmlns:iso4217="http://www.xbrl.org/2003/iso4217">iso4217:EUR</xbrli:measure>
			</xbrli:unit>
		</units>
		
		<!--
		Template of the instance document to produce
		-->
		<facts xmlns:tx="http://taxonomy.com/example">
			<!-- item -->
			<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 -->
			<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>

</syntaxhighlight>

==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 [http://www.reportingstandard.com/apidoc/com/ihr/xbrl/mapper/source/XBRLDataSource.html 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:
<syntaxhighlight 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>
</syntaxhighlight>

===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:
<syntaxhighlight 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>
</syntaxhighlight>
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:
<syntaxhighlight lang="xml">
  <contexts>
    <scheme>http://www.xbrl.org/companyName</scheme>
    <company>The Sample Company Name</company>
			
    <!--
      Template for instant contexts
    -->
    <context id="ctx0i">
      <entity>
        <xbrli:identifier scheme="_">_</xbrli:identifier>
      </entity>
      <period>
        <instant>eoy-P1Y</instant>
      </period>
    </xbrli:context>
			
    <!--
      Template for duration contexts
    -->
    <context id="ctx0d">
      <entity>
        <xbrli:identifier scheme="_">_</xbrli:identifier>
      </entity>
      <period>
        <startDate>boy-P1Y</startDate>
        <endDate>eoy-P1Y</endDate>
      </period>
    </context>						
  </contexts>
</syntaxhighlight>

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:
<syntaxhighlight lang="xml">
  <units>
    <xbrli:unit id="Euros">
      <xbrli:measure xmlns:iso4217="http://www.xbrl.org/2003/iso4217">iso4217:EUR</xbrli:measure>
    </xbrli:unit>
  </units>
</syntaxhighlight>

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|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.
<syntaxhighlight lang="xml">
    <item sourceRef="source0" contextRef="ctx0i" mapIdentifier="identifier0" concept="tx:A" unitRef="Euros"/>
</syntaxhighlight>

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|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|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.
<syntaxhighlight 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>
</syntaxhighlight>

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|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|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:
<syntaxhighlight lang="xml">
  <facts xmlns:tx="http://taxonomy.com/example">

    <!-- this is a single item event -->
    <item sourceRef="source0" contextRef="ctx0i" mapIdentifier="identifier0" concept="tx:A" unitRef="Euros"/>

    <!-- this is a single tuple event with no name -->
    <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>

    <!-- this is a second tuple -->
    <tuple concept="tx:U">
      <item sourceRef="source0" contextRef="ctx0i" mapIdentifier="identifier2" concept="tx:B" multi="1" unitRef="Euros"/>
    </tuple>

    <!-- dimensional item -->
    <item sourceRef="source0" contextRef="ctx0dim" mapIdentifier="identifier3" concept="tx:C" unitRef="Euros"/>
  </facts>
</syntaxhighlight>
==Navigation==
[[Main Page]] | [[XBRLmapper]]