OpenBook — the specification

The normative document defining the OpenBook standard. Version 0.3.0-draft · 2026-09-12

How to read this. This page is the technical contract. For a non-technical walkthrough see the guide. For shared names (sports, market types, segments) see the taxonomy and the id lists.

The JSON Schemas in ../schema/ are the machine-normative field definitions; where prose and schema disagree, the schema wins. Every rule here traces to a decision in ../docs/decisions.md. Keywords MUST, SHOULD, MAY are used per RFC 2119.

1. What OpenBook is

OpenBook is one shared format any publisher emits sportsbook data in, the way any transit agency publishes GTFS. It applies whenever odds that originate from a sportsbook are emitted externally — by the sportsbook itself or by a feed that carries them.

OpenBook is independent of any sportsbook, data provider or software vendor. It standardises the data contract only.

flowchart LR
  publisher[Publisher] --> feed[OpenBook feed]
  feed --> consumer[Consumer]
  feed -. names .-> source[Source of each price]

2. Conventions

3. Identifiers

Three layers. They are not interchangeable.

flowchart TB
  shared[Shared ids: sport, market type, segment, side] --> vocab[Owned by the standard]
  own[Publisher-own ids: league, fixture, participant] --> pub[Unique within that publisher]
  wiki["sameAs: Wikidata URL"] --> match[How consumers match entities across publishers]

3.1 Shared ids — the vocabularies

Sports, segments, market types and sides use ids owned by the standard, in two equivalent spellings:

Lowercase, :-separated, - inside a segment. Once published in a frozen version, never re-pointed, removed, or reassigned; only deprecated (Q35). Field names and list-values take the same promise. Deprecation is name + reason + replacement + sunset; removal from the live set only at MAJOR after the window (Q36).

Human map: ../docs/taxonomy.md. Lists: ../vocabularies/.

3.2 Publisher-own ids — the entities

Leagues, seasons, stages, fixtures, participants, players and venues carry the publisher's own id, unique within that publisher. OpenBook mints none.

3.3 Shared entity id — sameAs (Wikidata)

