Input Data Schemas¶

This page documents the authoritative schemas for all input data files required by the RWA calculator. These schemas are defined in src/rwa_calc/data/schemas.py and represent the single source of truth.

Quick Reference¶

Mapping Files:

Counterparty Schema¶

Purpose: Defines borrower/obligor information used for exposure classification, risk weight determination, and hierarchy resolution.

File: counterparty/counterparties.parquet

Entity Type: The Single Source of Truth¶

The entity_type field is the authoritative source for determining both SA and IRB exposure classes. Each entity type maps to specific exposure classes for each approach. This design ensures consistent classification across the calculation pipeline.

Valid entity_type values:

Why SA and IRB Classes Can Differ¶

For certain entity types, the regulatory treatment differs between SA and IRB approaches:

• RGLA/PSE with sovereign treatment: Under SA, these use dedicated RGLA/PSE risk weight tables. Under IRB, those with government guarantees or taxing powers use the central govt/central bank IRB formula.
• RGLA/PSE with institution treatment: Under SA, these use RGLA/PSE tables. Under IRB, commercial PSEs without sovereign backing use the institution IRB formula.
• MDB/International Orgs: Under SA, these typically receive 0% RW from the MDB table. Under IRB, they use the central govt/central bank formula.

Additional Classification Flags¶

Financial Sector Entity (FSE) Determination¶

The following entity types are classified as Financial Sector Entities for FI scalar purposes:

• institution
• bank
• ccp
• financial_institution
• pse_institution (PSE treated as institution)
• rgla_institution (RGLA treated as institution)

FI Scalar applies when (CRR Art. 153(2)): 1. Large FSE: total_assets >= EUR 70bn, OR 2. Financial sector entity with apply_fi_scalar = True

Example:

import polars as pl

counterparties = pl.DataFrame({
    "counterparty_reference": ["CORP_001", "CORP_002", "SOV_001", "BANK_001", "PSE_001"],
    "counterparty_name": ["Acme Corp Ltd", "Beta Industries PLC", "UK Treasury", "Major Bank PLC", "Local Council"],
    "entity_type": ["corporate", "corporate", "sovereign", "bank", "pse_sovereign"],
    "country_code": ["GB", "GB", "GB", "GB", "GB"],
    "annual_revenue": [25_000_000.0, 500_000_000.0, None, None, None],
    "total_assets": [30_000_000.0, 600_000_000.0, None, 80_000_000_000.0, 500_000_000.0],
    "default_status": [False, False, False, False, False],
    "sector_code": ["62.01", "28.11", None, "64.19", None],
    "apply_fi_scalar": [False, False, False, False, False],
    "is_managed_as_retail": [False, False, False, False, False],
})

Classification Algorithm Summary¶

The classifier (engine/classifier.py) processes counterparties through these steps:

1. Entity Type Mapping: Maps entity_type to both SA and IRB exposure classes
2. SME Classification: Checks if annual_revenue < EUR 50m for corporates
3. Retail Threshold: Aggregates exposures by lending group against EUR 1m threshold
4. Default Identification: Checks default_status for defaulted treatment
5. FI Scalar Determination: Identifies large/unregulated FSEs for 1.25x correlation
6. Approach Assignment: Assigns SA/F-IRB/A-IRB/Slotting based on IRB permissions

See Classification for the complete classification algorithm.

Facility Schema¶

Purpose: Defines committed credit facilities (parent nodes in exposure hierarchy). Facilities represent credit limits; actual drawings are captured in the Loan schema.

File: exposures/facilities.parquet

Valid product_type values:

Valid seniority values:

Valid risk_type values (CRR Art. 111 CCF Categories):

Note: Under F-IRB (CRR Art. 166(8)), MR and MLR both become 75% CCF.

F-IRB Exception (Art. 166(9)): Short-term letters of credit arising from the movement of goods retain 20% CCF under F-IRB. To flag these exposures, set is_short_term_trade_lc = True for MLR risk type items.

A-IRB Modelled CCF: For A-IRB exposures, provide the bank's own modelled CCF estimate (0.0 to 1.5) in ccf_modelled. Retail IRB CCFs can exceed 100% due to additional drawdown behaviour. When populated and approach is A-IRB, this value takes precedence over the risk_type lookup.

