Designing a Financial Instrument Domain Model for Trading Systems

The modeling principle

The useful question is not “which subclass is this?” It is a set of independent questions: What is it? What economic exposure does it represent? What product family does it belong to? What exact contract terms apply? Where is it listed? How is it identified by each provider? How does it trade and settle? Treat the answers as separate dimensions.

FinancialInstrument
├── Identity
├── Classification: AssetClass, InstrumentType, InstrumentSubType, CFI
├── Economics: currency, underlying, multiplier, contract size
├── TypeSpecificTerms
├── Lifecycle
├── Identifiers[]
├── Listings[]
└── Relationships[]

Separate the domain layers

Keep the economic or reference object separate from the financial product, the concrete instrument, and its market representation. An issuer, currency, commodity, index, rate, basket, or reference entity can be an economic reference. A product family describes the family of exposure. A concrete instrument adds exact terms. A listing or venue instrument describes where and under which market segment it trades.

Classification is not identity

InstrumentType, CFI, security classification, and asset class explain what an instrument is. They do not identify one exact instrument. ISIN, CFI, MIC, ticker, exchange symbol, and provider IDs serve different namespaces and should remain separate records with source and validity metadata. A classification code must never be used as an internal instrument ID.

Type-specific terms without nullable-field sprawl

Shared fields belong on the core instrument. Product-specific terms belong in separate value objects: EquityTerms, BondTerms, OptionTerms, FutureTerms, ForwardTerms, SwapTerms, PerpetualTerms, and FundTerms. For an option, keep underlying, call or put, strike, exercise style, expiration, and settlement together. Do not put every possible strike, coupon, funding rate, and face value into one table as nullable columns.

OptionTerms {
  underlying: InstrumentId,
  callPut: CallPut,
  strike: Decimal,
  exerciseStyle: ExerciseStyle,
  expiration: Instant,
  settlement: SettlementSpecification
}

Canonical instrument, listing, and provider mapping

A canonical instrument can have multiple listings and multiple provider mappings. A venue symbol such as BTCUSDT, BTC-USDT, or an IBKR contract identifier is a representation in a namespace, not a universal identity. Preserve provider, venue, market segment, native symbol, native contract ID, environment, validity, and verification evidence in the mapping.

CanonicalInstrument
  ├── VenueInstrument / Listing
  │     └── InstrumentIdentifier[]
  └── ProviderInstrumentMapping[]

Trading rules and lifecycle are first-class

Trading behavior belongs outside the instrument identity but must be linked to it. Model price increments, quantity rules, trading calendars, sessions, status, issue and effective dates, expiry or maturity, settlement specifications, corporate actions, and delisting or successor events. The same canonical product may have different rules on two venues or in two environments.

• PriceIncrementRule and QuantityRule define valid orders.
• TradingCalendar and TradingSession define when orders and data are valid.
• InstrumentLifecycle records issue, effective, expiry, maturity, status, and transitions.
• SettlementSpecification captures settlement asset, currency, timing, and method.

Relationships instead of hidden inheritance

Use explicit relationships for meaning that crosses products: UNDERLYING, DERIVED_FROM, CONVERTS_TO, DELIVERS, TRACKS, COMPONENT_OF, SUCCESSOR_OF, ROLLS_TO, and SAME_SHARE_CLASS. This represents options, futures, ETFs, indices, baskets, rolls, deliverables, and multi-leg instruments without pretending they are all the same subtype.

Implementation checklist

1. Assign a stable internal identity independent of ticker and provider.
2. Attach classifications and economic exposure as separate dimensions.
3. Store type-specific terms in dedicated structures.
4. Model listings, venue instruments, and provider mappings explicitly.
5. Attach rules, lifecycle, settlement, and corporate actions with effective dates.
6. Represent underlyings, components, deliverables, successors, and legs as relationships.
7. Require exact, current mappings before an execution command reaches a broker adapter.