Render Inline XBRL (iXBRL) with CellStore, Part 4: Tweaking the iXBRL Rendering

This page is a placeholder, its contents are being worked on.

Estimated reading time: 5 minutes

How to Tweak the iXBRL Rendering with the API

In parts 2 and 3 we have seen how we can create an iXBRL template and combine it with queried facts to be rendered to iXBRL by the cellstore/v1/facts/render/ixbrl endpoint.

iXBRL Rendering API: Overriding Parameters

Parameters can be overriden in the iXBRL template. This allows to dynamically change the content or scope of a created report.

Consider this template:

<html xmlns="http://www.w3.org/1999/xhtml" 
      xmlns:ixtp="http://reportix.com/2021-07-21/ixbrl/template" 
      xmlns:us-gaap="http://fasb.org/us-gaap/2020-01-31" 
      xml:lang="en">
    <head>
       ...
       <!-- define parameter currentPeriodInstant with default value '2020-12-31' (value can be overridden from outside, 
            e.g. through the API) -->
       <meta ixtp:type="parameter" name="currentPeriodInstant" content="2020-12-31"/>
       <!-- define variable customNumberFormat with value '#,##0;(#,##0);0' (value can not be overridden from outside) -->
       <meta ixtp:type="variable" name="customNumberFormat" content="#,##0;(#,##0);0"/>
    </head>
    <body>
       ...
       <!-- use parameter currentPeriodInstant and variable customNumberFormat -->
       <span ixtp:factMatch="xbrl:concept=us-gaap:Assets; xbrl:period=${currentPeriodInstant};" 
             ixtp:numberFormat="${customNumberFormat}"/>
    </body>
</html>

This template could be rendered with assets from december 2020 by POSTing the template to cellstore/v1/facts/render/ixbrl?xbrl:instance=123&xbrl:concept=us-gaap:Assets&xbrl:period=2020-12-31. The output iXBRL document will contain the single assets for december 2020 as expected. In order to change the content, one might POST the same iXBRL template to cellstore/v1/facts/render/ixbrl?xbrl:instance=123&xbrl:concept=us-gaap:Assets&xbrl:period=2019-12-31. This will not match any fact in the template, so the content will be empty. However, if we add &parameter::currentPeriodInstant=2019-12-31 to the URL we can change the scope very easily and now can see the fact in the output.

iXBRL Rendering API: Force Keeping Content from the Template

Sometimes it is necessary to keep the content from the template file. For example, there is no automatic way to guess where to split long text to create ix:continuation elements. Consequently, the attribute ixtp:forceKeepContent can be used to keep the content from the template for certain elements. In case you would like to keep all content from the iXBRL template, you can add parameter forceKeepContent=true which will behave as if all elements had the attribute ixtp:forceKeepContent=true

iXBRL Rendering API: Analyze the Rendered Inline XBRL Output

For your specific rendering request you might want to know the details of the matching process and validate the rendered Inline XBRL result. You can get a detailed analysis in JSON format of the rendered result by adding parameter analyze=true.

The reported events by the report will include:

ixtp:factMatch attributes where …
- … no matching fact could be found
- … or multiple matching facts were found and where one was potentially chosen over another
ixtp:footnote attributes where no matching footnote could be found
ixtp:footnoteRef attributes where no matching ixtp:footnote could be found

In addition with analyze=true some validations will be carried out (by parsing the rendered iXBRL result testing for full round trippability), but further ones can be explicitly applied:

Parameter	Default ON/OFF	Validation carried out
`analyzeNumericFactValues`	ON	Compares the parsed rendered value of numeric facts with the value stored in the DB.
`analyzeIxbrlConformanceValidation`	ON	Checks if the rendered iXBRL is conformant with the Inline XBRL 1.1 Spec.
`analyzeXbrlCalculationValidation`	ON	Checks if calculations defined in the DTS pass.
`analyzeXbrlConformanceValidation`	ON	Checks if the rendered iXBRL is conformant with the XBRL Core 2.1 Spec.
`analyzeXmlSchemaValidation`	ON	Checks if the rendered iXBRL is valid according to XML Schema validation.
`analyzeFactDimensionalValidation`	OFF	Checks if the rendered iXBRL is conformant with the XBRL Dimensions 1.0 Spec.
`analyzeFactValueValidation`	OFF	Checks if fact values are valid according to their XML Schema type.
`analyzeTextFactValues`	OFF	Compares the parsed rendered value of nonNumeric facts with the value stored in the DB.
`analyzeXbrlFormulaValidation`	OFF	Checks if the rendered iXBRL is conformant with the XBRL Formula 1.0 Spec.
`analyzeXbrlTablesConformanceValidation`	OFF	Checks if the rendered iXBRL including the DTS is conformant with the XBRL Table Linkbase 1.0 Spec.

The parameter analyzeTextFactValues may cause heavy load on the server. It is particulary computation heavy in terms of CPU usage, because it may compute diffs. If the fact contains an HTML value then the diff is computed for the whitespace collapsed version of the value. The diffs are then presented in the result in the field factValueDiff where insertions are marked with #++>>> and <<<++# and deletions are marked with #-->>> and <<<--#. Because this parameter can consume so much CPU time, there is a global setting in the reportix.properties file which can limit this feature. The property IXBRL_RENDERING_ANALYZE_TEXT_FACTS_DIFF_LIMIT_KB is by default set to 25600 (=25MB) of text for which a full diff is computed (all or nothing). Hence, if the rendered iXBRL contains text facts where the aggregated size is larger than this property value, then no diff is computed for text facts. Instead only the values from the DB and the rendered values are returned in the fields factRenderedValue and factStoredValue, so that a diff could still be computed client-side. If no diff should be computed at all, because this causes too much of a delay, then this property should be set to 0.

cellstore, Inline XBRL, XBRL, guide, tutorial, API, rendering