Example:

from datetime import date
import polars as pl

facilities = pl.DataFrame({
    "facility_reference": ["FAC_001", "FAC_002"],
    "product_type": ["rcf", "term_loan"],
    "book_code": ["CORP_LENDING", "CORP_LENDING"],
    "counterparty_reference": ["CORP_001", "CORP_002"],
    "value_date": [date(2024, 1, 15), date(2023, 6, 1)],
    "maturity_date": [date(2029, 1, 15), date(2028, 6, 1)],
    "currency": ["GBP", "GBP"],
    "limit": [10_000_000.0, 5_000_000.0],
    "committed": [True, True],
    "lgd": [None, None],  # Supervisory LGD used for F-IRB
    "beel": [None, None],
    "is_revolving": [True, False],
    "seniority": ["senior", "senior"],
    "risk_type": ["MR", "MR"],  # Medium risk - committed undrawn
    "ccf_modelled": [None, None],  # No modelled CCF (use regulatory)
})

Loan Schema¶

Purpose: Defines drawn loan exposures (leaf nodes in exposure hierarchy). Loans represent actual credit usage under facilities.

File: exposures/loans.parquet

Note: Loans do not have CCF fields (risk_type, ccf_modelled, is_short_term_trade_lc) because CCF only applies to off-balance sheet items. For drawn loans, EAD = drawn_amount + interest directly.

Example:

from datetime import date
import polars as pl

loans = pl.DataFrame({
    "loan_reference": ["LOAN_001", "LOAN_002", "LOAN_003"],
    "product_type": ["rcf_drawing", "term_loan", "term_loan"],
    "book_code": ["CORP_LENDING", "CORP_LENDING", "CORP_LENDING"],
    "counterparty_reference": ["CORP_001", "CORP_001", "CORP_002"],
    "value_date": [date(2024, 3, 1), date(2024, 4, 15), date(2023, 6, 1)],
    "maturity_date": [date(2029, 1, 15), date(2029, 1, 15), date(2028, 6, 1)],
    "currency": ["GBP", "GBP", "GBP"],
    "drawn_amount": [2_000_000.0, 1_500_000.0, 5_000_000.0],
    "interest": [10_000.0, 7_500.0, 25_000.0],  # Accrued interest
    "lgd": [None, None, None],
    "beel": [None, None, None],
    "seniority": ["senior", "senior", "senior"],
    "is_buy_to_let": [False, False, False],
    "has_netting_agreement": [False, False, False],
    "netting_facility_reference": [None, None, None],
})

Contingent Schema¶

Purpose: Defines off-balance sheet commitments that require Credit Conversion Factor (CCF) application.

File: exposures/contingents.parquet

Example:

from datetime import date
import polars as pl

contingents = pl.DataFrame({
    "contingent_reference": ["CONT_001", "CONT_002", "CONT_003"],
    "product_type": ["trade_finance", "guarantee", "import_lc"],
    "book_code": ["TRADE", "GUARANTEE", "TRADE"],
    "counterparty_reference": ["CORP_001", "CORP_002", "CORP_003"],
    "value_date": [date(2024, 1, 1), date(2024, 2, 1), date(2024, 3, 1)],
    "maturity_date": [date(2025, 1, 1), date(2025, 2, 1), date(2024, 6, 1)],
    "currency": ["GBP", "GBP", "GBP"],
    "nominal_amount": [500_000.0, 1_000_000.0, 250_000.0],
    "lgd": [None, None, None],
    "beel": [None, None, None],
    "seniority": ["senior", "senior", "senior"],
    "risk_type": ["FR", "MR", "MLR"],  # FR=100%, MR=50%/75%, MLR=20%/75%
    "ccf_modelled": [None, None, None],  # No modelled CCF
    "is_short_term_trade_lc": [False, False, True],  # Third is Art. 166(9) exception
    "bs_type": ["OFB", "OFB", "OFB"],  # Off-balance sheet (default)
})

Collateral Schema¶

Purpose: Defines collateral/security items used for Credit Risk Mitigation (CRM). Collateral can be linked at counterparty, facility, or loan level.

File: collateral/collateral.parquet

