Converter

The converter modules holds the Converter class, which converts XBRL-XML to XBRL-CSV taking as input taxonomy and instance objects.

Main function is to do an inner join between the XML instance and the preprocessed JSON, to generate an XBRL-CSV file.

class xbridge.converter.Converter(instance_path: str | Path)

Bases: object

Converter different types of files into others, using the EBA taxonomy and XBRL-instance. Each file is extracted and saved in a temporary directory. Then, these files are converted into JSON and again saved in a compressed folder such as ZIP or 7z.

Variables are generated by combining the open keys column with the attributes found within the taxonomy modules. Then, variable’s dimension is extracted from it with the purpose to be used with the context coming from the XML_instance, to create the scenario.

Finally, an inner join is done between the variables created and the values from the facts of the XML_instance context.

convert(output_path: str | Path, headers_as_datapoints: bool = False, validate_filing_indicators: bool = True, strict_validation: bool = False) → Path

Convert the XML Instance to a CSV file or between CSV formats

convert_csv(output_path: Path) → Path

convert_xml(output_path: Path, headers_as_datapoints: bool = False, validate_filing_indicators: bool = True, strict_validation: bool = True) → Path

class xbridge.converter.FactReconciliation(source_facts: int = 0, converted: int = 0, excluded_non_reported: int = 0, unmatched: int = 0, unrecognized_elements: ~typing.List[str] = <factory>)

Post-conversion accounting of every source fact.

The core invariant is:

source_facts == converted + excluded_non_reported + unmatched

where each detected fact ends up in exactly one bucket. unmatched and unrecognized_elements represent facts lost silently — the former detected but matching no table, the latter never recognised as facts at all. A balanced reconciliation with no unrecognised elements means nothing was dropped.

converted: int = 0

excluded_non_reported: int = 0

property has_silent_loss: bool

True when facts were dropped without an explicit filing-indicator reason.

Covers detected facts that matched no table (unmatched) and top-level elements never recognised as facts (unrecognized_elements). Orphaned facts (excluded_non_reported) are not silent — they have their own filing-indicator report — so they do not count here.

property is_consistent: bool

every detected fact lands in exactly one bucket.

unmatched is computed as the remainder, so this should always hold; a False result signals a counting bug (e.g. a fact double-counted as both converted and orphaned). It says nothing about whether facts were lost — use has_silent_loss for that.

Type:

Defensive accounting check

source_facts: int = 0

unmatched: int = 0

unrecognized_elements: List[str]

Generating variables:

Firstly, variables are generated taking the pre-processed tables that form the modules, which URLs are saved in the index.json file, and the instance columns that form the XML_instance. If instance have not got any open keys, variables are not going to be generated.

Index.json will look like this:

After that, variables are parsed, cleaning them up and an intersection is done with them and the instance columns. Now, the table is generated.

Converting tables:

Tables are generated, filling them with the variables generated before, and save in a CSV file. It will contain the variable version IDs.

This tables have to be treatise, so they can be used in the conversion process. This treatment consists in replacing hyphens with dots, so CSV files can be generated.

Converting filing indicators:

The filing indicators show which tables within the module are reported. Reports.json files only indicate XBRL related metadata and the module URL.

Converting parameters:

Parameters will contain all info related to entity, period, baseCurrency and decimals contained in the XBRL-XML file.

Fact reconciliation:

After a conversion, the converter records a FactReconciliation on Converter.reconciliation that accounts for every source fact. Each detected fact is classified as converted, excluded_non_reported (orphaned to non-reported tables) or unmatched (matched no table definition), and top-level elements never recognised as facts are collected as unrecognized_elements.

unmatched facts and unrecognized_elements are silent losses — facts absent from the output without an explicit filing-indicator reason. They are reported through FactReconciliationWarning / FactReconciliationError under the same strict_validation flag used for orphaned facts: a warning when False, an error when True. The census reuses the masks already computed for filing-indicator validation, so it adds negligible overhead.