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.

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.
  },

  "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.

  "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",
  "isin": "US0378331005", // International Securities Identification Number. Unique global ID.
  "name": "Apple Inc.",
  "type": "EQUITY", // EQUITY, ETF, CRYPTO, OPTION, MUTUAL_FUND.
  "currency": "USD",
  "market_price": 176.19,
  "last_updated": "2023-10-01T15:00:00Z"
}

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.