For leagues, participants, venues and territories, sameAs holds the Wikidata entity URL (https://www.wikidata.org/entity/Q9617) — the shared cross-publisher entity id: REQUIRED when one exists, null when it does not. A string to pin, never a runtime dependency.

3.4 External ids — identifier

Any object MAY carry identifier: a list of schema.org PropertyValue ({propertyID, value}). Optional, never canonical.

4. The hierarchy

flowchart TB
  sport[sport — shared] --> league[league — publisher-own]
  league --> season[season]
  season --> stage[stage — recursive parent]
  stage --> fixture[fixture — the priced event]
  fixture --> segment[segment — shared; slice inside the match]
  sport --> participant[participant — team or individual]
  participant --> player[player — roster membership]

• A league is any recurring competition — the Premier League, the FA Cup, the NBA Cup, the F1 World Championship — typed by competitionType. It MAY name an organizer (the NBA, UEFA, the FIA): one organizer runs several competitions.
• A participant is a team or an individual (participantType); a tennis player, an F1 driver, a golfer is a participant. It belongs to a sport, never to a league: the same team plays the league, the cup and the continental competition in one week. player exists only as roster membership.
• A stage is recursive: Champions League → Knockout (phase) → Quarter-final (round) → Leg 2 (leg); NBA → Playoffs (phase) → Conference Semifinals (round) → Game 3 (seriesGame). A fixture names its leaf stage; the chain is walked via parent.
• In Formula 1, Qualifying, Sprint and Race are three fixtures in one round; their sessions (Q1/Q2/Q3) are segments.

5. Change: everything is diff-able

• Every object and message carries sequence — a monotonic integer the publisher's server issues per feed — and dateModified.
• Push streams (§8) send changes only. Pull endpoints accept since=<sequence> and return only what changed after it. since is never a timestamp.
• A snapshot is the state as of a sequence, for initial load and recovery; a diff from zero, not a separate format.
• Field-level granularity, JSON Merge Patch (RFC 7386) semantics: a change carries the object id plus only the fields that changed; absent = unchanged; null = removed. Consumers MUST merge and MUST NOT assume a message re-sends unchanged state. JSON Patch (RFC 6902) is not an alternate change encoding (Q91).
• Odds are push-first. Publishers SHOULD deliver odds/change by push and MAY additionally offer a since= pull. market/snapshot gives a fixture's current prices for initial load and recovery.

flowchart LR
  snap[Snapshot] --> replay[Replay diffs since that sequence]
  replay --> caught[snapshotComplete]
  caught --> live[Live ticks]

Merge Patch in one line:

5.1 Delivery and recovery (Q33)

A publisher that claims Level L MUST honour all eight. These are protocol guarantees, not JSON Schema.

5.2 Feed operations (Q41, Q48, Q49)

• Live documents SHOULD declare ttl: integer seconds, GBFS (Q48). Optional on the publisher record; required on the discovery document.
• A publisher SHOULD offer one discovery URL that returns { lastUpdated, ttl, feeds: [{ name, url, kind, id, schemaUrl }] } (../schema/discovery.schema.json). Snapshot, stream, publisher-hosted API docs, and additional surfaces (MCP, plugins) are named feeds. The publisher object stays identity, not the catalog (Q49, Q56). Documents are not wrapped in a GBFS-style outer container (Q90). There is no spec-owned list of many publishers (Q94).
• A publisher MAY co-serve more than one OpenBook version at the same time (distinct URLs or topics per openbookVersion).

5.3 Additional surfaces: MCP and plugins (Q56)

OpenBook standardises the sportsbook data contract. MCP servers, Agent Plugins, and other client tooling are additional surfaces: they are advertised on the same discovery document, and they MUST NOT invent a second betting model.

• Each discovery entry SHOULD carry kind: snapshot · stream · docs · mcp · plugin. name and url stay required. kind is optional so existing catalogs remain valid; new catalogs SHOULD set it. Consumers MUST ignore unrecognised kind values (Q34, Q37).
• snapshot, stream, docs are OpenBook surfaces. docs is the publisher's own OpenAPI, AsyncAPI, or HTML (Q54).
• mcp — url MUST be that MCP server's manifest (the MCP Registry server.json, or the conventional /.well-known/mcp.json that holds the same body). Connection details (stdio, Streamable HTTP, SSE), packages, and remotes live in that document. OpenBook does not wrap MCP, does not ship MCP's schema, and does not put MCP on the change envelope or topic grammar (same rule as CloudEvents, Q52).
• plugin — url MUST be that plugin's manifest (for example an Agent Plugins plugin.json). OpenBook does not define plugin file layout.
• schemaUrl SHOULD be set on mcp and plugin entries: the URI of the schema that governs the document at url (for example the MCP Registry server schema, or the Agent Plugins plugin schema). Omit it on snapshot / stream (those validate against this spec).
• id MAY distinguish several mcp or plugin entries from one publisher.
• An MCP server or plugin that exposes OpenBook data MUST use OpenBook document shapes (the schemas in ../schema/) as the payload. Tools MAY name OpenBook object / action pairs; they MUST NOT replace market, odds, score, or grade with a parallel schema. Vendor extras stay x_-prefixed (Q37).

Two independent implementations (a producer and a consumer; not ../tools/validate.py) are required to freeze 1.0, not to ship a 0.x minor.

5.3 Monitoring a feed

The §5.1 guarantees are also the signals a consumer watches to know a feed is healthy, not only what it replays:

5a. Status: three questions, three fields

Taking a market off the board is marketStatus (suspended · closed · void). Last odds MAY stay on the document. Dropping an outcome or price from the snapshot is Merge Patch null (tombstone). Never a sentinel price (odds: "0").

flowchart TB
  subgraph fixtureStatus [Fixture]
    scheduled --> live
    live --> ended
  end
  subgraph segmentStatus [Segment]
    pending --> segLive[live]
    segLive --> down[down — terminal]
  end
  subgraph marketStatus [Market]
    open --> suspended
    open --> closed
    open --> voided[void]
  end
  ended --> down
  down --> closed

Rules: eventStatus: ended ⇒ every segment down. A market whose segment is down MUST be closed or void. A grade MAY only reference a down segment. segmentStatus: paused is halt on the field, not odds offline. A period taken off the board is a fan-out of marketStatus on markets with that segment (Q99). Prefer the affected markets; bulk only when the book took the whole period down. Progress lives on score, not on odds. There is no betting-open flag on the fixture or the segment. Graded is the grade object, not marketStatus.

Corrections without settling twice (Q31): a downed segment's status and downAt never change. A publisher correcting a result sends score/update with correction: true and a statusReason — an erratum, not a second settlement. Grades built on the old values are grade/deleted and re-issued with supersedes, pointing (basedOn) at the correction's sequence.

6. Standard facts (matching across publishers)

Every fixture MUST carry the facts below. Consumers match on sport + league (name, territory) + start time + participants (names, territories), and on Wikidata QIDs when both sides have them. role and order are facts the publisher asserts; the sign of a handicap is derived from them. A feed's presentation order is never a fact.

7. Objects

Each reference document carries openbookVersion, id, sequence, dateModified; exact types in the schemas. Catalogue objects are the fixture list. Live objects are the board that keeps moving.

7.1 Catalogue

7.2 Live

8. Streams: fixture-first, then object / action

Every message is one object and one action; topic and payload say the same thing. Topics are fixture-first so that everything about one match is a single subscription.

flowchart LR
  a[openbook] --> b[v1]
  b --> c[publisher id]
  c --> d[sport slug]
  d --> e[fixture]
  e --> f[fixture id]
  f --> g[object]
  g --> h[action]

• <action> — the JSON enum token: snapshot · create · update · delete, plus change (odds only), plus control actions snapshotComplete and heartbeat (Q46). snapshotComplete is camelCase on both topic and payload.
• <sport> — the shared slug without prefix (soccer).
• Rules (after WMO WIS2): lowercase, - inside a level, no dots, unique per level; + matches one level, # the rest; v1 bumps only on a breaking change to the grammar. Exception: <action> matches the JSON enum, so snapshotComplete is mixed-case.

The same grammar is described for tooling in asyncapi.yaml (Q42). MQTT is not required.

8.1 The change envelope

One envelope for every message (../schema/change.schema.json).

• odds/change carries its markets[] diff in changes (odds_change.schema.json).
• snapshotComplete and heartbeat carry changes: {}.
• If intermediate ticks were dropped, that envelope MUST set conflated: true (Q47).
• market/update MAY carry msgType (alert · update · cancel), reason and references[] to prior sequences, after OASIS CAP 1.2.
• A void is a market/update to void.
• A corrected grade is grade/delete + grade/create with supersedes.

9. Extensions

Publishers MAY add x_-prefixed fields for vendor-specific extras.

10. Conformance

The gate is this spec, the JSON Schemas, and the language-agnostic corpus in ../conformance/ (Q40). Valid cases MUST be accepted; invalid cases MUST be rejected. ../tools/validate.py is one runner, not a language oracle.

11. Versioning

Semantic versioning per ../VERSIONING.md. -draft marks an unfrozen version. Within a frozen major, compatibility is FULL-TRANSITIVE (Q32): minors only add optional fields; the required set does not shrink or grow. Freezing 1.0 requires two independent implementations (Q41).