Valid collateral_type values:

Valid beneficiary_type values:

Example:

from datetime import date
import polars as pl

collateral = pl.DataFrame({
    "collateral_reference": ["COLL_001", "COLL_002"],
    "collateral_type": ["cash", "real_estate"],
    "currency": ["GBP", "GBP"],
    "maturity_date": [None, None],
    "market_value": [1_000_000.0, 500_000.0],
    "nominal_value": [1_000_000.0, None],
    "beneficiary_type": ["counterparty", "loan"],
    "beneficiary_reference": ["CORP_001", "LOAN_003"],
    "issuer_cqs": [None, None],
    "issuer_type": [None, None],
    "residual_maturity_years": [None, None],
    "is_eligible_financial_collateral": [True, False],
    "is_eligible_irb_collateral": [True, True],
    "valuation_date": [date(2024, 12, 31), date(2024, 11, 15)],
    "valuation_type": ["market", "independent"],
    "property_type": [None, "residential"],
    "property_ltv": [None, 0.65],
    "is_income_producing": [None, False],
    "is_adc": [None, False],
    "is_presold": [None, None],
})

Guarantee Schema¶

Purpose: Defines guarantee protection for Credit Risk Mitigation using the substitution approach.

File: guarantee/guarantee.parquet

Valid guarantee_type values:

Example:

from datetime import date
import polars as pl

guarantees = pl.DataFrame({
    "guarantee_reference": ["GUAR_001"],
    "guarantee_type": ["guarantee"],
    "guarantor": ["SOV_001"],  # UK Treasury guaranteeing
    "currency": ["GBP"],
    "maturity_date": [date(2030, 12, 31)],
    "amount_covered": [2_000_000.0],
    "percentage_covered": [1.0],
    "beneficiary_type": ["counterparty"],
    "beneficiary_reference": ["CORP_001"],
})

Provision Schema¶

Purpose: Defines IFRS 9 provisions/impairments for EAD reduction and IRB expected loss comparison.

File: provision/provision.parquet

Valid provision_type values:

Valid beneficiary_type values:

Valid ifrs9_stage values:

Example:

from datetime import date
import polars as pl

provisions = pl.DataFrame({
    "provision_reference": ["PROV_001", "PROV_002"],
    "provision_type": ["scra", "gcra"],
    "ifrs9_stage": [1, 2],
    "currency": ["GBP", "GBP"],
    "amount": [50_000.0, 100_000.0],
    "as_of_date": [date(2024, 12, 31), date(2024, 12, 31)],
    "beneficiary_type": ["loan", "counterparty"],
    "beneficiary_reference": ["LOAN_001", "CORP_002"],
})

Rating Schema¶

Purpose: Defines internal and external credit ratings for risk weight determination.

File: ratings/ratings.parquet

Valid rating_agency values:

CQS Mapping:

*UK deviation: CQS 2 institutions get 30% RW (not 50%)

Example:

from datetime import date
import polars as pl

ratings = pl.DataFrame({
    "rating_reference": ["RAT_001", "RAT_002"],
    "counterparty_reference": ["CORP_001", "SOV_001"],
    "rating_type": ["external", "external"],
    "rating_agency": ["SP", "SP"],
    "rating_value": ["BBB+", "AA"],
    "cqs": [3, 1],
    "pd": [None, None],
    "rating_date": [date(2024, 6, 15), date(2024, 1, 1)],
    "is_solicited": [True, True],
})

FX Rates Schema¶

Purpose: Defines FX (foreign exchange) rates for converting exposure amounts from their original currencies to a reporting currency. This enables consistent RWA calculations across multi-currency portfolios.

File: fx_rates/fx_rates.parquet

Usage: - Rates should be provided for all currency pairs needed (source → target) - Include identity rates (e.g., GBP→GBP = 1.0) for the target currency - The target currency should match CalculationConfig.base_currency

Converted Fields: - Exposures: drawn_amount, undrawn_amount, nominal_amount - Collateral: market_value, nominal_value - Guarantees: amount_covered - Provisions: amount

Audit Trail: After conversion, the following columns are added: - original_currency - Currency before conversion - original_amount - Amount before conversion (drawn + nominal) - fx_rate_applied - Rate used (null if no conversion needed)

