Skip to content

Alias Profiles

Alias profiles enable CalcBridge to ingest data from any source by normalizing column headers to a canonical schema.

How Alias Profiles Work

When a workbook is uploaded:

  1. Profile Selection: CalcBridge matches the workbook against available profiles using sheet name hints and required fields
  2. Header Normalization: Column headers are mapped to canonical field names using the alias dictionary
  3. Validation: Normalized data is validated against domain-specific rules
  4. Storage: Data is stored using canonical field names
flowchart LR
    subgraph Input["Data Source"]
        H1["Par Amount"]
        H2["Face Value"]
        H3["Notional"]
    end

    subgraph Profile["Alias Profile"]
        MAP["par_value:\n- Par Amount\n- Face Value\n- Notional"]
    end

    subgraph Output["Canonical"]
        CANON["par_value"]
    end

    H1 --> MAP
    H2 --> MAP
    H3 --> MAP
    MAP --> CANON

Profile Configuration

CLO Profiles

Located in config/clo_aliases/*.json:

{
  "profile": "default",
  "description": "Generic CLO alias map",
  "sheet_name_hints": ["Holdings", "Portfolio"],
  "required_fields": ["company", "quantity"],
  "required_any_of": [["cusip", "isin"]],
  "aliases": {
    "cusip": ["CUSIP", "cusip_id", "CUSIP ID"],
    "par_value": ["Par", "Par Amount", "Face Value", "Notional"],
    "spread": ["Spread", "DM", "Discount Margin"]
  }
}

Servicer Profiles

Located in config/servicer_aliases/*.json:

{
  "profile": "default",
  "description": "Baseline servicer snapshot",
  "sheet_name_hints": {
    "key_data": ["Key Data"],
    "risk_restrictions": ["Risk Restrictions"]
  },
  "section_aliases": {
    "key_data": {
      "snapshot": ["Total Assets", "NAV"],
      "borrower": ["Borrower Name", "Entity"]
    }
  }
}

Mapping Overrides

Users can override alias profiles with custom mapping configurations via the Mappings API:

  1. Create a mapping config with custom field mappings
  2. Mapping configs take precedence over alias profiles during ingestion
  3. Useful for sources that don't match any existing profile

Schema Drift Detection

CalcBridge monitors for schema drift - changes in source data structure over time:

  • New columns: Columns not in the alias profile are flagged
  • Missing columns: Expected columns not found are reported
  • Type changes: Data type changes are detected
  • Drift diagnostics are included in ingest reports

Adding New Profiles

To add a new alias profile:

  1. Create a JSON file in the appropriate directory (clo_aliases/ or servicer_aliases/)
  2. Define profile, description, and sheet_name_hints
  3. Map canonical fields to source column aliases
  4. Include required_fields and required_any_of for validation
  5. Add rating crosswalks if applicable (CLO profiles)