0. Overview

July 26, 2026 · View on GitHub

Status: Draft — v0.1.0-draft Format name: Open Backtest Format Acronym: OBTF File extension: .obtf Media type: application/vnd.quant-commons.obtf Magic bytes: OBTF (4 bytes, ASCII — 0x4F 0x42 0x54 0x46)

Requirements language

The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in RFC 2119 and RFC 8174 when, and only when, they appear in all capitals.

Goals

OBTF is designed to be:

  • Portable — a single file that can be shared, archived, or loaded across environments, framework versions, and languages without external dependencies.
  • Self-contained — all evidence for one algorithm's backtests (metrics, trades, orders, snapshots, cost assumptions, Monte-Carlo tests, metadata) is stored together in one file.
  • Engine-agnostic — vector, event-driven, walk-forward, cross-sectional, and hybrid engines can all emit conforming bundles.
  • Studies-first — the primary organisational unit is a study (a strategy idea / signal), not a single backtest run. One bundle MAY hold multiple studies for direct side-by-side comparison.
  • Blob-friendly — large time-series metrics MAY be offloaded to Parquet blobs while keeping the main body compact and fast to read.
  • Versioned — an explicit integer format_version MUST be present in the envelope. Readers reject unknown-higher versions. Writers default to the highest version they know.
  • Forward-compatible — additive changes within a major format version MUST be safe for older readers. Unknown extension fields (x-*), unknown blob keys, and unknown model type names MUST be ignored, not rejected.

Non-goals

  • OBTF is not a live-trading log format.
  • OBTF is not a tick / bar / market-data store. Data-source references are permitted; raw market data is not.
  • OBTF is not a strategy source-code exchange format.
  • OBTF is not a query API or a data lake — it is a single-file envelope.
  • OBTF does not standardise the computation of metrics. Sharpe ratio, drawdown, and friends are producer-defined; the format specifies only how the values are stored, not how they are calculated.

Terminology

  • Bundle — a single OBTF file. One bundle corresponds to exactly one algorithm_id.
  • Algorithm ID (algorithm_id) — a producer-defined, stable, opaque string identifying the strategy code + config that produced a bundle. Producers MUST document their fingerprinting scheme in metadata["algorithm_id_scheme"].
  • Anchor — a related bundle from which the current bundle was derived (e.g. a perturbed sibling). Recorded via anchor_algorithm_id.
  • Study — a single strategy idea / signal within a bundle (e.g. "ema_cross", "in_sample_signal_sweep"). A bundle MAY hold multiple studies.
  • Run — a single execution of a strategy over one date range / window on one universe. A study holds one or more runs per engine slot.
  • Engine slot — a bucket within a study that holds runs and a pooled summary for one engine class (vector, event, or a vendor-defined type; see 10. Extensions).
  • Universe — the set of symbols, trading currency, and market context a run was evaluated on.
  • Window — a BacktestDateRange: a named start/end pair that bounds a single run.
  • Blob — a Parquet payload stored under a producer-chosen key in the bundle's top-level blobs map. Referenced from the msgpack body via {"@blob": "<key>"}.
  • Producer — the software that writes an OBTF bundle. Also called a writer.
  • Consumer — the software that reads an OBTF bundle. Also called a reader.

Document structure