Feat/add validations

.github/workflows/docs.yml

@@ -24,22 +24,22 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
       - name: Setup Pages
         id: pages
-        uses: actions/configure-pages@v4
+        uses: actions/configure-pages@v5
       - name: Install poetry
         run: pipx install poetry
       - name: Setup Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
       - name: Install dependencies
         run: poetry install --with docs
       - name: Build with Sphinx
         run: |
           poetry run sphinx-build docs _site
       - name: Upload artifact
         # Automatically uploads an artifact from the './_site' directory by default
-        uses: actions/upload-pages-artifact@v3
+        uses: actions/upload-pages-artifact@v4
 
   # Deployment job
   deploy:
@@ -51,4 +51,4 @@ jobs:
     steps:
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@v5

.github/workflows/release.yml

@@ -15,11 +15,11 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
       - name: Install poetry
         run: pipx install poetry
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: "3.x"
       - name: Build package

.github/workflows/testing.yml

@@ -18,15 +18,15 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest, macos-latest, windows-latest]
-        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
 
     steps:
     - name: Checkout code
-      uses: actions/checkout@v4
+      uses: actions/checkout@v5
     - name: Install poetry
       run: pipx install poetry
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v5
+      uses: actions/setup-python@v6
       with:
         python-version: ${{ matrix.python-version }}
     - name: Install dependencies

.github/workflows/version.yml

@@ -14,10 +14,10 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: '3.12'
 

.gitignore

@@ -11,3 +11,4 @@ input/
 .venv
 .coverage
 development.py
+*.skill

CHANGELOG.md

@@ -7,6 +7,33 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.0.0] - 2026-03-17
+
+### Added
+- **Standalone Validation API**: New `xbridge.validation` module with `validate()` function for checking XBRL instance files against structural and regulatory rules — both XBRL-XML and XBRL-CSV formats.
+- **Validation CLI Command**: New `validate` subcommand with `--eba`, `--post-conversion`, and `--json` flags for running validation checks from the command line.
+- **Validate-Convert-Validate Pipeline**: New `--validate` and `--eba` CLI flags for the `convert` command run validation before and after conversion. Equivalent `validate=` and `eba=` parameters added to `convert_instance()`. Raises `ValidationError` on failure.
+- **XML Validation Rules**: 30+ rules covering well-formedness (XML-001..XML-003), schemaRef checks (XML-010/012), filing indicators (XML-020..XML-026), context structure (XML-030..XML-035), fact structure (XML-040..XML-043), unit UTR reference (XML-050), document-level checks (XML-060..XML-069), and taxonomy conformance (XML-070..XML-072).
+- **CSV Validation Rules**: 30+ rules covering report package structure (CSV-001..CSV-006), report.json metadata (CSV-010..CSV-016), parameters.csv (CSV-020..CSV-026), FilingIndicators.csv (CSV-030..CSV-035), data table checks (CSV-040..CSV-049), fact-level checks (CSV-050..CSV-052), and taxonomy conformance (CSV-060..CSV-062).
+- **EBA-specific Validation Rules**: Entity identifier checks (EBA-ENTITY-001/002), currency validation (EBA-CUR-001..003), non-monetary unit checks (EBA-UNIT-001/002), decimals accuracy (EBA-DEC-001..004), guidance compliance (EBA-GUIDE-001..007), file naming conventions (EBA-NAME-001..071), and supplementary regulatory checks (EBA-2.5, EBA-2.16.1, EBA-2.24, EBA-2.25).
+- **EBA Taxonomy 4.2.1**: Added support for FINREP 4.2.1 (`finrep9dp` module).
+- **Validation Documentation**: New `docs/validation.rst` with full API reference, usage examples, and integration guide.
+
+### Changed
+- **Scoped Validation Results**: `validate()` returns a dictionary keyed by validation scope (`"XBRL"` always present, `"EBA"` when `eba=True`). Each scope contains `"errors"` and `"warnings"` sub-dicts keyed by rule code. Code previously reading `results["errors"]` must access `results["XBRL"]["errors"]` or iterate `results.values()`.
+- **Validation Performance**: Single-pass XML scanning and shared cache across rules eliminate redundant I/O (~60-65% faster for CSV validation).
+- **Simplified Module Interface**: Removed external `dim_dom_mapping*.json` dependency; dimension-domain variable mapping is now computed inline from table column metadata.
+- **Converter Output**: Updated `reportPackage.json` and `report.json` to use final XBRL specification URLs (`https://xbrl.org/report-package/2023` and `https://xbrl.org/2021/xbrl-csv`).
+
+### Fixed
+- Fixed `Scenario.parse()` crash on dimension attributes without a namespace prefix.
+- Fixed EBA-CUR-002 incorrectly flagging non-monetary facts in a denomination context.
+- Fixed `iso4217:`-prefixed `baseCurrency` parameter handling in CSV validation rules.
+- Fixed ZIP root folder prefix detection affecting CSV-003 and CSV-005.
+- Fixed CSV-033 to accept boolean values `'1'` and `'0'` for filing indicator `reported` column.
+- Fixed CSV-025 `baseCurrency` check to only consider actually reported datapoints.
+- Fixed incorrect `R_02.00.a` filing indicator in the `rem_bm` module — corrected to `R_02.00`.
+
 ## [1.5.2] - 2026-02-13
 
 ### Fixed