Example:

from datetime import date
import polars as pl

fx_rates = pl.DataFrame({
    "currency_from": ["GBP", "USD", "EUR", "JPY", "CHF"],
    "currency_to": ["GBP", "GBP", "GBP", "GBP", "GBP"],
    "rate": [1.0, 0.79, 0.88, 0.0053, 0.89],
})

Behaviour: - Missing rates: Exposures in currencies without rates retain original values; fx_rate_applied is null - FX disabled: Set apply_fx_conversion=False in CalculationConfig to skip conversion - No FX file: If fx_rates.parquet is not provided, no conversion occurs

Specialised Lending Schema¶

Purpose: Defines specialised lending metadata for slotting approach treatment (CRE33). Keyed by counterparty_reference — all exposures to an SL counterparty inherit the same slotting treatment. This allows a corporate counterparty to have both SL and non-SL exposures.

File: ratings/specialised_lending.parquet

Valid sl_type values:

Valid slotting_category values:

Equity Exposure Schema¶

Purpose: Defines equity holdings (SA only under Basel 3.1, IRB approaches withdrawn).

Valid equity_type values:

Facility Mapping Schema¶

Purpose: Defines parent-child relationships between facilities, loans, and contingents.

File: exposures/facility_mapping.parquet

Example:

import polars as pl

facility_mapping = pl.DataFrame({
    "parent_facility_reference": ["FAC_001", "FAC_001", "FAC_001"],
    "child_reference": ["LOAN_001", "LOAN_002", "FAC_001A"],
    "child_type": ["loan", "loan", "facility"],
})

Org Mapping Schema¶

Purpose: Defines organisation hierarchy for rating and turnover inheritance.

File: mapping/org_mapping.parquet

Example:

import polars as pl

org_mapping = pl.DataFrame({
    "parent_counterparty_reference": ["CORP_PARENT", "CORP_PARENT"],
    "child_counterparty_reference": ["CORP_001", "CORP_002"],
})

Lending Mapping Schema¶

Purpose: Defines lending groups for retail threshold aggregation.

File: mapping/lending_mapping.parquet

Exposures are aggregated to the group level for retail eligibility (threshold: EUR 1m / GBP 880k).

Model Permissions Schema¶

Purpose: Defines per-model IRB approach permissions, enabling granular control over which exposures can use FIRB, AIRB, or slotting. When permission_mode=PermissionMode.IRB, model permissions drive all approach routing. When absent in IRB mode, the pipeline falls back to SA for all exposures with a warning.

Why model-level permissions matter: Banks typically have multiple IRB models, each approved for specific exposure classes, geographies, and portfolios. This schema allows the calculator to resolve the correct approach per-exposure based on the model it belongs to, rather than applying a single org-wide permission.

File: config/model_permissions.parquet

Approach determination logic:

Example:

import polars as pl

model_permissions = pl.DataFrame({
    "model_id": ["UK_CORP_PD_01", "UK_CORP_PD_01", "EU_INST_01"],
    "exposure_class": ["corporate", "corporate_sme", "institution"],
    "approach": ["advanced_irb", "foundation_irb", "advanced_irb"],
    "country_codes": ["GB", "GB,IE", None],  # None = all geographies
    "excluded_book_codes": [None, "LEGACY_BOOK", None],
})

Data Preparation Checklist¶

Before running the calculator, verify your data meets these requirements:

• [ ] All required files present in expected locations
• [ ] Column names match schema exactly (case-sensitive)
• [ ] Data types match expected types
• [ ] All required columns have non-null values
• [ ] Reference columns have valid foreign key relationships
• [ ] Dates are in YYYY-MM-DD format
• [ ] Currency codes are valid ISO 4217
• [ ] Country codes are valid ISO 3166-1 alpha-2
• [ ] Numeric amounts are non-negative where expected
• [ ] PD values are in range [0, 1]
• [ ] LGD values are in range [0, 1.25]

See Data Validation Guide for validation functions and troubleshooting.

Next Steps¶

• Data Validation Guide - Validation rules and error handling
• Intermediate Schemas - Pipeline intermediate data
• Output Schemas - Calculation results