XBRL API related discussions: Difference between revisions
From XBRLWiki
Jump to navigationJump to search
No edit summary |
|||
| (12 intermediate revisions by 2 users not shown) | |||
| Line 3: | Line 3: | ||
===Product page=== | ===Product page=== | ||
[ | [https://www.reportingstandard.com/xbrl-2-1-integration-api/?lang=en XBRL API product page] | ||
===Descripcion=== | ===Descripcion=== | ||
| Line 13: | Line 13: | ||
All Tools from Reporting Standard have been build using Reporting Standard XBRL API. | 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 or Storage capabilities in relational databases. | 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=== | ===Quick start guide=== | ||
| Line 21: | Line 21: | ||
====Java==== | ====Java==== | ||
# Download the latest version of Reporting Standard tools from the [ | 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. | ||
# Download the latest version of Reporting Standard tools from the [https://www.reportingstandard.com/downloads/?lang=en downloads page] | |||
# Install the tools on your computer | # Install the tools on your computer | ||
# Install the license files in the lib folder as indicated in the documentation | # Install the license files in the lib folder as indicated in the documentation | ||
# Create a new Java project and add the following jar libraries to it: | # Create a new Java project and add the following jar libraries to it: | ||
## The XBRL API in the '''xbrljlib-2.0.jar''' file | ## The XBRL API in the '''xbrljlib-2.0.jar''' file | ||
## The dependencies are: '''jdom.jar''', '''commons-logging-1.0.4.jar''', '''log4j-1.2.11.jar''', ''' | ## The dependencies are: '''jdom.jar''', '''commons-logging-1.0.4.jar''', '''log4j-1.2.11.jar''', '''saxon9ee.jar''', '''saxon9-jdom.jar''' and '''resolver.jar''' | ||
## | ## Reporting Standard license file ('''XBRLlicense.lic''') MUST be available in the classpath of the JVM | ||
# Take a look at the section describing the environment variables in order to understand how they can be configured in your organization | # Take a look at the section describing the environment variables in order to understand how they can be configured in your organization | ||
# Start coding | # Start coding | ||
| Line 33: | Line 35: | ||
====.NET==== | ====.NET==== | ||
# Download the latest version of Reporting Standard tools from the [ | # Download the latest version of Reporting Standard tools from the [https://www.reportingstandard.com/downloads/?lang=en downloads page] | ||
# Install the tools on your computer | # Install the tools on your computer | ||
# Install the license files in the lib folder as indicated in the documentation | # Install the license files in the lib folder as indicated in the documentation | ||
| Line 39: | Line 41: | ||
# 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. | # 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. | ||
# Create a new project in, for example, Visual Basic .NET | # Create a new project in, for example, Visual Basic .NET | ||
# add references to the following DLL files: '''xbrljlib-2.0.dll''', '''IKVM.OpenJDK. | # 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''' | ||
# Please note, other DLLs may be required depending on the application you are using. All of them are in the same directory. | |||
# Start coding | # Start coding | ||
| Line 46: | Line 49: | ||
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 <tt>save</tt> method, the information flows from top bottom layers. | 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 <tt>save</tt> method, the information flows from top bottom layers. | ||
===Environment Variables=== | ===Environment Variables and Java Variables === | ||
Reporting Standard XBRL API can be configured using environment variables in order to set the location of common components. The following environment variables are recognized by the XBRL API: | 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. | * '''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. | * '''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 [https://www.reportingstandard.com/apidoc/com/ihr/xbrl/util/RSStaticAndUser.html RSStaticAndUser java class documentation] | |||
===Objects overview=== | ===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 [ | The starting point for almost anything you want to do with Reporting Standard API requires the creation of a DTSContainer object. See the [https://www.reportingstandard.com/apidoc/com/ihr/xbrl/om/DTSContainer.html DTSContainer javadoc page] this object will be used for loading a DTS or for creating a new DTS from scratch, performing XBRL validation, etc. | ||
* [[DTSContainer]] wiki page | * [[DTSContainer]] wiki page | ||
| Line 73: | Line 82: | ||
* XBRL 2.1 validation [[XBRLCoreProcessor]] | * XBRL 2.1 validation [[XBRLCoreProcessor]] | ||
* XBRL Dimensions processor [[XDTProcessor]] | |||
* XBRL Formulas processor [[XBRLFormulaProcessor]] | |||
* XBRL UTR (Universal Type Registry) processor [[XBRLUTR]] | |||
* XBRL Edgar (US SEC Validator) [[EDGAR Validator]] | |||
* Traversing networks of relationships [[DTSExplorer]] | * Traversing networks of relationships [[DTSExplorer]] | ||
| Line 81: | Line 98: | ||
* Getting available languages [[LangsProvider]] | * Getting available languages [[LangsProvider]] | ||
Extending the validation engine | |||
* [[The basis of all validation engines]] | |||
* [[XBRLPlugInProcessor]] wiki page | |||
* [[XBRLProcessorFactory]] interface wiki page | |||
* [[XBRLProcessorFactoryBase]] abstract class that implements the [[XBRLProcessorFactory]] interface | |||
=== Related documentation=== | === Related documentation=== | ||
[[http://www.xbrl.org/Specification/Infoset/PWD-2009-02-04/infoset-PWD-2009-02-04.html The XBRL Infoset Specification document]] Created by Reporting Standard S.L. | [[http://www.xbrl.org/Specification/Infoset/PWD-2009-02-04/infoset-PWD-2009-02-04.html The XBRL Infoset Specification document]] - Created by Reporting Standard S.L. | ||
Latest revision as of 11:58, 28 January 2019
XBRL 2.1 Reporting Standard 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.
- Download the latest version of Reporting Standard tools from the downloads page
- Install the tools on your computer
- Install the license files in the lib folder as indicated in the documentation
- Create a new Java project and add the following jar libraries to it:
- The XBRL API in the xbrljlib-2.0.jar file
- The dependencies are: jdom.jar, commons-logging-1.0.4.jar, log4j-1.2.11.jar, saxon9ee.jar, saxon9-jdom.jar and resolver.jar
- Reporting Standard license file (XBRLlicense.lic) MUST be available in the classpath of the JVM
- Take a look at the section describing the environment variables in order to understand how they can be configured in your organization
- Start coding
.NET
- Download the latest version of Reporting Standard tools from the downloads page
- Install the tools on your computer
- Install the license files in the lib folder as indicated in the documentation
- Download the .NET version of the libraries (ask support at reportingstandard dot com for the download URL)
- 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.
- Create a new project in, for example, Visual Basic .NET
- 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
- Please note, other DLLs may be required depending on the application you are using. All of them are in the same directory.
- 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.
- DTSContainer wiki page
XBRL Document related objects
- XBRLTaxonomy wiki page
- XBRLLinkbase wiki page
- XBRLInstance wiki page
Simple API Services
- XBRL 2.1 validation XBRLCoreProcessor
- XBRL Dimensions processor XDTProcessor
- XBRL Formulas processor XBRLFormulaProcessor
- XBRL UTR (Universal Type Registry) processor XBRLUTR
- XBRL Edgar (US SEC Validator) EDGAR Validator
- Traversing networks of relationships DTSExplorer
- Exploring the content of XBRL reports InstanceExplorer
- Getting concept labels LabelsProvider
- Getting available languages LangsProvider
Extending the validation engine
- XBRLPlugInProcessor wiki page
- XBRLProcessorFactory interface wiki page
- XBRLProcessorFactoryBase abstract class that implements the XBRLProcessorFactory interface
Related documentation
[The XBRL Infoset Specification document] - Created by Reporting Standard S.L.
