Open Backtest Format (OBTF)

Status: Draft — v0.1.0-draft. The specification is not yet stable and has not yet been adopted outside its reference implementation. Field names, envelope layout, and MUST-level requirements MAY change until v1.0.0.

The Open Backtest Format (OBTF) is a versioned, engine-agnostic, studies-first on-disk format for storing the full evidence of a quantitative trading strategy's backtest results — metrics, trades, orders, portfolio snapshots, universes, cost assumptions, and Monte-Carlo significance tests — in a single self-contained file.

One .obtf file per algorithm. Portable across environments, engines (vector / event-driven / hybrid), regimes, and toolchains.

Why

Every quantitative research team ends up inventing the same thing: a directory or pickle or ad-hoc JSON dump that holds "the results of this backtest." These artefacts are not portable between engines, not comparable across teams, and not readable a year later without the exact code that produced them.

OBTF is a boring, versioned, spec'd container for those results, so that:

• Analysis tools (dashboards, notebooks, ranking pipelines, LLM agents) can consume outputs from any engine without per-engine adapters.
• Research teams can archive and share bundles across environments and framework versions.
• Engine authors (event-driven, vector, walk-forward, cross-sectional) can standardise on a common on-disk contract without giving up their internal execution model.

Non-goals

• OBTF is not a live-trading log format.
• OBTF is not a tick, bar, or market-data store — it holds the outputs of a backtest, not its inputs. 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 how metrics are computed. Sharpe ratio, drawdown, and friends are producer-defined; the format specifies only how their values are stored.

Read the spec

The specification lives under spec/. Read it in order:

• 0-overview.md — goals, non-goals, terminology, RFC-2119 language
• 1-envelope.md — magic bytes, framing, compression
• 2-data-model.md — Bundle → Study → Run → Metrics
• 3-metrics.md — per-run and summary metric catalog
• 4-blobs.md — Parquet blob extraction & the @blob reference protocol
• 5-universe-windows.md — universes, date ranges, sample_type vocabulary
• 6-execution-config.md — cost / slippage / commission / fill model shape
• 7-reader-contract.md — MUST/SHOULD for readers
• 8-writer-contract.md — MUST/SHOULD for writers
• 9-versioning.md — semver policy for the format itself
• 10-extensions.md — vendor extension namespace (x-*)

Reference implementation

The reference Python implementation currently lives inside coding-kitties/investing-algorithm-framework. It will be extracted into a standalone quantos-bundle-py package as OBTF stabilises. Conformance test vectors will live under conformance/ in this repo (TBD).

Contributing

The spec is in early draft. Small edits, typo fixes, and clarifying questions are welcome as pull requests or issues. Substantive changes should go through the change-proposal process — see GOVERNANCE.md.

Governance

OBTF is currently single-vendor-authored (QuantOS / Quant-Commons) and will transition to a multi-vendor governance structure as external implementations emerge. See GOVERNANCE.md.

License

Apache License, Version 2.0. See LICENSE.