@@ -139,7 +166,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 - Initial pre-release version
 
-[Unreleased]: https://github.com/Meaningful-Data/xbridge/compare/v1.5.2...HEAD
+[Unreleased]: https://github.com/Meaningful-Data/xbridge/compare/v2.0.0...HEAD
+[2.0.0]: https://github.com/Meaningful-Data/xbridge/compare/v1.5.2...v2.0.0
 [1.5.2]: https://github.com/Meaningful-Data/xbridge/compare/v1.5.1...v1.5.2
 [1.5.1]: https://github.com/Meaningful-Data/xbridge/compare/v1.5.0...v1.5.1
 [1.5.0]: https://github.com/Meaningful-Data/xbridge/compare/v1.4.0...v1.5.0

README.rst

@@ -22,16 +22,17 @@ 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 supports **EBA Taxonomy version 4.2**, as published on the 14th January 2026 and includes support for DORA (Digital Operational Resilience Act) CSV conversion. The library must be updated with each new EBA taxonomy version release.
+The library supports **EBA Taxonomy versions 4.2 and 4.2.1** and includes support for DORA (Digital Operational Resilience Act) CSV conversion. The library must be updated with each new EBA taxonomy version release.
 
 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
+* **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
+* **Standalone Validation**: Validate XBRL-XML and XBRL-CSV files against structural and EBA rules via CLI or Python API
 * **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
@@ -82,12 +83,20 @@ The CLI provides a quick way to convert files without writing code:
     # Include headers as datapoints
     xbridge instance.xbrl --headers-as-datapoints
 
+    # Validate before and after conversion
+    xbridge instance.xbrl --validate
+
+    # Validate with EBA-specific rules
+    xbridge instance.xbrl --validate --eba
+
 **CLI 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
+* ``--validate``: Run validation before and after conversion (default: False)
+* ``--eba``: Enable EBA-specific validation rules (only applies with ``--validate``)
 
 For more CLI options, run ``xbridge --help``.
 
@@ -126,6 +135,25 @@ Customize the conversion with additional parameters:
         strict_validation=False,  # Emit warnings instead of errors for orphaned facts
     )
 
+    # Validate-convert-validate pipeline
+    from xbridge.exceptions import ValidationError
+
+    try:
+        convert_instance(
+            instance_path="path/to/instance.xbrl",
+            output_path="path/to/output",
+            validate=True,   # Enable pre/post-conversion validation
+            eba=True,         # Include EBA-specific rules
+        )
+    except ValidationError as e:
+        print(f"Validation failed: {e}")
+        if e.path:
+            print(f"Output was written to: {e.path}")
+        for section in e.results.values():
+            for code, findings in section["errors"].items():
+                for f in findings:
+                    print(f"  [{f['severity']}] {f['rule_id']}: {f['message']}")
+
 Python API - Handling Warnings
 ------------------------------
 
