Skip to content

FintraOS Open Standard (FOS)

1. The Vision: A Universal Language for Money

The financial industry is built on a Tower of Babel. A "Transaction" in a banking core looks nothing like a "Transaction" in a credit card processor, which looks nothing like a "Transaction" in an Open Banking API.

This fragmentation forces every fintech developer to build "Translation Layers" — brittle adapters that normalise data before they can even start building their actual product.

FintraOS Open Standard (FOS) is an open-source data schema designed to be the "HTML of Finance." Just as HTML allows any browser to render any website, FOS allows any financial application to understand any financial life, regardless of where the data originated.

Note: FOS is the public specification. Inside FintraOS Core, this standard will be implemented as the Unified Financial Profile.

2. Core Design Principles

  1. Strict Typing: Money is not a float. Dates are not strings. We use strict, safe types for all monetary values to prevent rounding errors.
  2. Entity-Centric: We model the entity (The Loan, The Investment), not just the transaction stream.
  3. Intelligence-Ready: The schema includes fields specifically for AI/ML features (e.g., recurrence_group_id, carbon_footprint), not just raw bank data.
  4. Privacy-First: PII (Personally Identifiable Information) is segregated from the financial behaviour data.

2.1. Canonical Representations (Money, Time, Provenance)

To keep the platform deterministic and audit-ready, FOS defines canonical representation rules:

  • Timestamps: ISO‑8601 UTC (YYYY-MM-DDTHH:MM:SSZ) at API boundaries; internal processing should retain full precision and timezone correctness.
  • Money: use integer minor units for computation and event payloads (for example amount_minor), and use decimal strings (or structured { value, currency }) for human-readable API views.
  • Provenance: any derived number (metrics, valuations, explanations) must be attributable to a specific stream position (for example source_event_id and source_version).

3. Data Domains

The standard is divided into four domain pillars. Each represents a distinct aspect of a user's financial life.

A. Banking & Accounts

The foundation of day-to-day money management.

This domain covers liquid assets and daily spending. It standardises how we represent containers of value (UnifiedAccount) and the movement of money (UnifiedTransaction).

UnifiedAccount

Narrative: An account is the fundamental container. However, "Account" means different things in different contexts. A checking account needs an available_balance to prevent overdrafts. A credit card needs a limit to calculate utilisation. A savings account needs an APY to calculate projected returns.

Schema & Field Guide: 

{
  "account_id": "acc_890",
  "type": "DEPOSITORY", 
  // CRITICAL: The high-level category. Determines which downstream models run.
  // Options: DEPOSITORY (Cash), CREDIT (Cards), LOAN (Debt), INVESTMENT (Assets), PROPERTY.

  "subtype": "CHECKING", 
  // Granular classification for UI and Logic.
  // e.g., "401K" triggers tax rules; "BITCOIN_WALLET" triggers crypto custody logic.

  "name": "Barclays Premier Current",
  "mask": "4499", // Safe-to-display last 4 digits.
  "currency": "GBP",

  "balances": {
    "current": 1450.50, 
    // The "Posted Balance". What the bank says you have right now.

    "available": 1400.00, 
    // The "Spendable Balance". (Current - Pending Transactions). 
    // CRITICAL for "Can I afford this?" checks.

    "limit": 2000.00 
    // Credit Limit or Overdraft Limit. 
    // Used to calculate "Credit Utilisation Ratio" (Risk Score input).
  },

  "apy": 0.05, // Annual Percentage Yield (5.0%). Used for "Idle Cash" optimisation alerts.
  "apr": 0.0 // Annual Percentage Rate. Used for "Debt Cost" analysis.
}

UnifiedTransaction

Narrative: Transactions are the heartbeat of finance. But raw bank transactions are messy ("AMZN MKTPL SEATTLE WA"). FOS transforms them into rich, structured events. We distinguish between authorised dates (when it happened) and posted dates (when it settled) to enable accurate cashflow forecasting.

Schema & Field Guide: 

{
  "transaction_id": "tx_123",
  "account_id": "acc_890",

  "amount": { 
    "value": "-12.50", // Negative = Money leaving the user.
    "currency": "GBP" 
  },

  "status": "POSTED", 
  // PENDING: Temporary hold. Might change amount or disappear.
  // POSTED: Final settlement. Immutable history.

  "dates": { 
    "posted": "2023-10-01", 
    "authorised": "2023-09-30" // The actual moment of purchase. Best for analytics.
  },

  "balance_after": { "value": "1387.50", "currency": "GBP" },
  // Optional: running balance after the transaction posts, when supplied by the source.
  // This supports deterministic reconciliation and balance derivation without requiring separate balance snapshots.

  "details": {
    "type": "PAYMENT", 
    // PAYMENT: Standard spend.
    // TRANSFER: Internal movement (neutral to net worth).
    // FEE: Bank charge (avoidable expense).
    // INTEREST: Passive income/cost.

    "channel": "ONLINE" // ONLINE vs IN_STORE. Used for fraud detection and behavioural profiling.
  },

  "merchant": {
    "raw_name": "TFL TRAVEL CH", // The ugly string from the bank.
    "clean_name": "Transport for London", // The human-readable entity.
    "logo_url": "https://logos.fintraos.com/tfl.png",
    "category_code": "5812", // ISO 18245 Merchant Category Code (MCC).
    "website": "tfl.gov.uk"
  },

  "enrichment": {
    // Derived intelligence layers
    "category": ["Transport", "Public Transport"], // Hierarchical taxonomy.
    "is_recurring": true, // Flagged by the Recurring Engine.
    "recurrence_group_id": "rec_999", // Links this tx to its "Subscription" parent.
    "carbon_footprint_g": 150 // Environmental impact score.
  }
}

