An open-source API specification and data standard for structured, queryable board game data.
Board games deserve what MusicBrainz built for music and TMDb built for film: a community-driven, standardized way to describe and query game data. OpenTabletop is that standard. It defines the data model, API contract, and controlled vocabularies -- not a database, but the blueprint that any database can implement. Think of it like SQL defines a query language while PostgreSQL and MySQL implement it, or how ActivityPub defines a federation protocol while Mastodon and Lemmy implement it. OpenTabletop defines the specification; anyone can build a conforming server with their own data.
BoardGameGeek's XML API is the de facto source for board game data, but it's showing its age: undocumented rate limits, recent authentication breakage, XML-era design, and critical missing features. Board Game Atlas -- the only real competitor -- shut down entirely. Every developer building a board game app reinvents the same wrappers, the same workarounds, the same incomplete data models.
There is no standard way to answer the question every board gamer asks:
"We have 4 people, about 90 minutes, and we want something medium-weight and cooperative -- what should we play?"
This problem isn't limited to English-speaking markets. Board game communities exist worldwide -- in Japan, Germany, Brazil, South Korea, France, China, and beyond -- each with their own data silos, their own platforms, and no interoperability between them. OpenTabletop is language-agnostic by design: games carry alternate names in any language, community data is disaggregated by population, and any regional community can run a conforming server with their own language and their own data. The standard enables a global ecosystem.
Define the vocabulary once. Games, expansions, promos, reimplementations, mechanics, categories, themes, designers, publishers -- with proper relationships, proper types, and proper schemas. Every decision recorded as an Architecture Decision Record (ADR).
The showcase feature. Compound, multi-dimensional filtering that winnows thousands of games to exactly what you want in a single query:
GET /games?players=4&community_playtime_max=90&weight_min=2.0&weight_max=3.5
&mode=cooperative&mechanics=hand-management&theme_not=space
&effective=true&sort=bayes_rating&order=desc
Six composable dimensions: player count (including expansion-modified "best at"), play time (publisher-stated vs community-reported), weight/complexity, game mode & mechanics (AND/OR/NOT), themes, and metadata. Set effective=true to filter against expansion-modified properties -- something no existing API can do.
Every opinion-based data point -- player count polls, weight votes, community play times, expansion deltas -- is stored as raw, exportable, analyzable data. Bulk export in JSON Lines and CSV. The API doesn't just serve aggregates; it serves the distributions that power them.
Expansions don't just add content -- they change how a game plays. OpenTabletop tracks this:
Spirit Island (base): 1-4 players, best@2, weight 3.9
+ Branch & Claw: 1-4 players, best@2, weight 4.0
+ Jagged Earth: 1-6 players, best@2-3, weight 4.1
+ Branch & Claw + Jagged Earth: 1-6 players, best@2-4, weight 4.2
The combination of Branch & Claw + Jagged Earth has emergent effects that differ from summing their individual deltas. The API stores explicit community-curated data for expansion combinations and falls back to computed deltas when explicit data doesn't exist.
spec/ OpenAPI 3.1 specification (source of truth)
data/
taxonomy/ Controlled vocabularies (mechanics, categories, themes)
mappings/ BGG bridge mappings for migration
samples/ Sample game data conforming to the schemas
docs/ mdbook documentation, ADRs, and pillar guides
tools/ Taxonomy viewer and utilities
scripts/ Spec bundling and ADR validation
Explore the spec interactively:
# Bundle and preview in your browser
./scripts/bundle-spec.sh
npx @redocly/cli preview-docs spec/bundled/openapi.yamlGenerate a client SDK:
# Python, TypeScript, Rust, Go, Java, and 50+ other languages
npx @openapitools/openapi-generator-cli generate \
-i spec/bundled/openapi.yaml -g python -o my-sdk/Build a conforming server: See the Implementer's Guide for the full walkthrough -- database schema, sample data loader, endpoint implementation, and conformance validation.
- Spec-first: The OpenAPI specification is the source of truth -- implementations conform to it
- ADR-driven: Every architectural decision is recorded in
docs/src/adr/ - Standards-based: OpenAPI 3.1, RFC 9457 errors, HAL-style links, keyset pagination
- Implementation-agnostic: Build your server in any language; generate SDKs from the spec
See CONTRIBUTING.md for how to:
- Propose spec changes via the RFC process
- Submit data corrections
- Contribute taxonomy data and sample records
OpenTabletop uses an RFC-based governance model. Spec changes require a formal RFC, community discussion, and steering committee approval. See docs/src/governance.md.
- Tooling and scripts: Apache License 2.0
- Specification, documentation, and data: CC-BY-4.0