@@ -175,6 +203,78 @@ To treat all XBridge warnings as errors:
         warnings.simplefilter("error", XbridgeWarning)
         convert_instance("path/to/instance.xbrl", "path/to/output")
 
+Validation - Command-Line Interface
+------------------------------------
+
+The ``validate`` subcommand checks XBRL instance files against structural and regulatory rules without performing conversion:
+
+.. code-block:: bash
+
+    # Validate an XBRL-XML file
+    xbridge validate instance.xbrl
+
+    # Enable EBA-specific rules (entity, currency, decimals, etc.)
+    xbridge validate instance.xbrl --eba
+
+    # Validate an XBRL-CSV package
+    xbridge validate report.zip --eba
+
+    # Skip structural checks for xbridge-generated CSV output
+    xbridge validate output.zip --eba --post-conversion
+
+    # Get machine-readable JSON output
+    xbridge validate instance.xbrl --eba --json
+
+**Validate Options:**
+
+* ``--eba``: Enable EBA-specific validation rules (default: False)
+* ``--post-conversion``: Skip structural checks guaranteed by xbridge's converter (CSV only, default: False)
+* ``--json``: Output findings as JSON instead of human-readable text
+
+The validate command exits with code **0** when no errors are found, and **1** when at least one ERROR-level finding is present.
+
+For more options, run ``xbridge validate --help``.
+
+Validation - Python API
+------------------------
+
+Validate XBRL files programmatically using the ``validate()`` function:
+
+.. code-block:: python
+
+    from xbridge.validation import validate
+
+    # Validate an XBRL-XML file
+    results = validate("path/to/instance.xbrl")
+
+    # Enable EBA-specific rules
+    results = validate("path/to/instance.xbrl", eba=True)
+
+    # Validate an XBRL-CSV package
+    results = validate("path/to/report.zip", eba=True)
+
+The ``validate()`` function returns a dictionary keyed by validation scope (``"XBRL"`` always present, ``"EBA"`` when ``eba=True``). Each scope contains ``"errors"`` and ``"warnings"`` dicts keyed by rule code:
+
+.. code-block:: python
+
+    from xbridge.validation import validate
+
+    results = validate("path/to/instance.xbrl", eba=True)
+
+    for scope, section in results.items():
+        for code, findings in section["errors"].items():
+            for f in findings:
+                print(f"[{scope}] [{f['severity']}] {f['rule_id']}: {f['message']}")
+                print(f"  Location: {f['location']}")
+
+    error_count = sum(
+        len(v) for section in results.values() for v in section["errors"].values()
+    )
+    warning_count = sum(
+        len(v) for section in results.values() for v in section["warnings"].values()
+    )
+    print(f"Errors: {error_count}, Warnings: {warning_count}")
+
 Loading an Instance
 -------------------
 
@@ -254,6 +354,8 @@ convert_instance Parameters
 * **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)
+* **validate** (bool): Run validation before and after conversion; raises ``ValidationError`` on errors (default: False)
+* **eba** (bool): Enable EBA-specific validation rules; only used when *validate* is True (default: False)
 
 Troubleshooting
 ===============
@@ -265,7 +367,7 @@ Common Issues
     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.2.
+    Ensure you're using the correct version of XBridge for your taxonomy version. XBridge 2.x supports EBA Taxonomy 4.2/4.2.1.
 
 **Orphaned facts warning/error**
     Facts that don't belong to any reported table. Set ``strict_validation=False`` to continue with warnings instead of errors.

docs/api.rst

@@ -133,7 +133,7 @@ Parameters
 
 
 Load an XBRL-XML Instance
-==========================
+--------------------------
 
 .. autofunction:: load_instance
 
@@ -219,8 +219,8 @@ Load an instance to validate it before conversion:
     except Exception as e:
         print(f"✗ Validation or conversion failed: {e}")
 
-Parameters
-----------
+load_instance() Parameters
+--------------------------
 
 :param instance_path: Path to the XBRL-XML instance file. Accepts ``str`` or ``pathlib.Path``.