B. Wealth & Investments

The engine of long-term net worth.

Simple aggregators often treat investments as a single number. FOS breaks them down into Holdings and Securities. This separation allows us to track what you own separately from what it is worth, enabling real-time portfolio re-valuation even if the bank connection is stale.

UnifiedInvestmentHolding

Narrative: Represents "My ownership of Apple Stock." It links a User Account to a global Security.

Schema & Field Guide: 

{
  "holding_id": "hold_555",
  "account_id": "acc_inv_01",
  "security_id": "sec_aapl", // Link to the global asset definition.

  "quantity": 10.5, // How many units held.

  "display_symbol": "AAPL",
  // Optional: the symbol you want to show in product UI.

  "quote_symbol": "AAPL",
  // Optional: canonical provider symbol used for pricing lookups (may differ from display_symbol).

  "quote_currency": "USD",
  // Optional: quote currency for the instrument; used for FX conversion during base-currency valuation.

  "cost_basis": { "value": 1500.00, "currency": "USD" }, 
  // What you paid. Essential for Capital Gains Tax calculations.

  "current_value": { "value": 1850.00, "currency": "USD" },
  // What it's worth now (Quantity * Market Price).

  "performance": {
    "gain_loss_abs": 350.00, // Absolute profit.
    "gain_loss_pct": 0.233 // 23.3% return. Used for "Portfolio Health" dashboard.
  }
}

UnifiedSecurity

Narrative: Represents "Apple Stock" itself. This data is global and shared across all users holding this asset.

Schema & Field Guide: 

{
  "security_id": "sec_aapl",
  "symbol": "AAPL",
  "quote_symbol": "AAPL",
  // Canonical provider symbol (may be exchange-qualified), used for pricing tools/providers.
  "isin": "US0378331005", // International Securities Identification Number. Unique global ID.
  "name": "Apple Inc.",
  "type": "EQUITY", // EQUITY, ETF, CRYPTO, OPTION, MUTUAL_FUND.
  "currency": "USD",
  "quote_currency": "USD",
  "market_price": 176.19,
  "last_updated": "2023-10-01T15:00:00Z"
}

3.1. Deterministic Mapping Plans (Schema-Flexible Ingestion)

Real-world payloads rarely arrive in a perfect FOS shape. FintraOS supports schema-flexible ingestion using deterministic mapping plans:

  • A mapping plan describes how to extract records and fields from an arbitrary payload (CSV/JSON/webhooks) and transform them into FOS entities.
  • Mapping plans are designed to be replayable (the same payload + plan always yields the same output).
  • Mapping plans can be proposed by AI, but must be validated deterministically; validation failures are structured so plans can be repaired without manual guesswork.

This approach keeps ingestion extensible (“webhooks-as-data”) without sacrificing auditability.

3.2. Base-Currency Valuation and Missing Price Visibility

FOS supports consistent valuation across mixed-currency holdings:

  • All user-facing totals are expressed in a profile base currency.
  • Price and FX inputs are treated as time-stamped reference data with explicit provenance.
  • When a holding cannot be priced or converted, the system must surface this explicitly (for example via an “unpriced assets” list) rather than silently omitting it from totals.

3.3. AI Compatibility (Tool-Driven, Provenance-First)

FOS is “AI-ready” by design, but the AI layer must be constrained:

  • AI may not invent numbers; numeric claims must be derived from tool outputs or deterministic projections.
  • Responses must include sources[] sufficient to reproduce and audit the result.

C. Liabilities & Debt

The obligations that impact future cashflow.

Debt is often hidden in "Negative Balances." FOS elevates Debt to a first-class citizen (UnifiedLiability). We model the terms of the debt, not just the balance. This enables powerful "Refinancing Calculator" and "Debt Avalanche" features.

UnifiedLiability

Narrative: Used for Mortgages, Student Loans, and Vehicle Finance. It captures the "Cost of Debt" and the "Timeline to Freedom."

Schema & Field Guide: 

{
  "account_id": "acc_mort_99",

  "principal": { "value": 250000.00, "currency": "GBP" }, 
  // The remaining amount owed.

  "interest_rate": {
    "percentage": 4.5,
    "type": "FIXED" 
    // FIXED vs VARIABLE. 
    // Crucial for "Rate Shock" simulation (e.g., "What if rates rise to 6%?").
  },

  "terms": {
    "term_months": 300, // 25 Year Mortgage.
    "start_date": "2020-01-01",
    "end_date": "2045-01-01" // The "Debt Free Date".
  },

  "payment": {
    "next_payment_due_date": "2023-11-01", 
    // Used for "Bill Calendar" and "Late Fee Prevention".

    "minimum_payment": 1450.00 
    // The contractual floor. Anything paid above this is "Overpayment" (accelerates payoff).
  }
}

