{
  "spec_name": "When2Buy Options Data Standard",
  "spec_version": "1.0.0-draft",
  "generated_at_utc": "2026-07-29T00:00:00Z",
  "disclaimer": "Examples in this file are illustrative synthetic values only. Not real market data.",
  "conventions": {
    "timestamps": "ISO-8601, UTC, nanosecond precision where available (e.g. 2026-07-29T13:35:00.123456789Z). Always paired with an exchange_tz IANA name (e.g. America/New_York). Ambiguous local timestamps without a UTC offset are not permitted.",
    "identifiers": "Every instrument carries both a human-readable option_symbol (OCC-style) and a stable internal instrument_id that does not change across corporate actions or symbol reformatting.",
    "dates": "expiration_date and trade_date use YYYY-MM-DD (exchange local calendar date).",
    "prices": "Decimal USD per share/contract unit, never scaled integers. strike_price is decimal (e.g. 552.50), not 552500.",
    "multiplier": "contract_multiplier is explicit on every contract row (typically 100 for standard US equity/ETF/index options).",
    "iv": "implied_volatility is a decimal fraction, e.g. 0.2075 means 20.75%, never a whole-number percent.",
    "greeks": "Sign convention: call delta in [0,1], put delta in [-1,0]; gamma/vega >= 0 for long options; theta typically <= 0 for long options. Every greeks row states model, risk_free_rate_ref, and dividend_yield_input plus the as_of_ts_utc it was computed at.",
    "quotes": "Every NBBO row includes bid/ask price and size, the reporting bid/ask exchange, a quote_condition, a monotonic sequence_number per instrument/venue/day, and an is_correction flag."
  },
  "products": [
    {
      "id": "contract_master",
      "name": "Contract Master / Reference",
      "priority": "P0",
      "sample_file": "sample_contracts.csv",
      "description": "One row per option contract: identifiers, underlying, expiration, strike, type, multiplier, exercise style, currency, listing status.",
      "fields": [
        {"name": "instrument_id", "type": "string", "unit": null, "nullable": false, "example": "SPY-2026-07-29-C-552.50", "priority": "P0", "description": "Stable internal identifier, unaffected by symbol reformatting."},
        {"name": "option_symbol", "type": "string", "unit": null, "nullable": false, "example": "SPY260729C00552500", "priority": "P0", "description": "OCC-style human-readable symbol."},
        {"name": "underlying_symbol", "type": "string", "unit": null, "nullable": false, "example": "SPY", "priority": "P0", "description": "Underlying ticker or index root."},
        {"name": "asset_class", "type": "enum", "unit": null, "nullable": false, "example": "ETF_OPTION", "priority": "P1", "description": "ETF_OPTION | INDEX_OPTION | EQUITY_OPTION."},
        {"name": "primary_listing", "type": "string", "unit": null, "nullable": true, "example": "OPRA_CONSOLIDATED", "priority": "P1", "description": "Consolidated tape or primary listing venue group."},
        {"name": "expiration_date", "type": "date", "unit": "YYYY-MM-DD", "nullable": false, "example": "2026-07-29", "priority": "P0", "description": "Exchange-local expiration calendar date."},
        {"name": "strike_price", "type": "decimal", "unit": "USD", "nullable": false, "example": "552.50", "priority": "P0", "description": "Decimal strike, not scaled integer."},
        {"name": "option_type", "type": "enum", "unit": null, "nullable": false, "example": "C", "priority": "P0", "description": "C (call) or P (put)."},
        {"name": "contract_multiplier", "type": "integer", "unit": "shares/contract", "nullable": false, "example": 100, "priority": "P0", "description": "Explicit multiplier; do not assume 100."},
        {"name": "exercise_style", "type": "enum", "unit": null, "nullable": false, "example": "American", "priority": "P1", "description": "American or European."},
        {"name": "currency", "type": "string", "unit": null, "nullable": false, "example": "USD", "priority": "P1", "description": "ISO 4217 currency code."},
        {"name": "first_listed_date", "type": "date", "unit": "YYYY-MM-DD", "nullable": true, "example": "2026-01-05", "priority": "P2", "description": "Date the contract was first listed for trading."},
        {"name": "is_synthetic", "type": "boolean", "unit": null, "nullable": false, "example": true, "priority": "P0", "description": "Present only in this illustrative sample; not part of production schema."}
      ]
    },
    {
      "id": "nbbo_quotes",
      "name": "NBBO Quote Events",
      "priority": "P0",
      "sample_file": "sample_quotes.csv",
      "description": "Event-level (or, if unavailable at tick granularity, 1-minute derived) National Best Bid/Offer updates per instrument.",
      "fields": [
        {"name": "event_ts_utc", "type": "timestamp", "unit": "ISO-8601 UTC, ns", "nullable": false, "example": "2026-07-29T13:35:00.050000000Z", "priority": "P0", "description": "Event time in UTC with nanosecond precision where available."},
        {"name": "exchange_tz", "type": "string", "unit": "IANA tz", "nullable": false, "example": "America/New_York", "priority": "P0", "description": "Exchange local timezone paired with event_ts_utc."},
        {"name": "instrument_id", "type": "string", "unit": null, "nullable": false, "example": "SPY-2026-07-29-P-548.00", "priority": "P0", "description": "Foreign key to contract_master.instrument_id."},
        {"name": "option_symbol", "type": "string", "unit": null, "nullable": false, "example": "SPY260729P00548000", "priority": "P1", "description": "Denormalized human-readable symbol."},
        {"name": "bid_price", "type": "decimal", "unit": "USD/share", "nullable": true, "example": 0.08, "priority": "P0", "description": "National best bid price; nullable only if one-sided market."},
        {"name": "bid_size", "type": "integer", "unit": "contracts", "nullable": true, "example": 12, "priority": "P0", "description": "Size at national best bid."},
        {"name": "ask_price", "type": "decimal", "unit": "USD/share", "nullable": true, "example": 0.12, "priority": "P0", "description": "National best ask price; nullable only if one-sided market."},
        {"name": "ask_size", "type": "integer", "unit": "contracts", "nullable": true, "example": 12, "priority": "P0", "description": "Size at national best ask."},
        {"name": "bid_exchange", "type": "string", "unit": null, "nullable": true, "example": "CBOE", "priority": "P1", "description": "Venue currently setting the best bid."},
        {"name": "ask_exchange", "type": "string", "unit": null, "nullable": true, "example": "ARCX", "priority": "P1", "description": "Venue currently setting the best ask."},
        {"name": "quote_condition", "type": "enum", "unit": null, "nullable": false, "example": "REGULAR", "priority": "P0", "description": "REGULAR | CROSSED | LOCKED | FAST_MARKET | CLOSED, etc."},
        {"name": "sequence_number", "type": "integer", "unit": null, "nullable": false, "example": 1004, "priority": "P0", "description": "Monotonic per instrument/venue/day; used to detect gaps/out-of-order delivery."},
        {"name": "is_correction", "type": "boolean", "unit": null, "nullable": false, "example": false, "priority": "P0", "description": "True if this event revises/cancels a prior event."}
      ]
    },
    {
      "id": "trades",
      "name": "Trades",
      "priority": "P0",
      "sample_file": "sample_trades.csv",
      "description": "Executed trade prints per instrument with size, venue, and conditions.",
      "fields": [
        {"name": "event_ts_utc", "type": "timestamp", "unit": "ISO-8601 UTC, ns", "nullable": false, "example": "2026-07-29T13:35:00.000000000Z", "priority": "P0", "description": "Trade execution time in UTC."},
        {"name": "exchange_tz", "type": "string", "unit": "IANA tz", "nullable": false, "example": "America/New_York", "priority": "P0", "description": "Exchange local timezone."},
        {"name": "instrument_id", "type": "string", "unit": null, "nullable": false, "example": "SPY-2026-07-29-P-548.00", "priority": "P0", "description": "Foreign key to contract_master.instrument_id."},
        {"name": "option_symbol", "type": "string", "unit": null, "nullable": false, "example": "SPY260729P00548000", "priority": "P1", "description": "Denormalized human-readable symbol."},
        {"name": "trade_price", "type": "decimal", "unit": "USD/share", "nullable": false, "example": 0.10, "priority": "P0", "description": "Executed price, decimal USD per share."},
        {"name": "trade_size", "type": "integer", "unit": "contracts", "nullable": false, "example": 10, "priority": "P0", "description": "Number of contracts traded."},
        {"name": "exchange", "type": "string", "unit": null, "nullable": false, "example": "CBOE", "priority": "P0", "description": "Executing venue."},
        {"name": "trade_conditions", "type": "string", "unit": null, "nullable": true, "example": "REGULAR", "priority": "P1", "description": "Condition codes (e.g. regular, late, opening, ISO)."},
        {"name": "sequence_number", "type": "integer", "unit": null, "nullable": false, "example": 5001, "priority": "P0", "description": "Monotonic per instrument/venue/day."},
        {"name": "is_correction", "type": "boolean", "unit": null, "nullable": false, "example": false, "priority": "P0", "description": "True if this print revises/cancels a prior trade."},
        {"name": "is_synthetic", "type": "boolean", "unit": null, "nullable": false, "example": true, "priority": "P0", "description": "Present only in this illustrative sample."}
      ]
    },
    {
      "id": "option_chain_snapshot",
      "name": "Option Chain Snapshot",
      "priority": "P0",
      "sample_file": "sample_chain_snapshot.csv",
      "description": "Full chain (all strikes/types for one expiration) as of a single timestamp, joined with underlying price.",
      "fields": [
        {"name": "snapshot_ts_utc", "type": "timestamp", "unit": "ISO-8601 UTC, ns", "nullable": false, "example": "2026-07-29T13:35:00.000000000Z", "priority": "P0", "description": "Point-in-time snapshot instant, shared by every row in one snapshot."},
        {"name": "exchange_tz", "type": "string", "unit": "IANA tz", "nullable": false, "example": "America/New_York", "priority": "P0", "description": "Exchange local timezone."},
        {"name": "underlying_symbol", "type": "string", "unit": null, "nullable": false, "example": "SPY", "priority": "P0", "description": "Underlying ticker."},
        {"name": "underlying_price", "type": "decimal", "unit": "USD", "nullable": false, "example": 552.47, "priority": "P0", "description": "Underlying last/mid price at snapshot_ts_utc."},
        {"name": "instrument_id", "type": "string", "unit": null, "nullable": false, "example": "SPY-2026-07-29-C-552.50", "priority": "P0", "description": "Foreign key to contract_master.instrument_id."},
        {"name": "option_symbol", "type": "string", "unit": null, "nullable": false, "example": "SPY260729C00552500", "priority": "P1", "description": "Denormalized human-readable symbol."},
        {"name": "strike_price", "type": "decimal", "unit": "USD", "nullable": false, "example": "552.50", "priority": "P0", "description": "Decimal strike."},
        {"name": "option_type", "type": "enum", "unit": null, "nullable": false, "example": "C", "priority": "P0", "description": "C or P."},
        {"name": "bid_price", "type": "decimal", "unit": "USD/share", "nullable": true, "example": 0.53, "priority": "P0", "description": "NBBO bid at snapshot instant."},
        {"name": "bid_size", "type": "integer", "unit": "contracts", "nullable": true, "example": 25, "priority": "P0", "description": "Size at bid."},
        {"name": "ask_price", "type": "decimal", "unit": "USD/share", "nullable": true, "example": 0.63, "priority": "P0", "description": "NBBO ask at snapshot instant."},
        {"name": "ask_size", "type": "integer", "unit": "contracts", "nullable": true, "example": 25, "priority": "P0", "description": "Size at ask."},
        {"name": "last_price", "type": "decimal", "unit": "USD/share", "nullable": true, "example": 0.58, "priority": "P1", "description": "Last traded price as of snapshot."},
        {"name": "volume", "type": "integer", "unit": "contracts", "nullable": false, "example": 940, "priority": "P0", "description": "Cumulative contracts traded through snapshot_ts_utc."},
        {"name": "open_interest", "type": "integer", "unit": "contracts", "nullable": false, "example": 11800, "priority": "P0", "description": "Open interest as of prior session close (or intraday estimate if flagged)."}
      ]
    },
    {
      "id": "greeks_iv",
      "name": "Greeks & Implied Volatility",
      "priority": "P0",
      "sample_file": "sample_greeks.csv",
      "description": "Per-instrument Greeks and IV with explicit model and methodology metadata.",
      "fields": [
        {"name": "as_of_ts_utc", "type": "timestamp", "unit": "ISO-8601 UTC, ns", "nullable": false, "example": "2026-07-29T13:35:00.000000000Z", "priority": "P0", "description": "Instant the Greeks/IV were computed for."},
        {"name": "exchange_tz", "type": "string", "unit": "IANA tz", "nullable": false, "example": "America/New_York", "priority": "P0", "description": "Exchange local timezone."},
        {"name": "instrument_id", "type": "string", "unit": null, "nullable": false, "example": "SPY-2026-07-29-C-552.50", "priority": "P0", "description": "Foreign key to contract_master.instrument_id."},
        {"name": "option_symbol", "type": "string", "unit": null, "nullable": false, "example": "SPY260729C00552500", "priority": "P1", "description": "Denormalized human-readable symbol."},
        {"name": "underlying_price", "type": "decimal", "unit": "USD", "nullable": false, "example": 552.47, "priority": "P0", "description": "Underlying price used as model input."},
        {"name": "implied_volatility", "type": "decimal", "unit": "annualized fraction", "nullable": true, "example": 0.150, "priority": "P0", "description": "Decimal fraction, e.g. 0.2075 = 20.75%. Never a whole-number percent."},
        {"name": "delta", "type": "decimal", "unit": "unitless", "nullable": true, "example": 0.50, "priority": "P0", "description": "Call in [0,1], put in [-1,0]."},
        {"name": "gamma", "type": "decimal", "unit": "unitless", "nullable": true, "example": 0.073, "priority": "P0", "description": ">= 0 for long options."},
        {"name": "theta", "type": "decimal", "unit": "USD/day", "nullable": true, "example": -0.28, "priority": "P0", "description": "Per-day time decay, <= 0 for long options."},
        {"name": "vega", "type": "decimal", "unit": "USD per 1.0 vol pt", "nullable": true, "example": 0.066, "priority": "P0", "description": ">= 0 for long options."},
        {"name": "rho", "type": "decimal", "unit": "USD per 1.0 rate pt", "nullable": true, "example": 0.0015, "priority": "P2", "description": "Sensitivity to risk-free rate."},
        {"name": "model", "type": "string", "unit": null, "nullable": false, "example": "black_scholes_1973_american_approx", "priority": "P0", "description": "Pricing model identifier used to compute this row."},
        {"name": "risk_free_rate_ref", "type": "string", "unit": null, "nullable": false, "example": "US_SOFR_1M", "priority": "P1", "description": "Reference rate curve/source used as model input."},
        {"name": "dividend_yield_input", "type": "decimal", "unit": "annualized fraction", "nullable": true, "example": 0.013, "priority": "P1", "description": "Dividend yield assumption fed into the model."}
      ]
    },
    {
      "id": "underlying_ohlcv",
      "name": "Underlying / Index OHLCV",
      "priority": "P0",
      "sample_file": "sample_underlying_bars.csv",
      "description": "OHLCV bars for the underlying or index, tagged with session type (regular vs extended hours).",
      "fields": [
        {"name": "bar_start_ts_utc", "type": "timestamp", "unit": "ISO-8601 UTC, ns", "nullable": false, "example": "2026-07-29T13:35:00.000000000Z", "priority": "P0", "description": "Bar open instant, UTC."},
        {"name": "bar_end_ts_utc", "type": "timestamp", "unit": "ISO-8601 UTC, ns", "nullable": false, "example": "2026-07-29T13:35:59.999999999Z", "priority": "P0", "description": "Bar close instant, UTC."},
        {"name": "exchange_tz", "type": "string", "unit": "IANA tz", "nullable": false, "example": "America/New_York", "priority": "P0", "description": "Exchange local timezone."},
        {"name": "underlying_symbol", "type": "string", "unit": null, "nullable": false, "example": "SPY", "priority": "P0", "description": "Underlying ticker or index root."},
        {"name": "open", "type": "decimal", "unit": "USD", "nullable": false, "example": 552.47, "priority": "P0", "description": "Bar open price."},
        {"name": "high", "type": "decimal", "unit": "USD", "nullable": false, "example": 552.58, "priority": "P0", "description": "Bar high price."},
        {"name": "low", "type": "decimal", "unit": "USD", "nullable": false, "example": 552.42, "priority": "P0", "description": "Bar low price."},
        {"name": "close", "type": "decimal", "unit": "USD", "nullable": false, "example": 552.52, "priority": "P0", "description": "Bar close price."},
        {"name": "volume", "type": "integer", "unit": "shares", "nullable": false, "example": 193900, "priority": "P0", "description": "Shares traded during the bar."},
        {"name": "session_flag", "type": "enum", "unit": null, "nullable": false, "example": "REGULAR", "priority": "P0", "description": "REGULAR | PRE_MARKET | AFTER_HOURS."}
      ]
    },
    {
      "id": "oi_volume_eod_settlement",
      "name": "Open Interest / Volume / EOD / Settlement",
      "priority": "P1",
      "sample_file": null,
      "sample_note": "open_interest and volume for the example snapshot are included as columns in sample_chain_snapshot.csv; a dedicated end-of-day settlement file is not part of this v1.0 draft sample set.",
      "description": "Daily end-of-day summary per instrument: official settlement price, closing OI, total volume, and settlement methodology.",
      "fields": [
        {"name": "trade_date", "type": "date", "unit": "YYYY-MM-DD", "nullable": false, "example": "2026-07-29", "priority": "P0", "description": "Exchange local trade date the summary covers."},
        {"name": "instrument_id", "type": "string", "unit": null, "nullable": false, "example": "SPY-2026-07-29-C-552.50", "priority": "P0", "description": "Foreign key to contract_master.instrument_id."},
        {"name": "settlement_price", "type": "decimal", "unit": "USD/share", "nullable": true, "example": 0.58, "priority": "P0", "description": "Official settlement/closing price used for EOD valuation."},
        {"name": "settlement_method", "type": "string", "unit": null, "nullable": false, "example": "OPRA_OFFICIAL_CLOSE", "priority": "P1", "description": "Methodology/source for the settlement price."},
        {"name": "closing_open_interest", "type": "integer", "unit": "contracts", "nullable": false, "example": 11800, "priority": "P0", "description": "Open interest as reported at end of trade_date."},
        {"name": "total_volume", "type": "integer", "unit": "contracts", "nullable": false, "example": 940, "priority": "P0", "description": "Total contracts traded during trade_date."}
      ]
    },
    {
      "id": "corporate_actions_calendar_rates",
      "name": "Corporate Actions / Calendar / Reference Rates / Dividends",
      "priority": "P1",
      "sample_file": null,
      "sample_note": "Not included as a sample file: the single-day 0DTE example has no corporate action events. Schema below defines the shape required for production ingestion.",
      "description": "Reference data needed to correctly adjust contracts and value options: splits/mergers, expiration/holiday calendars, dividend schedules, and the risk-free rate curve.",
      "fields": [
        {"name": "event_type", "type": "enum", "unit": null, "nullable": false, "example": "CASH_DIVIDEND", "priority": "P0", "description": "SPLIT | CASH_DIVIDEND | SPECIAL_DIVIDEND | MERGER | SYMBOL_CHANGE | EARLY_EXPIRATION | HOLIDAY."},
        {"name": "underlying_symbol", "type": "string", "unit": null, "nullable": false, "example": "SPY", "priority": "P0", "description": "Affected underlying."},
        {"name": "effective_date", "type": "date", "unit": "YYYY-MM-DD", "nullable": false, "example": "2026-09-19", "priority": "P0", "description": "Exchange local date the event takes effect."},
        {"name": "ex_date", "type": "date", "unit": "YYYY-MM-DD", "nullable": true, "example": "2026-09-18", "priority": "P1", "description": "Ex-dividend date, if applicable."},
        {"name": "cash_amount", "type": "decimal", "unit": "USD/share", "nullable": true, "example": 1.72, "priority": "P1", "description": "Cash dividend amount per share, if applicable."},
        {"name": "split_ratio", "type": "string", "unit": null, "nullable": true, "example": "2:1", "priority": "P1", "description": "Split/reverse-split ratio, if applicable."},
        {"name": "adjustment_factor", "type": "decimal", "unit": "unitless", "nullable": true, "example": 1.0, "priority": "P1", "description": "Multiplicative adjustment applied to historical strikes/prices."},
        {"name": "reference_rate_curve", "type": "string", "unit": null, "nullable": true, "example": "US_SOFR", "priority": "P2", "description": "Named risk-free rate curve for the affected date, when event_type is a rate update."}
      ]
    }
  ]
}