XBridge Documentation

Overview

XBridge is a Python library for converting XBRL-XML files into XBRL-CSV files using the EBA (European Banking Authority) taxonomy. It provides a simple, reliable way to transform regulatory reporting data from XML format to CSV format.

The library currently supports EBA Taxonomy version 4.2 and includes support for DORA (Digital Operational Resilience Act) CSV conversion.

Key Features

XBRL-XML to XBRL-CSV Conversion: Seamlessly convert XBRL-XML instance files to XBRL-CSV format
Command-Line Interface: Quick conversions without writing code using the xbridge CLI
Python API: Programmatic conversion for integration with other tools and workflows
EBA Taxonomy 4.2 Support: Built for the latest EBA taxonomy specification
DORA CSV Conversion: Support for Digital Operational Resilience Act reporting
Configurable Validation: Flexible filing indicator validation with strict or warning modes
Decimal Handling: Intelligent decimal precision handling with configurable options
Type Safety: Fully typed codebase with MyPy strict mode compliance
Python 3.9+: Supports Python 3.9 through 3.13

Quick Start

Installation

Install XBridge from PyPI:

pip install eba-xbridge

Command-Line Usage

The fastest way to convert files is using the CLI:

# Basic conversion
xbridge instance.xbrl

# Specify output directory
xbridge instance.xbrl --output-path ./output

# Continue with warnings instead of errors
xbridge instance.xbrl --no-strict-validation

Python API Usage

For programmatic use, import and use the Python API:

from xbridge.api import convert_instance

# Basic conversion
convert_instance(
    instance_path="path/to/instance.xbrl",
    output_path="path/to/output"
)

# Advanced usage with validation options
convert_instance(
    instance_path="path/to/instance.xbrl",
    output_path="path/to/output",
    headers_as_datapoints=True,
    validate_filing_indicators=True,
    strict_validation=False
)

What’s New

Version 1.5.1rc1

Fixed handling of filing indicators codes by getting them from JSON files in the taxonomy

Version 1.5.0

Support for “0” and “1” values in filing indicators
Structured warnings for easier integration
Custom exceptions with detailed error information
Configurable filing indicator strictness
EBA Taxonomy 4.2 support

See the CHANGELOG for complete version history.

Documentation Contents

User Guide

Technical notes

Additional Resources

How XBridge Works

XBridge performs the conversion in several steps:

Load the XBRL-XML instance: Parse and extract facts, contexts, scenarios, and filing indicators
Load the EBA taxonomy: Access pre-processed taxonomy modules containing tables and variables
Match and validate: Join instance facts with taxonomy definitions
Generate CSV files: Create XBRL-CSV files including data tables, filing indicators, and parameters
Package output: Bundle all CSV files into a ZIP archive

Output Structure

The output ZIP file contains:

META-INF/: JSON report package metadata
reports/: CSV files for each reported table
filing-indicators.csv: Table reporting indicators
parameters.csv: Report-level parameters (entity, period, currency, decimals)

Support & Contributing

Documentation: https://docs.xbridge.meaningfuldata.eu
Issue Tracker: https://github.com/Meaningful-Data/xbridge/issues
Email: info@meaningfuldata.eu
Contributing: See CONTRIBUTING.md

License

XBridge is licensed under the Apache License 2.0. See the LICENSE file for details.