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. The library must be updated with each new EBA taxonomy version release.
- 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
xbridgeCLI - 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
- Python: 3.9 or higher
- 7z Command-Line Tool: Required for loading compressed taxonomy files (7z or ZIP format)
- On Ubuntu/Debian:
sudo apt-get install p7zip-full - On macOS:
brew install p7zip - On Windows: Download from 7-zip.org
- On Ubuntu/Debian:
Install XBridge from PyPI using pip:
pip install eba-xbridgeFor development installation, see CONTRIBUTING.md.
XBridge offers two ways to convert XBRL-XML files to XBRL-CSV: a command-line interface (CLI) for quick conversions, and a Python API for programmatic use.
The CLI provides a quick way to convert files without writing code:
# Basic conversion (output to same directory as input)
xbridge instance.xbrl
# Specify output directory
xbridge instance.xbrl --output-path ./output
# Continue with warnings instead of errors
xbridge instance.xbrl --no-strict-validation
# Include headers as datapoints
xbridge instance.xbrl --headers-as-datapointsCLI Options:
--output-path PATH: Output directory (default: same as input file)--headers-as-datapoints: Treat headers as datapoints (default: False)--strict-validation: Raise errors on validation failures (default: True)--no-strict-validation: Emit warnings instead of errors
For more CLI options, run xbridge --help.
Convert an XBRL-XML instance file to XBRL-CSV using the Python API:
from xbridge.api import convert_instance
# Basic conversion
input_path = "path/to/instance.xbrl"
output_path = "path/to/output"
convert_instance(input_path, output_path)The converted XBRL-CSV files will be saved as a ZIP archive in the output directory.
Customize the conversion with additional parameters:
from xbridge.api import convert_instance
# Conversion with custom options
convert_instance(
instance_path="path/to/instance.xbrl",
output_path="path/to/output",
headers_as_datapoints=True, # Treat headers as datapoints
validate_filing_indicators=True, # Validate filing indicators
strict_validation=False, # Emit warnings instead of errors for orphaned facts
)Load and inspect an XBRL-XML instance without converting:
from xbridge.api import load_instance
instance = load_instance("path/to/instance.xbrl")
# Access instance properties
print(f"Entity: {instance.entity}")
print(f"Period: {instance.period}")
print(f"Facts count: {len(instance.facts)}")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 with facts and dimensions
- Filing indicators showing reported tables
- Parameters (entity, period, base currency, decimals)
- Package output: Bundle all CSV files into a ZIP archive
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
Comprehensive documentation is available at docs.xbridge.meaningfuldata.eu.
The documentation includes:
- API Reference: Complete API documentation
- Quickstart Guide: Step-by-step tutorials
- Technical Notes: Architecture and design details
- FAQ: Frequently asked questions
If you need to work with the EBA taxonomy directly, you can load it using:
python -m xbridge.taxonomy_loader --input_path path/to/FullTaxonomy.7zThis generates an index.json file containing module references and pre-processed taxonomy data.
Warning
Loading the taxonomy from a 7z package may take several minutes. Ensure the 7z command is available on your system.
- instance_path (str | Path): Path to the XBRL-XML instance file
- output_path (str | Path | None): Output directory for CSV files (default: current directory)
- headers_as_datapoints (bool): Treat table headers as datapoints (default: False)
- validate_filing_indicators (bool): Validate that facts belong to reported tables (default: True)
- strict_validation (bool): Raise errors on validation failures; if False, emit warnings (default: True)
- 7z command not found
- Install the 7z command-line tool using your system's package manager (see Prerequisites).
- Taxonomy version mismatch
- Ensure you're using the correct version of XBridge for your taxonomy version. XBridge 1.5.x supports EBA Taxonomy 4.1.
- Orphaned facts warning/error
- Facts that don't belong to any reported table. Set
strict_validation=Falseto continue with warnings instead of errors. - Decimal precision issues
- XBridge automatically handles decimal precision from the taxonomy. Check the parameters.csv file for applied decimal settings.
For more issues, see our FAQ or open an issue.
We welcome contributions! Please see CONTRIBUTING.md for:
- Development setup instructions
- Code style guidelines
- Testing requirements
- Pull request process
Before contributing, please read our Code of Conduct.
See CHANGELOG.md for a detailed history of changes.
- Documentation: https://docs.xbridge.meaningfuldata.eu
- Issue Tracker: https://github.com/Meaningful-Data/xbridge/issues
- Email: info@meaningfuldata.eu
- Company: https://www.meaningfuldata.eu/
For security issues, please see our Security Policy.
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.
MeaningfulData - https://www.meaningfuldata.eu/
Maintainers:
- Antonio Olleros (antonio.olleros@meaningfuldata.eu)
- Jesus Simon (jesus.simon@meaningfuldata.eu)
- Francisco Javier Hernandez del Caño (javier.hernandez@meaningfuldata.eu)
- Guillermo Garcia Martin (guillermo.garcia@meaningfuldata.eu)
This project is designed to work with the European Banking Authority (EBA) taxonomy for regulatory reporting