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 / 4.2.1 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

• XBRL-XML and XBRL-CSV Validation: Validate instance files against structural and EBA regulatory rules, with format-aware rule selection and post-conversion mode

• Command-Line Interface: Quick conversions and validation without writing code using the xbridge CLI

• Python API: Programmatic conversion and validation for integration with other tools and workflows

• EBA Taxonomy 4.2/4.2.1 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

Validation

Validate XBRL-XML or XBRL-CSV files without converting:

# Structural checks
xbridge validate instance.xbrl

# Include EBA regulatory rules
xbridge validate instance.xbrl --eba

# Validate a CSV package
xbridge validate report.zip --eba

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"
)

# Conversion with pre- and post-conversion validation
convert_instance(
    instance_path="path/to/instance.xbrl",
    output_path="path/to/output",
    validate=True,
    eba=True,
)

from xbridge.validation import validate

# Standalone validation
results = validate("path/to/instance.xbrl", eba=True)
has_errors = any(section["errors"] for section in results.values())

What’s New

Version 2.0.0rc8

• Validation Fix: Fixed Scenario.parse() crash on dimension attributes without namespace prefix, which silently prevented taxonomy-based validation rules (XML-070/071/072) from running

• Validation Engine: Added fallback module_ref extraction so taxonomy rules can still execute when XmlInstance parsing fails

Version 2.0.0rc3

• Validate-Convert-Validate Pipeline: --validate / --eba CLI flags and validate= / eba= API parameters for pre- and post-conversion validation

• EBA Taxonomy 4.2.1: Added FINREP 4.2.1 (finrep9dp) module

• Fixed EBA-CUR-002 incorrectly flagging non-monetary facts

• Fixed incorrect R_02.00.a filing indicator in the rem_bm (GL 2022-06) module

Version 2.0.0rc2

• CSV Structural Rules: CSV-001..CSV-005, CSV-010..CSV-016, CSV-020..CSV-026, CSV-030..CSV-035, CSV-040..CSV-049, CSV-050..CSV-052, CSV-060..CSV-062

• CSV EBA Rules: CSV-side implementations for EBA-ENTITY-001/002, EBA-DEC-001..004, EBA-UNIT-001/002, EBA-CUR-003, EBA-2.16.1, EBA-2.24, EBA-GUIDE-002/004/007, EBA-NAME-071

• Validation Performance: Shared cache across rules eliminates redundant ZIP I/O (~60-65% faster for CSV validation)

• Fixed iso4217:-prefixed baseCurrency parameter handling in CSV validation rules

Version 2.0.0rc1

• Standalone Validation API: New xbridge.validation module with validate() function

• Validation CLI Command: New xbridge validate subcommand

• XML Structural Rules: XML-001..XML-072

• EBA Rules: EBA-ENTITY, EBA-CUR, EBA-UNIT, EBA-DEC, EBA-GUIDE, EBA-NAME, and additional EBA rules

See the CHANGELOG for complete version history.

Documentation Contents

Getting Started

• Quickstart Guide
  • Prerequisites
  • Installation
  • Use Case 1: XBRL-XML to XBRL-CSV Conversion
  • Use Case 2: Standalone Validation
  • Use Case 3: XBRL-CSV Architecture Conversion
  • Next Steps
  • Troubleshooting
  • Getting Help

User Guide

• Technical notes
  • XML_instances
  • Conversion process
  • Load Taxonomy
• Validation Rules
  • Rule Attributes
  • Input Format Detection
  • 1. XML Instance Rules
  • 2. CSV Report Package Rules
  • 3. Submission Package Naming Rules
  • Rule Coverage Summary

API Reference

• API Reference
  • Python API
  • Convert XBRL Instance to CSV
  • Basic Usage
  • Advanced Usage Examples
  • Parameters
  • Load an XBRL-XML Instance
  • Usage Examples
  • load_instance() Parameters
  • Return Value
• Validation API
  • Overview
  • Design
  • Quick Start
  • Public API
  • Usage Examples
  • Parameters
  • Integration with Conversion
  • Architecture
  • Reference Documents
• Command-Line Interface
  • Usage
  • Arguments
  • CLI Examples
  • Validate Command
  • Validate Examples
• Converter
  • Converter
  • Generating variables:
  • Converting tables:
  • Converting filing indicators:
  • Converting parameters:
• Taxonomy loader
  • Taxonomy class
• Modules
  • Module class
  • Table class
  • Variable class
• XML Instance
  • Instance Class
  • Scenario Class
  • Context Class
  • Fact Class
  • Filing Indicator Class

Additional Resources

• GitHub Repository
• Issue Tracker
• Changelog
• Contributing
• Security Policy

How XBridge Works

XBridge performs the conversion in several steps:

1. Load the XBRL-XML instance: Parse and extract facts, contexts, scenarios, and filing indicators

2. Load the EBA taxonomy: Access pre-processed taxonomy modules containing tables and variables

3. Match and validate: Join instance facts with taxonomy definitions

4. Generate CSV files: Create XBRL-CSV files including data tables, filing indicators, and parameters

5. 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.

Indices and Tables

• Index

• Module Index

• Search Page