Skip to content

Data Models

This section documents the data models used throughout the CalcBridge API. Understanding these models is essential for working with API requests and responses.

Overview

CalcBridge uses consistent data models across all endpoints. Models are organized into the following categories:

Category Description Key Models
Workbook Models Excel file representation Workbook, Sheet, SheetData, Cell
Scenario Models What-if simulation Scenario, Trade, SimulationResult
Compliance Models Compliance testing TestSuite, TestResult, Threshold
User Models Authentication & authorization User, Tenant, Role, APIKey

Common Patterns

UUID Identifiers

All resources use UUID v4 identifiers:

{
  "id": "550e8400-e29b-41d4-a716-446655440000"
}

Timestamps

Timestamps are in ISO 8601 format with UTC timezone:

{
  "created_at": "2026-01-25T10:30:00Z",
  "updated_at": "2026-01-25T11:45:00Z"
}

Pagination

List responses follow a consistent pagination structure:

{
  "items": [...],
  "total": 150,
  "page": 1,
  "page_size": 20,
  "total_pages": 8
}

Error Responses

Error responses include structured error information:

{
  "detail": "Human-readable error message",
  "error_code": "SPECIFIC_ERROR_CODE",
  "request_id": "req_abc123xyz"
}

Type Conventions

Nullable Fields

Fields that may be null are marked as optional in the documentation:

Notation Meaning
string Required string
string? Optional/nullable string
string (UUID) UUID-formatted string
string (ISO 8601) ISO 8601 date/datetime

Enumerations

Enum values are documented with all valid options:

{
  "status": "draft | calculating | completed | failed"
}

Nested Objects

Complex objects are linked to their own model documentation:

{
  "workbook": {
    "id": "...",
    "sheets": [Sheet, ...]  // See Sheet model
  }
}

Model Relationships

Tenant
  |-- User (many)
  |-- APIKey (many)
  |-- Workbook (many)
        |-- Sheet (many)
              |-- SheetData (one)
                    |-- Cell (many)
        |-- ComplianceResult (many)
              |-- TestResult (many)
        |-- Scenario (many)
              |-- Trade (many)
              |-- SimulationResult (one)
        |-- Report (many)
        |-- Alert (many)

Versioning

Models may evolve over time. The API maintains backward compatibility within major versions:

  • Additive changes (new fields): Always backward compatible
  • Field deprecation: Marked with documentation, removed in next major version
  • Breaking changes: Only in major version updates

Deprecated Fields

Deprecated fields are marked in documentation:

{
  "old_field": "value",  // DEPRECATED: Use new_field instead
  "new_field": "value"
}

Quick Reference

Core Resources

Resource Create Read Update Delete
Workbook POST /workbooks GET /workbooks/{id} PATCH /workbooks/{id} DELETE /workbooks/{id}
Scenario POST /scenarios GET /scenarios/{id} PATCH /scenarios/{id} DELETE /scenarios/{id}
Alert POST /alerts/configure GET /alerts/{id} PATCH /alerts/{id} DELETE /alerts/{id}
Mapping POST /mappings GET /mappings/{id} PATCH /mappings/{id} DELETE /mappings/{id}
Report POST /reports/generate GET /reports/{id} - DELETE /reports/{id}

Status Enumerations

Workbook Status: uploading | processing | ready | error | recalculating

Scenario Status: draft | calculating | completed | failed

Compliance Status: pending | running | completed | failed

Report Status: pending | generating | completed | failed

User Status: pending | active | inactive

API Key Status: active | deprecated | revoked

SDK Type Definitions

Type definitions are available for supported SDKs:

import type {
  Workbook,
  Sheet,
  Scenario,
  Trade,
  ComplianceResult,
  User,
  Tenant
} from '@calcbridge/sdk';

from calcbridge.models import (
    Workbook,
    Sheet,
    Scenario,
    Trade,
    ComplianceResult,
    User,
    Tenant
)