Skip to content

Compliance Models

This page documents the data models related to compliance testing, test suites, results, and thresholds.

TestSuite

Represents a collection of compliance tests.

Properties

Property Type Description
id string Suite identifier
name string Suite display name
description string? Suite description
test_count integer Number of tests in suite
categories string[] Test categories included
tests TestDefinition[]? Test definitions (when requested)
is_system boolean Whether suite is system-defined
created_at string (ISO 8601) Creation timestamp

Example

{
  "id": "standard",
  "name": "Standard CLO Tests",
  "description": "Common compliance tests for CLO portfolios",
  "test_count": 15,
  "categories": ["concentration", "rating", "coverage", "portfolio"],
  "tests": [
    {
      "test_id": "concentration_single_obligor",
      "name": "Single Obligor Concentration",
      "category": "concentration",
      "description": "Maximum exposure to any single obligor",
      "default_threshold": 5.0,
      "threshold_type": "max"
    }
  ],
  "is_system": true,
  "created_at": "2025-01-01T00:00:00Z"
}

TestDefinition

Definition of a single compliance test.

Properties

Property Type Description
test_id string Unique test identifier
name string Test display name
category TestCategory Test category
description string Test description
default_threshold number Default threshold value
threshold_type ThresholdType Type of threshold comparison
formula string? Formula used for calculation
unit string? Unit of measurement

Example

{
  "test_id": "concentration_single_obligor",
  "name": "Single Obligor Concentration",
  "category": "concentration",
  "description": "Maximum exposure to any single obligor",
  "default_threshold": 5.0,
  "threshold_type": "max",
  "formula": "MAX(obligor_exposure) / SUM(par_value) * 100",
  "unit": "percentage"
}

TestCategory

Enumeration of compliance test categories.

Value Description Example Tests
concentration Obligor/industry concentration Single obligor, Top 5, Industry
rating Credit rating thresholds CCC bucket, Average rating
coverage Coverage ratio tests OC test, IC test
portfolio Portfolio composition WAL, WAS, Diversity score
liquidity Liquidity requirements Cash reserve, Principal proceeds

ThresholdType

Enumeration of threshold comparison types.

Value Description Pass Condition
max Maximum threshold value <= threshold
min Minimum threshold value >= threshold
exact Exact match value == threshold
range Value within range min <= value <= max

ComplianceResult

Results from running compliance tests.

Properties

Property Type Description
id string (UUID) Result identifier
workbook_id string (UUID) Tested workbook
test_suite string Test suite used
status ResultStatus Execution status
summary ResultSummary Aggregated results
results TestResult[] Individual test results
executed_at string (ISO 8601) Execution timestamp
execution_time_ms integer Processing time

Example

{
  "id": "770e8400-e29b-41d4-a716-446655440002",
  "workbook_id": "550e8400-e29b-41d4-a716-446655440000",
  "test_suite": "standard",
  "status": "completed",
  "summary": {
    "total": 15,
    "passed": 13,
    "failed": 2,
    "warnings": 1,
    "skipped": 0
  },
  "results": [
    {
      "test_id": "concentration_single_obligor",
      "test_name": "Single Obligor Concentration",
      "category": "concentration",
      "status": "pass",
      "current_value": 4.2,
      "threshold_value": 5.0,
      "threshold_type": "max",
      "cushion": 0.8,
      "cushion_pct": 16.0,
      "message": "Single obligor concentration within limit"
    }
  ],
  "executed_at": "2026-01-25T10:30:00Z",
  "execution_time_ms": 1523
}

ResultStatus

Enumeration of compliance run statuses.

Value Description
pending Run queued
running Tests executing
completed All tests finished
failed Execution error

ResultSummary

Aggregated compliance test results.

Properties

Property Type Description
total integer Total tests run
passed integer Tests that passed
failed integer Tests that failed
warnings integer Tests with warnings
skipped integer Tests skipped

Example

{
  "total": 15,
  "passed": 13,
  "failed": 2,
  "warnings": 1,
  "skipped": 0
}

TestResult

Result of a single compliance test.

Properties

Property Type Description
test_id string Test identifier
test_name string Test display name
category TestCategory Test category
status TestStatus Pass/fail/warning status
current_value number Calculated metric value
threshold_value number Configured threshold
threshold_type ThresholdType Threshold comparison type
cushion number Distance to threshold
cushion_pct number Cushion as percentage
message string Result description
details TestDetails? Detailed breakdown

Example

{
  "test_id": "rating_ccc_bucket",
  "test_name": "CCC Rated Assets",
  "category": "rating",
  "status": "fail",
  "current_value": 8.5,
  "threshold_value": 7.5,
  "threshold_type": "max",
  "cushion": -1.0,
  "cushion_pct": -13.33,
  "message": "CCC rated assets exceed maximum threshold",
  "details": {
    "formula": "=SUMIF(Ratings, \"CCC*\", Par) / SUM(Par)",
    "cell_refs": ["Sheet1!G:G", "Sheet1!D:D"],
    "breakdown": {
      "ccc_par": 8500000,
      "total_par": 100000000
    }
  }
}