D. Intelligence & Patterns

The derived layer that makes data actionable.

This is where FintraOS will shine. We will not just store data; we will interpret it. These schemas represent the output of our AI/ML engines.

RecurringStream

Narrative: A single transaction is an event; a Stream is a habit. This model identifies Subscriptions (Netflix), Income (Salary), and Bills (Rent). It is the primary input for Cashflow Forecasting.

Schema & Field Guide: 

{
  "stream_id": "str_netflix",
  "name": "Netflix",
  "type": "SUBSCRIPTION", 
  // SUBSCRIPTION: Discretionary, fixed.
  // BILL: Mandatory, variable (e.g., Utilities).
  // SALARY: Income, fixed.
  // DIVIDEND: Income, variable.

  "direction": "OUTFLOW",

  "amount": {
    "average": 15.99, // The predicted amount for the forecast.
    "currency": "GBP",
    "is_variable": false // TRUE if amount fluctuates (e.g., Uber rides).
  },

  "schedule": {
    "frequency": "MONTHLY",
    "interval": 1,
    "next_date": "2023-10-15" // The specific day to place on the calendar.
  },

  "history": ["2023-09-15", "2023-08-15"] // Evidence used to detect this pattern.
}

FinancialHealthScore

Narrative: A standardized "FICO for Financial Wellness." Instead of creditworthiness (can I borrow?), this measures resilience (can I survive?).

Schema & Field Guide: 

{
  "overall_score": 850, // 0-1000 scale.

  "components": {
    "cashflow_score": 78, 
    // 0-100. Do you spend less than you earn? (Burn Rate analysis).

    "solvency_score": 85, 
    // 0-100. Do you own more than you owe? (Net Worth analysis).

    "resilience_days": 45, 
    // The "Runway." If income stopped today, how many days until cash = 0?

    "savings_rate_pct": 0.15 
    // 15% of income is saved. Key metric for "Retirement Velocity."
  }
}

4. Platform Extensibility

The "BYO-Data" layer. Standardising the non-standard.

FOS is not just for banking data. It is a container for any numeric or categorical data that influences a user's financial life.

UnifiedPlatformData

Narrative: Represents data ingested from 3rd-party platforms (Gig Economy apps, eCommerce, Vertical SaaS). It allows FintraOS to correlate "Real World Actions" with "Financial Outcomes."

Schema & Field Guide: 

{
  "data_id": "pdat_888",
  "profile_id": "usr_123",
  "tenant_id": "org_uber_clone",
  "timestamp": "2023-10-27T14:00:00Z",

  "key": "completed_rides", 
  // The metric name. Must be registered in the Metric Registry.

  "value": 45, 
  // The numeric value.

  "context": {
    "service_type": "delivery",
    "region": "london_zone_1"
  }
}

MetricDefinition

Narrative: Defines how to calculate a derived value. This allows the logic to be portable across different FintraOS instances.

Schema & Field Guide: 

{
  "metric_id": "coffee_weekend_avg",
  "display_name": "Weekend Coffee Habit",
  "logic": {
    "filter": "category == 'Coffee' AND day_of_week IN ['Sat', 'Sun']",
    "aggregation": "AVG(amount)",
    "window": "90d"
  },
  "return_type": "CURRENCY" // or NUMBER, PERCENTAGE, BOOLEAN
}

5. Agent Capabilities

Standardising how AI interacts with the world.

AgentSkill

Narrative: A machine-readable definition of a "Tool" that an AI agent can invoke. Based on the OpenAI Function Calling standard but enriched with FintraOS governance fields.

Schema & Field Guide: 

{
  "skill_id": "transfer_money",
  "name": "Transfer Money",
  "description": "Moves money between two accounts belonging to the user.",

  "parameters": {
    "type": "object",
    "properties": {
      "amount": { "type": "number", "description": "Amount to transfer" },
      "from_account": { "type": "string", "description": "Source Account ID" },
      "to_account": { "type": "string", "description": "Destination Account ID" }
    },
    "required": ["amount", "from_account", "to_account"]
  },

  "governance": {
    "required_scope": "WRITE_PAYMENTS",
    "risk_level": "HIGH", // HIGH requires explicit 2FA or Step-up Auth.
    "max_transaction_value": 500.00
  }
}

6. Implementation Strategy

The Artifacts

We will publish a standalone repository fintraos/fos-spec containing: - JSON Schemas: Strict validation rules for all financial entities. - Protobuf Definitions: For high-performance gRPC communication. - TypeScript / Go / Python SDKs: Generated types for easy adoption.

Adoption Plan

  • License: Apache 2.0 (Permissive).
  • Governance: We accept Pull Requests from banks, fintechs, and competitors.
  • Adapters: We will build open-source adapters (e.g., plaid-to-fos, teller-to-fos) to lower the barrier to entry.