One open standard for sportsbook data.

A reference model, a live wire, and controlled vocabularies — the format any sportsbook or feed emits odds in. Read it once, consume every publisher.

Read the guide Examples

v0.3.0-draft

16
JSON schemas
25+
market types
schema.org
field names
Wikidata
entity ids
CC BY 4.0
licence

How to read this site

Three tracks. Pick the one that matches how you work — the data contract itself does not change between them.

Start here

Guide

Plain language. What a publisher, a source and a fixture are. No RFC keywords. For trading, ops, product, commercial.

Shared names

Taxonomy

What a sport, segment, market type and side mean. The id lists are the computer spelling of the same lists.

Implement

Specification

The technical contract: MUST / SHOULD / MAY, schemas, streams. Tables and diagrams, still the same rules.

Who it is for

Same format whether you run a book, carry many books, or consume odds. OpenBook is the data contract, not a pricing engine.

Sportsbooks

Publish your own prices without inventing a private dump format. Keep the engine, models and pricing proprietary.

Feeds

Carry many sources in one stream. Every price names its source and how it was obtained — licensed, scraped, or derived.

Consumers

One importer for every publisher: traders, screen operators, researchers, regulators, and downstream books.

The problem it solves

Every book and feed ships odds in its own shape, so every consumer writes a bespoke integration per source, and no neutral cross-vendor market taxonomy exists. OpenBook is the shared contract — like GTFS for transit — so a publisher emits once and any consumer reads it with one importer.

Publisher-neutral

A book publishing its own odds, or a feed carrying many books' odds — same format. Every price carries its source and how it was obtained.

Live by default

Prices, scores and grades stream as diffs with a monotonic sequence — modelled on live transit feeds and MQTT, not a REST endpoint you poll.

Built on real standards

ISO 8601, ISO 4217, CLDR territories, Wikidata ids, schema.org field names, JSON Merge Patch. Nothing reinvented.

Looks like a sportsbook. Travels as data.

The live wire is fixture-first. One subscription follows a match; markets, prices and grades hang off that fixture. This board is an example, not a live feed.

Arsenal vs Chelsea
sport:soccer · fixture EVT-88213 · source pinnacle · licensed
segment:soccer:full-time · marketStatus open
MarketHomeAwayOver / Under
market:moneyline 1.90 3.80 3.40 draw
market:spread −0.5 1.95 1.91
market:total 2.5 1.95 / 1.91
openbook/v1/acme-feeds/soccer/fixture/EVT-88213/#

Two tiers

The same split GTFS uses: a durable reference layer, and a live layer of diffs that point back at it.

Reference — the catalogue

Durable, bounded objects

  • sport → league → season → stage → fixture
  • participant (teams & individuals) belong to a sport
  • market_type, segment, side — shared vocabularies
  • Publisher-own ids + standard facts + Wikidata sameAs
Live — the wire

Streamed diffs

  • odds/change — price moves, per source, with provenance
  • score/update — status, clock, scores per unit & segment
  • market/update — suspend · re-open · void
  • grade/create — the grade, once a segment is down

The live wire

One envelope for everything: object + action, a Merge-Patch changes body, and a topic that says the same thing. Fixture-first, so one subscription follows a whole match.

# subscribe to everything about one match
openbook/v1/acme-feeds/soccer/fixture/EVT-88213/#

# an odds change on that match
{
  "openbookVersion": "0.3.0-draft",
  "sequence": 104871,
  "object": "odds", "action": "change",
  "sport": "soccer", "id": "EVT-88213",
  "changes": { "markets": [{
    "marketType": "market:total",
    "segment": "segment:soccer:full-time",
    "line": 2.5,
    "source": "pinnacle", "provenance": "licensed",
    "outcomes": [{ "side": "over", "odds": 1.95 }]
  }]}
}

Controlled vocabularies

The piece no one else publishes: shared names for what can be bet and how a match is sliced. Read the taxonomy first; this list is the computer spelling.

market:moneylinemarket:spreadmarket:total market:player-pointsmarket:correct-scoremarket:outright-winner segment:soccer:1st-halfsegment:baseball:inning-1segment:tennis:set-2 side:oversport:athletics

Market types, sports and segments →

JSON Schemas

Draft 2020-12. Machine-normative for what is on the wire. Validate with python3 tools/validate.py.

change common fixture grade league market market_type odds_change participant player publisher region score season sport stage examples (raw)

Resources

Readable copies of this repo, and the standards OpenBook is shaped after. We don't mint what already exists.

This standard

What it stands on

Get started

1
Start with the guide (plain language) and the taxonomy. Implementers then read the specification and decision log.
2
Validate against the JSON Schemas (draft 2020-12): python3 tools/validate.py.
3
Map your feed in: keep your own ids, add the standard facts, attach a Wikidata sameAs where one exists.
4
Publish — a book's own odds, or a feed carrying many books. Same format either way.

Draft status. OpenBook is v0.3.0-draft — the model is settled, the wire may still change before 1.0. Issues and proposals welcome on GitHub.

Open spec, private engines

OpenBook standardises the data contract — schemas and vocabularies — and nothing else. How a book produces, models or prices its data stays entirely its own. The specification is CC BY 4.0; implementations may be fully proprietary. This is how OpenRTB, FIX and GTFS reached adoption.