TestStatus

Enumeration of individual test result statuses.

Value Description Condition
pass Test passes Within threshold
fail Test fails Exceeds threshold
warning Approaching threshold Within warning threshold
skipped Test not run Missing data or disabled
error Calculation error Formula or data error

TestDetails

Detailed information about test calculation.

Properties

Property Type Description
formula string? Formula used for calculation
cell_refs string[]? Excel cell references used
breakdown object? Calculation breakdown

Example

{
  "formula": "=SUMIF(Ratings, \"CCC*\", Par) / SUM(Par)",
  "cell_refs": ["Sheet1!G:G", "Sheet1!D:D"],
  "breakdown": {
    "ccc_par": 8500000,
    "total_par": 100000000,
    "ccc_count": 12,
    "total_count": 150
  }
}

Threshold

Custom threshold configuration.

Properties

Property Type Description
id string (UUID) Threshold identifier
workbook_id string (UUID)? Workbook-specific (null for tenant default)
test_id string Test identifier
threshold_value number Threshold value
threshold_type ThresholdType Comparison type
warning_threshold number? Warning level threshold
enabled boolean Whether test is enabled
created_at string (ISO 8601) Creation timestamp
updated_at string (ISO 8601) Last update timestamp

Example

{
  "id": "880e8400-e29b-41d4-a716-446655440003",
  "workbook_id": "550e8400-e29b-41d4-a716-446655440000",
  "test_id": "concentration_single_obligor",
  "threshold_value": 4.5,
  "threshold_type": "max",
  "warning_threshold": 4.0,
  "enabled": true,
  "created_at": "2026-01-25T10:30:00Z",
  "updated_at": "2026-01-25T10:30:00Z"
}

ThresholdRequest

Request body for creating/updating thresholds.

Properties

Property Type Required Description
workbook_id string (UUID) No Workbook-specific threshold
test_id string Yes Test identifier
threshold_value number Yes Threshold value
threshold_type ThresholdType No Comparison type
warning_threshold number No Warning level
enabled boolean No Enable/disable (default: true)

Example

{
  "workbook_id": "550e8400-e29b-41d4-a716-446655440000",
  "test_id": "concentration_single_obligor",
  "threshold_value": 4.5,
  "threshold_type": "max",
  "warning_threshold": 4.0
}

ComplianceRunRequest

Request body for running compliance tests.

Properties

Property Type Required Description
workbook_id string (UUID) Yes Workbook to test
test_suite string No Test suite (default: "standard")
test_ids string[] No Specific tests (all if omitted)
options RunOptions No Execution options

RunOptions

Property Type Default Description
include_cushion boolean true Calculate cushion values
fail_fast boolean false Stop on first failure
parallel boolean true Run tests in parallel

Example

{
  "workbook_id": "550e8400-e29b-41d4-a716-446655440000",
  "test_suite": "standard",
  "test_ids": ["concentration_single_obligor", "rating_ccc_bucket"],
  "options": {
    "include_cushion": true,
    "fail_fast": false
  }
}

Cushion Calculation

Cushion represents the distance between current value and threshold.

For Maximum Thresholds

cushion = threshold_value - current_value
cushion_pct = (cushion / threshold_value) * 100

For Minimum Thresholds

cushion = current_value - threshold_value
cushion_pct = (cushion / threshold_value) * 100

Interpretation

Cushion Meaning
Positive Passing with headroom
Zero At threshold boundary
Negative Failing (breach)

Standard Test Suite

The "standard" test suite includes these tests:

Concentration Tests

Test ID Name Default Threshold
concentration_single_obligor Single Obligor 5.0% (max)
concentration_top_5 Top 5 Obligors 20.0% (max)
concentration_top_10 Top 10 Obligors 35.0% (max)
concentration_industry Single Industry 15.0% (max)

Rating Tests

Test ID Name Default Threshold
rating_ccc_bucket CCC Rated Assets 7.5% (max)
rating_average_factor Average Rating Factor 2600 (max)
rating_b_minus_below B- and Below 10.0% (max)

Coverage Tests

Test ID Name Default Threshold
coverage_oc_senior Senior OC Test 120.0% (min)
coverage_oc_junior Junior OC Test 110.0% (min)
coverage_ic Interest Coverage 150.0% (min)

Portfolio Tests

Test ID Name Default Threshold
portfolio_wal Weighted Average Life 5.0 years (max)
portfolio_was Weighted Average Spread 3.0% (min)
portfolio_diversity Diversity Score 50 (min)