XBRL API related discussions

From XBRLWiki
Jump to navigationJump to search

XBRL 2.1 Reporting Standard API

Product page

XBRL API product page

Descripcion

The XBRL API is an object model created on top of the XBRL Specification. The XBRL API has been designed to facilitate the development of user friendly applications or applications that works with XBRL information without having to worry about the complexities of the XBRL syntax and related specifications like XML Schema, XLINK, XPointer etc. Using the XBRL API the user interact with the content of a DTS (XBRL Reports and related metadata in taxonomies and linkbases) using just objects and methods defined in the objects.

Current version of the XBRL API is 2.6.7 and there is ongoing work on version 2.6.8. Changes in the API occurs from time to time in order to add new functionality or reimplement things in order to accelerate execution. The public part of the API is stable and has not suffered any changes in the last year or so.

All Tools from Reporting Standard have been build using Reporting Standard XBRL API.

The API provides access to several components from other libraries like XML Schema aware XPath processing from Saxonica XML processor (License included in Reporting Standard license) or Storage capabilities in relational databases.

Quick start guide

This section is a walkthrough describing the required steps in order to start using Reporting Standard XBRL API in your own code. The section is divided in two sub sections; one for Java and another one for .NET development environments

Java

The Java version requires Java 1.6 installed and 4Gb of RAM are recommended 2Gb of RAM minimun. A single CPU processor of 1.4 Ghz is minimun but, in order to be able to handle large taxonomies a dual CPU at GHz or more is recommended.

  1. Download the latest version of Reporting Standard tools from the downloads page
  2. Install the tools on your computer
  3. Install the license files in the lib folder as indicated in the documentation
  4. Create a new Java project and add the following jar libraries to it:
    1. The XBRL API in the xbrljlib-2.0.jar file
    2. The dependencies are: jdom.jar, commons-logging-1.0.4.jar, log4j-1.2.11.jar, saxon9ee.jar, saxon9-jdom.jar and resolver.jar
    3. Reporting Standard license file (XBRLlicense.lic) MUST be available in the classpath of the JVM
  5. Take a look at the section describing the environment variables in order to understand how they can be configured in your organization
  6. Start coding

.NET

  1. Download the latest version of Reporting Standard tools from the downloads page
  2. Install the tools on your computer
  3. Install the license files in the lib folder as indicated in the documentation
  4. Download the .NET version of the libraries (ask support at reportingstandard dot com for the download URL)
  5. Read the section about the environment variables and set them according to your settings. Note there is no Classpath in .NET so the XBRLLIBRARYPATH environment variable is of high importance in .NET environments.
  6. Create a new project in, for example, Visual Basic .NET
  7. add references to the following DLL files: xbrljlib-2.0.dll, IKVM.OpenJDK.Core.dll, IKVM.OpenJDK.Util.dll, IKVM.OpenJDK.XML.API.dll, IKVM.OpenJDK.XML:Parse.dll, IKVM.AWT.WinForms.dll and IKVM.Runtime.dll
  8. Please note, other DLLs may be required depending on the application you are using. All of them are in the same directory.
  9. Start coding

Architecture

The API is organized in logical layers. The lowest layer is considered the syntactical layer of the XML files that are the source of the information. One intermediate layer is the object model that represents the DTS content after resolving relationship prohibitions. A higher layer on top of the previous layer is the output of the XBRL validation rules that operated with the input of the previous later. Each one of the layers are able to detect XBRL errors or errors related to the specific layer, for example, the XML parser will detect and raise errors found on the syntax of the XML files. The XML Schema validation layer will raise XML Schema errors and so on. Information can flow between the layers, for example when you load a DTS from files, the information flows from bottom to top, but when you create an XBRL report programatically and later you call de save method, the information flows from top bottom layers.

Environment Variables and Java Variables

Reporting Standard XBRL API can be configured using environment variables and Java Variables in order to set the location of common components such as the license file and taxonomy catalog files. The following environment variables and java variables are recognized by the XBRL API:

  • XBRLCATALOGPATH This environment variable points to a ; separated list of directories where files with the name XBRLCatalog.xml exist. Those files must be according to the OASIS XML Catalog syntax convention. For this reason, it is recommended (but not required) that they reference the Catalog.xsd schema. The variable has effect in Windows and Unix, Java and .NET environments. The Windows installer already sets the environment variable and the right value pointing to the directory where the installer has installed the Taxonomy Catalog.
  • XBRLRSHOME This environment variable points to a directory that will be used as the home directory where Reporting Standard applications store user properties that are used to share information across multiple applications (like the information to connect to the XBRL Repository). The Windows installer does not set this environment variable and the API defaults to the user's home directory. The value is used in Windows and Unix, Java and .NET environments.
  • xbrl.rs.home If this java system property exist, it shall point to a directory that will be used instead of the XBRLRSHOME enviroment variable.
  • XBRLLIBRARYPATH This environment variable points to the directory where Reporting Standard libraries are installed on the system.

Note: the next directory after the directory pointed to by this variables must have a fixed name ReportingStandardXBRLTools.

There is more information about how the API obtains the path for a user file on the RSStaticAndUser java class documentation

Objects overview

The starting point for almost anything you want to do with Reporting Standard API requires the creation of a DTSContainer object. See the DTSContainer javadoc page this object will be used for loading a DTS or for creating a new DTS from scratch, performing XBRL validation, etc.

XBRL Document related objects

Simple API Services

  • XBRL UTR (Universal Type Registry) processor XBRLUTR

Extending the validation engine

Related documentation

[The XBRL Infoset Specification document] - Created by Reporting Standard S.L.