Introduction

OpenTabletop is an open specification for board game data – a schema, vocabulary, and API contract that defines what a board game database should look like. Think of it as the MusicBrainz of tabletop gaming: a community-governed standard that anyone can implement with their own data. OpenTabletop is not a database. It is the blueprint for building one.

The Problem

Board game data is in a crisis:

• BoardGameGeek is the de facto monopoly on board game metadata, but its API is an undocumented XML endpoint from the mid-2000s. It is rate-limited, fragile, and missing basic capabilities like filtering by player count and play time simultaneously. There is no official documentation, no versioning, and no contract – it can change without notice. Worse, BGG does not facilitate others building on its data – no bulk exports, no interoperability, no ecosystem. The data goes in and it does not come out.
• Board Game Atlas attempted to be an alternative and then shut down entirely, taking its API and everyone’s integrations with it.
• No standard exists. Every board game app, collection tracker, and recommendation engine scrapes BGG or maintains its own ad-hoc database. There is no shared vocabulary, no common schema, no interoperability.

This is the state of the art: a single proprietary website with an XML API that was never designed to be an API, and no fallback when it goes down or changes behavior. A little competition could do the space some good – but competition requires a shared foundation to build on.

OpenTabletop exists to provide that foundation. Not by replacing BGG as a community – BGG is a great forum and review site – but by defining the specification so that multiple platforms, apps, and databases can exist, interoperate, and compete. Any developer can stand up a conforming server with their own data. Any app can consume any conforming API. The specification is the commons; the implementations are the marketplace.

Critically, the specification is language-agnostic and designed for global adoption. It does not assume English, does not assume BGG’s voter population, and does not assume a Western-centric hobby. A Japanese board game community can run a conforming server with Japanese game names, Japanese community data, and Japanese voter preferences. A German community can do the same. A Brazilian community can do the same. All of these servers speak the same API contract – an app built against any one of them works against all of them. Games carry alternate names in any language, voting data is disaggregated by community, and the taxonomy uses canonical slugs that implementations surface in their own language. The standard enables a global ecosystem where regional communities maintain their own data while remaining interoperable.

The Three Pillars

The project is organized around three pillars, each solving a distinct part of the problem:

Pillar 1: Standardized Data Model

A rigorous, relational data model for board games and everything associated with them. Games, expansions, designers, publishers, mechanics, categories, player counts, play times, complexity weights – all with well-defined types, relationships, and identifiers.

The data model handles the hard problems: an expansion that changes the player count of its base game. A standalone expansion that is both its own game and part of a family. A reimplementation that shares mechanics but is a distinct product.

Pillar 2: Filtering & Windowing

The ability to ask real questions of the data. Not just “show me Catan” but “show me cooperative games for exactly 4 players that play in under 90 minutes at medium weight, excluding space-themed games.” Six orthogonal filter dimensions that compose with boolean logic across hundreds of thousands of games.

This is the feature that does not exist anywhere today. BGG has no multi-dimensional filter. No board game service lets you query by effective player count with expansions included. The OpenTabletop specification makes this possible.

Pillar 3: Statistical Foundation

Board game data is rich – millions of ratings, weight votes, player count polls accumulated over two decades – but today it is locked inside formats that make real analysis impossible. BGG’s “top games” rankings, weight scores, and player count recommendations are black boxes: you get a single number, not the underlying data. No data scientist, analyst, or statistician can do meaningful work with an undocumented XML endpoint that returns a pre-computed average.

OpenTabletop specifies data structures built for analysis. Player count polls are stored as per-count vote distributions, not a min/max range. Weight is a full vote distribution, not a single number. Community play times are statistical distributions with percentiles, not a box estimate. A conforming data source gives researchers actual material to work with: alternative ranking algorithms, trend analysis over time, complexity studies, recommendation engines – all become possible when the data is structured for analysis from the ground up.

A Taste of What This Enables

Imagine it is game night. You have 4 people, about 90 minutes, and your group prefers medium-weight strategy games. You own Ticket to Ride: Europe with the Europa 1912 expansion. One person does not like horror themes.

With a conforming OpenTabletop server, this is a single API call:

POST /games/search HTTP/1.1
Content-Type: application/json

{
  "players": 4,
  "playtime_max": 90,
  "weight_min": 2.0,
  "weight_max": 3.5,
  "mechanics": ["route-building"],
  "theme_not": ["horror"],
  "effective": true,
  "sort": "rating_desc",
  "limit": 20
}

The effective: true flag means the search considers expansion combinations. Ticket to Ride: Europe’s box says 30-60 minutes, but community-reported play times for 4 players with Europa 1912’s expanded ticket set average closer to 70 minutes – still under the 90-minute cap. A conforming server knows this because the data model tracks how expansions modify effective play time. It uses community-reported times, not the publisher’s box estimate, so the results reflect how the game plays for the community of players who log their sessions – often a closer match to your experience than publisher estimates, especially for experienced groups.

No other board game API can answer this query today.

Where OpenTabletop Fits

OpenTabletop is a specification, not a database. This is an important distinction. MusicBrainz is both a standard and a hosted database – it defines what music metadata looks like and operates the canonical instance. OpenTabletop defines only the standard. Anyone can build and host a conforming implementation with their own data, their own community, and their own infrastructure.

This follows a pattern that has worked across the software industry:

The pattern is always the same: define the interface, let implementations compete on quality. The standard creates interoperability – an app built against one conforming server works against any other. The implementations create value – different communities can curate their own data, optimize for their own audience, and still speak the same language.

This is why the project ships schemas, vocabularies, and sample data rather than a running server. The specification is the product. A Japanese board game community, a German hobbyist database, a university research project, and a commercial collection tracker can all implement the same spec and produce interoperable data. The standard is the commons; the implementations are the marketplace.

Project Status

OpenTabletop is in the specification phase. The project is defining:

1. The OpenAPI 3.2 specification document – the canonical source of truth
2. This documentation, which explains the design rationale and data model
3. Architecture Decision Records (ADRs) that capture key choices
4. A governance model for community-driven evolution

The project provides schemas, controlled vocabularies, sample data, and implementer guidance – everything a developer needs to build a conforming server or client in the language of their choice.

The specification is developed in the open under dual licensing: Apache 2.0 for code, CC-BY-4.0 for the specification and documentation. Contributions are welcome – see the Governance Model and Getting Started guide.

Pillar 1: Standardized Data Model

The data model is the foundation of OpenTabletop. It defines every entity, relationship, and data type in the specification. The goal is a schema rigorous enough for a relational database, expressive enough to capture the full complexity of board game metadata, and stable enough that implementations can rely on it for years.

Entity-Relationship Overview

erDiagram
    Game ||--o{ GameRelationship : "source"
    Game ||--o{ GameRelationship : "target"
    Game }o--o{ Mechanic : "has"
    Game }o--o{ Category : "belongs to"
    Game }o--o{ Theme : "themed as"
    Game }o--o{ Family : "part of"
    Game }o--o{ Person : "designed/illustrated by"
    Game }o--o{ Organization : "published by"
    Game ||--o{ PlayerCountPoll : "has votes"
    Game ||--o{ PropertyModification : "modified by"
    Game ||--o{ Identifier : "known as"

    GameRelationship {
        uuid id
        uuid source_game_id
        uuid target_game_id
        enum relationship_type
    }

    Game {
        uuid id
        string slug
        string name
        enum type
        int year_published
        int min_players
        int max_players
        int min_playtime
        int max_playtime
        int community_min_playtime
        int community_max_playtime
        float weight
        float rating
    }

    Person {
        uuid id
        string slug
        string name
        enum role
    }

    Organization {
        uuid id
        string slug
        string name
        enum type
    }

    Mechanic {
        uuid id
        string slug
        string name
    }

    Category {
        uuid id
        string slug
        string name
    }

    Theme {
        uuid id
        string slug
        string name
    }

    Family {
        uuid id
        string slug
        string name
    }

    PlayerCountPoll {
        uuid game_id
        int player_count
        int best_votes
        int recommended_votes
        int not_recommended_votes
    }

    PropertyModification {
        uuid id
        uuid expansion_id
        uuid base_game_id
        string property
        string modification_type
        string value
    }

    Identifier {
        uuid game_id
        string source
        string external_id
    }

    ExpansionCombination {
        uuid id
        uuid base_game_id
        int min_players
        int max_players
        int min_playtime
        int max_playtime
        float weight
    }

    Game ||--o{ ExpansionCombination : "effective with"
    ExpansionCombination }o--o{ Game : "includes expansions"

Entity Summary

Design Principles

Explicit over implicit. Every relationship is a first-class entity with a type discriminator, not an implied association.

Dual-source data. Wherever community perceptions differ from publisher-stated values, both are captured. Publisher-stated play time and community-reported play time are separate fields, not averaged into one. Both sources carry their own biases – see Data Provenance & Bias.

Combinatorial awareness. The data model does not just store “this expansion exists.” It stores how that expansion changes the base game’s properties, and it supports pre-computed combinations for sets of expansions. This is what makes effective mode filtering possible.

Controlled vocabulary with governance. Mechanics, categories, and themes are not free-text tags. They are managed terms with slugs, definitions, and an RFC process for additions. This prevents the fragmentation problem where “deck building” and “deckbuilding” and “deck-building” are three different tags.

Stable identifiers. Every entity has a UUIDv7 (time-sortable, globally unique) and a human-readable slug. External cross-references (BGG IDs, etc.) are stored as structured Identifier entities, not ad-hoc fields.

Game Entity

The Game entity is the core of the data model. Every board game, expansion, promo, and accessory is represented as a Game with a type discriminator that indicates its role.

Fields

Type Discriminator

The type field classifies what kind of product this Game represents:

For detailed classification criteria, decision trees, and grey zone rules, see Entity Type Criteria.

Type Hierarchy

flowchart TD
    G[Game Entity]
    G --> BG[base_game]
    G --> EX[expansion]
    G --> SE[standalone_expansion]
    G --> PR[promo]
    G --> AC[accessory]
    G --> FE[fan_expansion]

    BG -.- note1["Playable alone"]
    EX -.- note2["Requires a base game"]
    SE -.- note3["Playable alone AND part of a family"]
    PR -.- note4["Small add-on, usually a single component"]
    AC -.- note5["Non-gameplay product"]
    FE -.- note6["Community-created, unofficial"]

Dual Playtime Fields

The Game entity carries two sets of playtime fields, reflecting the reality that publisher estimates and actual play times often diverge significantly:

• min_playtime / max_playtime: What the publisher prints on the box. These tend to be optimistic and assume experienced players. A game listed as “60-90 minutes” often takes 120+ minutes for a first play.
• community_min_playtime / community_max_playtime: Derived from community-reported play logs. These reflect what players actually experience. See Play Time Model for details on how these are computed.

Both sets of fields are available for filtering. The playtime_source filter parameter controls which set is used. See Filter Dimensions.

Weight and Rating

Weight is a community-voted measure of complexity on a 1.0 to 5.0 scale:

The weight_votes field indicates how many community members contributed to the weight score. A weight of 3.5 with 5,000 votes is far more reliable than 3.5 with 12 votes.

Rating is a community average on a 1.0 to 10.0 scale, with rating_votes tracking the sample size. The specification does not define a Bayesian average or geek rating equivalent – those are derived values that belong in application logic, not the data model. The raw average and vote count are the source data.

Example

{
  "id": "01967b3c-5a00-7000-8000-000000000001",
  "slug": "spirit-island",
  "name": "Spirit Island",
  "type": "base_game",
  "description": "Powerful spirits have existed on this island...",
  "year_published": 2017,
  "min_players": 1,
  "max_players": 4,
  "min_playtime": 90,
  "max_playtime": 120,
  "community_min_playtime": 90,
  "community_max_playtime": 150,
  "weight": 3.89,
  "weight_votes": 5127,
  "rating": 8.31,
  "rating_votes": 42891,
  "image_url": "https://example.com/images/spirit-island.jpg",
  "thumbnail_url": "https://example.com/images/spirit-island-thumb.jpg",
  "created_at": "2026-01-15T10:00:00Z",
  "updated_at": "2026-03-01T14:30:00Z"
}

Game Relationships

Games do not exist in isolation. An expansion extends a base game. A reimplementation shares mechanics with its predecessor. A big-box edition contains multiple products. The GameRelationship entity captures these connections as typed, directed edges.

GameRelationship Entity

Relationship Types

Directionality

All relationships are stored as directed edges from source_game_id to target_game_id. For symmetric relationships like integrates_with, both directions are stored:

• Star Realms -> integrates_with -> Star Realms: Colony Wars
• Star Realms: Colony Wars -> integrates_with -> Star Realms

This allows querying from either side without special-casing.

Case Study: The Spirit Island Family Tree

Spirit Island is an excellent example of the relationship model’s expressiveness. It has standard expansions, a standalone expansion, and dependency chains:

flowchart TD
    SI["Spirit Island<br/><i>base_game</i>"]

    BC["Branch & Claw<br/><i>expansion</i>"]
    JE["Jagged Earth<br/><i>expansion</i>"]
    NI["Nature Incarnate<br/><i>expansion</i>"]
    HSI["Horizons of Spirit Island<br/><i>standalone_expansion</i>"]

    P1["Promo Pack 1<br/><i>promo</i>"]
    P2["Promo Pack 2<br/><i>promo</i>"]
    FF["Feather & Flame<br/><i>compilation</i>"]

    BC -->|expands| SI
    JE -->|expands| SI
    NI -->|expands| SI
    P1 -->|expands| SI
    P2 -->|expands| SI
    FF -->|expands| SI
    FF -->|contains| P1
    FF -->|contains| P2

    HSI -.->|integrates_with| SI

    style SI fill:#1976d2,color:#fff
    style HSI fill:#7b1fa2,color:#fff
    style BC fill:#388e3c,color:#fff
    style JE fill:#388e3c,color:#fff
    style NI fill:#388e3c,color:#fff
    style P1 fill:#f57c00,color:#fff
    style P2 fill:#f57c00,color:#fff
    style FF fill:#e65100,color:#fff

Key observations from this graph:

• Branch & Claw, Jagged Earth, and Nature Incarnate are expansion type games with expands relationships pointing to Spirit Island. They require the base game.
• Horizons of Spirit Island is a standalone_expansion. It has an integrates_with relationship to Spirit Island (bidirectional) but does not have an expands relationship, because it does not require the base game.
• Promo Packs are promo type games with expands relationships. They add individual spirits or scenarios. Feather & Flame is a compilation that contains both Promo Pack 1 and Promo Pack 2 – the individual packs were difficult to obtain, so they were re-released as a single product. It also expands Spirit Island directly.

Querying Relationships

Get all expansions for a game

GET /games/spirit-island/relationships?type=expands&direction=inbound

Returns all games where target_game_id is Spirit Island and relationship_type is expands – i.e., everything that expands Spirit Island.

{
  "data": [
    {
      "source_game_id": "01912f4c-7e3a-7b1a-8c5d-9f0e1a2b3c4d",
      "target_game_id": "01912f4c-8a2b-7c3d-9e4f-0a1b2c3d4e5f",
      "relationship_type": "expands",
      "metadata": {
        "adds_spirits": 2,
        "adds_power_cards": 22
      },
      "_links": {
        "source": { "href": "/games/spirit-island", "title": "Spirit Island" },
        "target": { "href": "/games/spirit-island-branch-and-claw", "title": "Spirit Island: Branch & Claw" }
      }
    },
    {
      "source_game_id": "01912f4c-7e3a-7b1a-8c5d-9f0e1a2b3c4d",
      "target_game_id": "01912f4c-9b3c-7d4e-af5a-1b2c3d4e5f6a",
      "relationship_type": "expands",
      "metadata": {
        "adds_spirits": 10,
        "adds_power_cards": 52
      },
      "_links": {
        "source": { "href": "/games/spirit-island", "title": "Spirit Island" },
        "target": { "href": "/games/spirit-island-jagged-earth", "title": "Spirit Island: Jagged Earth" }
      }
    },
    // ... Nature Incarnate, Promo Pack 1, Promo Pack 2, Feather & Flame
  ],
  "_links": {
    "self": { "href": "/games/spirit-island/relationships?type=expands&direction=inbound" }
  }
}

Get the full family tree

GET /games/spirit-island/relationships?depth=2

Returns all relationships within 2 hops of Spirit Island, enabling reconstruction of the full family graph.

{
  "data": [
    {
      "source_game_id": "01912f4c-7e3a-7b1a-8c5d-9f0e1a2b3c4d",
      "target_game_id": "01912f4c-8a2b-7c3d-9e4f-0a1b2c3d4e5f",
      "relationship_type": "expands",
      "_links": {
        "source": { "href": "/games/spirit-island", "title": "Spirit Island" },
        "target": { "href": "/games/spirit-island-branch-and-claw", "title": "Spirit Island: Branch & Claw" }
      }
    },
    // ... other expands relationships ...
    {
      "source_game_id": "01912f4c-7e3a-7b1a-8c5d-9f0e1a2b3c4d",
      "target_game_id": "01912f4c-bd5e-7f6a-cb7c-3d4e5f6a7b8c",
      "relationship_type": "integrates_with",
      "_links": {
        "source": { "href": "/games/spirit-island", "title": "Spirit Island" },
        "target": { "href": "/games/horizons-of-spirit-island", "title": "Horizons of Spirit Island" }
      }
    },
    {
      "source_game_id": "01912f4c-ea8b-7c9d-fe0f-6a7b8c9d0e1f",
      "target_game_id": "01912f4c-ce6f-7a7b-dc8d-4e5f6a7b8c9d",
      "relationship_type": "contains",
      "_links": {
        "source": { "href": "/games/spirit-island-feather-and-flame", "title": "Spirit Island: Feather & Flame" },
        "target": { "href": "/games/spirit-island-promo-pack-1", "title": "Spirit Island: Promo Pack 1" }
      }
    },
    // ... depth=2 traversal includes relationships of related games
  ],
  "_links": {
    "self": { "href": "/games/spirit-island/relationships?depth=2" }
  }
}

Get what a game requires

GET /games/spirit-island-branch-and-claw/relationships?type=expands&direction=outbound

Returns the single relationship: Branch & Claw expands Spirit Island.

{
  "data": [
    {
      "source_game_id": "01912f4c-8a2b-7c3d-9e4f-0a1b2c3d4e5f",
      "target_game_id": "01912f4c-7e3a-7b1a-8c5d-9f0e1a2b3c4d",
      "relationship_type": "expands",
      "metadata": {
        "adds_spirits": 2,
        "adds_power_cards": 22
      },
      "_links": {
        "source": { "href": "/games/spirit-island-branch-and-claw", "title": "Spirit Island: Branch & Claw" },
        "target": { "href": "/games/spirit-island", "title": "Spirit Island" }
      }
    }
  ],
  "_links": {
    "self": { "href": "/games/spirit-island-branch-and-claw/relationships?type=expands&direction=outbound" }
  }
}

Case Study: Brass Reimplementations

Reimplementation captures when a game is rebuilt with significant changes but shares a lineage. The Brass family spans nearly two decades:

flowchart LR
    B["Brass<br/><i>(2007)</i>"]
    AI["Age of Industry<br/><i>(2010)</i>"]
    BL["Brass: Lancashire<br/><i>(2018)</i>"]
    BB["Brass: Birmingham<br/><i>(2018)</i>"]
    BP["Brass: Pittsburgh<br/><i>(2026)</i>"]

    AI -->|reimplements| B
    BL -->|reimplements| B
    BB -->|reimplements| B
    BP -.->|reimplements| B

    style B fill:#757575,color:#fff
    style AI fill:#43a047,color:#fff
    style BL fill:#1976d2,color:#fff
    style BB fill:#1976d2,color:#fff
    style BP fill:#1976d2,stroke-dasharray: 5 5

Key observations from this graph:

• Brass (2007) – Martin Wallace’s original design, set in Lancashire during the Industrial Revolution. All subsequent entries reimplement this game.
• Age of Industry (2010) – Wallace’s own abstracted reimplementation with variable maps, predating the 2018 relaunch. A distinct design direction (green) from the later Roxley series.
• Brass: Lancashire (2018) – a refined re-release of the original Brass by Roxley Games. Same Lancashire setting, updated rules and art. Despite sharing a setting with the 2007 original, it is a distinct game entry with a reimplements relationship.
• Brass: Birmingham (2018) – a new map with distinct economic strategies, also by Roxley. Paired with Lancashire as the 2018 relaunch.
• Brass: Pittsburgh (2026) – upcoming entry in the Roxley series (dashed arrow indicates unreleased).

All five are distinct games linked by reimplements, capturing mechanical lineage without implying compatibility or dependency.

Why not treat these as versions of one game? On BoardGameGeek, the original Brass (2007) has no separate entry – it exists only as a “Version” under Brass: Lancashire. This collapses a meaningful design distinction: the 2007 and 2018 games have different rules, different component sets, and different ratings communities. OpenTabletop models them as separate game entities connected by reimplements, preserving the historical lineage while keeping each game’s data (ratings, polls, weight) independent.

Property Deltas & Combinations

Expansions do not just add content – they change the properties of the base game. Invaders from Afar does not just add factions to Scythe; it raises the maximum player count from 5 to 7, extends play time at higher counts, and nudges the complexity weight upward with two new asymmetric factions. The property delta system captures these changes as structured, queryable data.

This is what makes effective mode filtering possible. Without it, you could only filter games by their base properties. With it, you can ask “what games support 6 players when I include expansions?” and get answers.

Three Layers of Data

Layer 0: Edition Deltas

Before expansion deltas are considered, the system accounts for edition differences. The same game may exist in multiple printings or editions – a revised edition might change the player count, adjust component counts that affect play time, or rebalance mechanics that shift the complexity weight. Edition deltas capture these differences relative to the canonical edition (the reference edition whose properties match the Game entity’s top-level values).

Key properties of edition deltas:

• Applied before expansion deltas in the resolution pipeline. The edition provides the adjusted base that expansions then modify.
• One edition at a time – unlike expansions, there is no combinatorial explosion. A game session uses exactly one edition.
• Deltas are relative to the canonical edition. If the 2017 first printing is canonical and the 2020 revised edition changes max play time from 120 to 90 minutes, the delta is -30 minutes.
• Optional. Many games have only one edition or no tracked edition differences. When no edition data exists, the canonical (top-level) properties are used directly.

The is_canonical flag on GameEdition marks which edition’s properties match the Game entity’s top-level values. The EditionDelta schema captures the property differences for non-canonical editions. See ADR-0035 for the full design rationale.

Layer 1: PropertyModification (Individual Deltas)

A PropertyModification records how a single expansion changes a single property of its base game.

Modification types:

• set – Replace the property value entirely. “Max players becomes 6.”
• add – Add to the existing value. “Max playtime increases by 30 minutes.”
• multiply – Multiply the existing value. Used rarely, mainly for scaling factors.

Layer 2: ExpansionCombination (Expansion Set-Level Effects)

An ExpansionCombination records the effective properties when a specific set of expansions is combined with a base game. This handles non-linear interactions: adding Invaders from Afar and The Rise of Fenris together does not simply stack their individual deltas. The combination has its own tested, community-verified properties.

Three-Tier Resolution

When the system needs to determine the effective properties of a base game with a set of expansions, it follows a three-tier resolution strategy:

flowchart TD
    Q["Query: Scythe + Invaders from Afar + The Rise of Fenris"]
    T1{"Explicit<br/>ExpansionCombination<br/>exists?"}
    T2{"Individual<br/>PropertyModifications<br/>exist?"}
    T3["Fall back to<br/>base game properties"]

    Q --> T1
    T1 -->|Yes| R1["Use ExpansionCombination<br/>properties directly"]
    T1 -->|No| T2
    T2 -->|Yes| R2["Apply delta sum:<br/>base + sum of deltas"]
    T2 -->|No| T3

    R1 -.- N1["Highest confidence.<br/>Community-verified data<br/>for this exact combo."]
    R2 -.- N2["Medium confidence.<br/>Assumes deltas stack<br/>linearly."]
    T3 -.- N3["Lowest confidence.<br/>Expansion effects<br/>unknown."]

    style R1 fill:#388e3c,color:#fff
    style R2 fill:#f57c00,color:#fff
    style T3 fill:#d32f2f,color:#fff

Tier 1: Explicit combination. If an ExpansionCombination record exists for exactly this set of expansions with this base game, use its properties. This is the most accurate: someone has verified “Scythe + IFA + Fenris supports 1-7 players at weight 3.52.”

Tier 2: Delta sum. If no explicit combination exists but individual PropertyModification records exist for each expansion, sum the deltas. For set modifications, the last one wins (by expansion release date). For add modifications, sum the values. This is a reasonable approximation but may not capture non-linear interactions.

Tier 3: Base fallback. If no modification data exists at all, use the base game’s properties unchanged. The expansion’s effects are simply unknown.

The API response includes a resolution_tier field so consumers know the confidence level of the effective properties they received.

Scythe: Full Worked Example

Here is the complete property delta data for Scythe and its expansions:

Base Game Properties

Individual PropertyModifications

Invaders from Afar (2016):

The Wind Gambit (2017):

The Rise of Fenris (2018):

Fenris does not change player count (still 1-5). It restructures the game into an 8-episode campaign and lowers the recommended age from 14+ to 12+ – the campaign’s guided structure makes the game more accessible to younger players. Its BGG weight (3.42) is slightly lower than the base game (3.45), following the same bias pattern as other expansions.

Encounters (2018):

Encounters replaces combat events with a deck of narrative encounter cards. Its BGG weight of 2.71 reflects the encounter card content rated in isolation. Additional PropertyModifications may apply but are omitted here for brevity.

Scythe also has 14 promo packs that add factions, encounters, and modules. These are omitted from this worked example – the four major expansions above are sufficient to demonstrate the property delta system.

Why are all expansion weights lower than the base game? Every Scythe expansion has a lower BGG weight than the base game (3.45): Invaders from Afar is 3.44, The Wind Gambit is 3.41, Fenris is 3.42, and Encounters is 2.71. This does not mean expansions simplify the game. It reflects selection bias – the people who rate expansion weights on BGG are experienced players who have already internalized the base game’s complexity. They rate the marginal difficulty the expansion adds from their veteran perspective, not the total combined experience a new player would face. This is why explicit ExpansionCombination records are valuable: they capture the curated, community-verified complexity of the combined experience rather than relying on individually biased ratings that undercount total weight.

ExpansionCombinations (Explicit)

Scythe + Invaders from Afar:

Scythe + The Wind Gambit:

Scythe + The Rise of Fenris:

Scythe + Invaders from Afar + The Wind Gambit:

Scythe + Invaders from Afar + The Rise of Fenris:

Scythe + Invaders from Afar + The Wind Gambit + The Rise of Fenris:

Notice how multi-expansion combinations produce different results than summing individual deltas. The top_at list with Fenris includes 3 players – something no individual expansion achieves, because the campaign structure is particularly engaging at smaller counts. The Wind Gambit’s reduced min_playtime of 70 minutes persists through combinations – airship abilities that accelerate the endgame work regardless of other expansions present. And the weight with all major expansions reaches 3.55, above any individual expansion’s weight, reflecting the cumulative cognitive load of managing factions, airships, and campaign modules simultaneously. These non-linear effects are why explicit ExpansionCombination records exist.

Resolution in Action

If someone queries “Scythe + Invaders from Afar + The Rise of Fenris”:

1. Check for an explicit ExpansionCombination with exactly {IFA, Fenris}. It exists with weight 3.52, 1-7 players, 75-150 min. Tier 1.

If instead someone queries “Scythe + Invaders from Afar + The Rise of Fenris + Encounters”:

1. Check for an explicit ExpansionCombination with exactly {IFA, Fenris, Encounters}. None exists.
2. Encounters has PropertyModification records (max_players: set 7, min_playtime: set 90). Apply delta sum: max_players remains 7 (already set by IFA), min_playtime remains 75 (Fenris sets it lower than Encounters’ 90). Tier 2 – the result is a reasonable approximation, but non-linear interactions between the three expansions are not captured.

Data Quality

Property delta data is community-contributed and curated. The specification defines the schema; the data itself comes from:

• Publisher information (max player count with an expansion is often printed on the box)
• Community play reports (play time with expansions)
• Community voting (weight with expansions)
• Curator verification (explicit combination records reviewed by maintainers)

The resolution_tier field in API responses provides transparency about data quality, letting consumers decide how much to trust effective-mode results.

Taxonomy

Board game metadata relies on three classification vocabularies: mechanics, categories, and themes. These are controlled vocabularies – curated lists of terms with stable identifiers, not free-text tags. A game is tagged with zero or more entries from each vocabulary through many-to-many join relationships.

Why Controlled Vocabularies

The board game community has a fragmentation problem. “Deck building” and “deckbuilding” and “deck-building” and “Deck Building” are four different tags on various platforms, all meaning the same thing. Free-text tagging guarantees this kind of drift. Controlled vocabularies prevent it by defining each term exactly once with a canonical slug.

Every taxonomy term has:

Mechanics

A mechanic describes how you interact with the game – the systems and structures that create the gameplay experience. These are objective, observable features of a game’s design.

Examples:

Mechanics can be hierarchical. deck-building might have children like pool-building (a variant using tokens instead of cards) and bag-building (drawing from a bag instead of a deck).

Categories

A category describes what kind of experience the game provides – its genre classification. Categories are more subjective than mechanics but still follow defined criteria.

Examples:

Themes

A theme describes the setting or subject matter of the game – its narrative and aesthetic wrapper. Themes are the most subjective vocabulary but still benefit from controlled terms.

Examples:

Families

A family groups games that share a brand, universe, or lineage but are not necessarily related by GameRelationship edges. Families are looser than relationships – they capture “these games are part of the same franchise” without implying mechanical dependency.

Examples:

A game can belong to multiple families. Pandemic Legacy: Season 1 belongs to both pandemic and legacy-games.

RFC Process for New Terms

Adding a new mechanic, category, or theme is a specification change. It follows the RFC governance process:

1. Proposal. A contributor submits an RFC with the proposed term, slug, name, description, and justification. The RFC must explain why the term is not covered by existing vocabulary and provide at least three published games that would use it.

2. Discussion. The RFC is open for community comment for a minimum of 14 days. Feedback focuses on whether the term is distinct enough, whether the name is clear, and whether the proposed slug follows conventions.

3. Decision. The BDFL (or steering committee, after transition) approves, requests changes, or rejects the RFC. Approved terms are added to the next minor version of the specification.

4. Aliasing. If an existing term is found to be ambiguous or too broad, it can be deprecated and split into more specific terms. The old slug becomes an alias that maps to the new terms, preserving backward compatibility.

Slug Conventions

• Lowercase, hyphen-separated: deck-building, not deckBuilding or deck_building
• Canonical slugs use the most common English term: cooperative, not co-operative
• Avoid abbreviations unless universally understood: rpg is acceptable, wrkr-plcmnt is not
• Maximum 50 characters

Canonical English slugs serve as interoperability keys – they ensure that a Japanese implementation and a German implementation refer to the same mechanic with the same identifier. Implementations surface these slugs to users in their own language via display names and translations: the slug worker-placement is the API key, but the UI shows “ワーカープレイスメント” in Japanese or “Arbeiterplatzierung” in German. The slug is for machines; the display name is for humans.

Taxonomy Classification Criteria

This document provides the decision framework for classifying game attributes into the three OpenTabletop vocabulary types: mechanics, categories, and themes. Use this guide when proposing taxonomy additions via RFC, reviewing contributions, or importing data from external sources.

The Three Vocabulary Types

Decision Tree

Use this flowchart when classifying a proposed term:

flowchart TD
    START["Does this term describe<br/>HOW you interact with the game?"]
    START -->|Yes| OBS["Is it an observable, objective<br/>system or rule mechanism?"]
    START -->|No| WHAT["Does it describe WHAT<br/>the game is about?<br/>(setting, subject, tone)"]

    OBS -->|Yes| MECH["✅ MECHANIC<br/>(e.g., worker placement,<br/>dice rolling, auction)"]
    OBS -->|No| DESIGN["Is it a design philosophy<br/>or genre classification?"]

    DESIGN -->|Yes| CAT["✅ CATEGORY<br/>(e.g., euro, ameritrash,<br/>party game)"]
    DESIGN -->|No| REEVAL["⚠️ Re-evaluate --<br/>may be too vague<br/>for the taxonomy"]

    WHAT -->|Yes| THEME["✅ THEME<br/>(e.g., fantasy, pirates,<br/>trains, horror)"]
    WHAT -->|No| EXPTYPE["Does it describe WHAT KIND<br/>of experience the game provides?"]

    EXPTYPE -->|Yes| CAT2["✅ CATEGORY<br/>(e.g., cooperative,<br/>legacy, campaign)"]
    EXPTYPE -->|No| META["❌ Does not belong in taxonomy<br/>-- may be game metadata<br/>(publisher, year, component list)"]

Worked Examples

Clear cases

• “Deck building” – You physically build a deck during play. Observable system with specific rules. -> Mechanic.
• “Euro” – Describes a cluster of design choices (low luck, indirect conflict, resource conversion). Not a single mechanism. -> Category.
• “Fantasy” – Describes the setting. -> Theme.
• “Trains” – What the game is about. -> Theme.
• “Party game” – What kind of experience (large group, social, quick). -> Category.

Grey zone cases

• “Cooperative” – This is both a mechanic AND a category. The mechanic cooperative describes the system (shared win condition, game-as-opponent). The category cooperative-game describes the experience type (playing together). Both entries exist with distinct definitions and distinct slugs (cooperative vs cooperative-game).

• “Legacy” – Both a mechanic and a category. The mechanic legacy describes the system (permanent component modification). The category legacy-game describes the format (finite lifecycle, sealed content). Both entries exist.

• “Horror” – A theme, not a category. “Horror” describes what the game is about (dark, frightening setting), not what kind of experience it provides. A worker-placement game about haunted houses is still a euro with a horror theme, not a “horror game” in the categorical sense.

• “Miniatures” – A theme describing a component-centric hobby aspect, not a mechanic (miniatures don’t change how you play) and not a category (miniatures games span all design philosophies).

Grey Zone Rules

When a term sits at a boundary between vocabulary types:

1. Both mechanic and category: Acceptable when the mechanic describes a system and the category describes an experience. Use distinct slugs and definitions. The mechanic entry goes in mechanics.yaml; the category entry goes in categories.yaml. Cross-reference in definitions.

2. Category vs. theme boundary: Prefer theme unless the term describes a distinct design philosophy with defining mechanical characteristics. “Fantasy” is a theme (setting). “Euro” is a category (design philosophy). “Dungeon crawler” is a category (distinct gameplay loop with defining characteristics).

3. Components are not mechanics: “Cards,” “dice,” and “miniatures” are components. “Card drafting,” “dice rolling,” and “measurement movement” are mechanics – they describe how you use those components.

4. Scale test: A proposed term must apply to at least 10 published games to warrant inclusion in the controlled vocabulary. Narrower terms belong in game-level metadata, not the taxonomy.

5. Overlap test: If a proposed term cannot be distinguished from an existing term in one sentence, it should be merged with the existing term (possibly as a synonym).

Weight Scale Calibration

The OpenTabletop weight scale ranges from 1.0 to 5.0 and is anchored to reference games as comparative examples. Weight is a community perception of rules complexity and strategic depth – not an intrinsic property of the game and not a measure of game quality. The same game may be perceived as lighter by experienced players and heavier by newcomers. See Data Provenance & Bias for a deeper discussion of why all community metrics are population-dependent.

Calibration rule: When assigning weight, find the two anchor games that bracket the target game’s perceived complexity. The weight should fall between those anchors. Cross-reference with BGG’s community weight rating – significant divergence (>0.5) is worth investigating, as it may indicate a different voter population, a genuinely unusual game, or that the anchor comparison is misleading for this particular design.

RFC Reviewer Checklist

When evaluating a proposed taxonomy addition:

• Decision tree: Does the term pass the mechanic/category/theme flowchart?
• Scale test: Does it apply to 10+ published games?
• Overlap test: Is it distinguishable from existing terms in one sentence?
• Slug format: Lowercase, hyphenated, max 50 characters?
• Definition: Precise enough to distinguish from related terms?
• Examples: At least 3 canonical examples provided?
• BGG mapping: BGG IDs provided if a mapping exists?
• Cross-vocabulary check: If it exists in another vocabulary type (mechanic vs. category), are both entries justified with distinct definitions?

Entity Type Classification Criteria

This document provides the decision framework for classifying board game products into the six OpenTabletop entity types and for determining when a product should be a new entity versus an edition of an existing one. Use this guide when proposing new entities via RFC, reviewing data contributions, importing data from BGG, or resolving classification disputes.

The Six Entity Types

Primary Decision Tree

Use this flowchart when classifying a product:

flowchart TD
    START["Is the product published by<br/>or licensed by the game's<br/>publisher or rights holder?"]
    START -->|No| FE["✅ fan_expansion"]
    START -->|Yes| GAMEPLAY["Does the product contain<br/>gameplay content?<br/>(rules, cards, tiles, scenarios,<br/>characters, win conditions)"]

    GAMEPLAY -->|No| AC["✅ accessory"]
    GAMEPLAY -->|Yes| STANDALONE["Can you play a complete,<br/>standalone game with<br/>ONLY this product?"]

    STANDALONE -->|Yes| FAMILY["Was this product designed<br/>as part of an existing game family,<br/>sharing its core rules<br/>and designed to integrate?"]
    STANDALONE -->|No| SCOPE["Is the product scope small?<br/>(typically 1-5 components,<br/>single card/tile/mini,<br/>no separate retail packaging)"]

    FAMILY -->|Yes| SE["✅ standalone_expansion<br/>+ integrates_with relationship"]
    FAMILY -->|No| BG["✅ base_game<br/>+ reimplements relationship<br/>if it's a new version"]

    SCOPE -->|Yes| PR["✅ promo"]
    SCOPE -->|No| EX["✅ expansion<br/>+ expands relationship"]

    FE -.- note1["Community-created,<br/>unofficial content"]
    AC -.- note2["Sleeves, organizers,<br/>playmats, upgraded tokens"]
    SE -.- note3["Playable alone AND<br/>mixes with parent family"]
    BG -.- note4["Independently designed<br/>or mechanically distinct"]
    PR -.- note5["Small add-on, usually<br/>free or bundled"]
    EX -.- note6["Requires a base game,<br/>adds content or rules"]

Entity vs Edition Decision Tree

When a new version of an existing game is released, use this flowchart to determine whether it should be a new entity or a new edition of the existing entity. See ADR-0035 for the edition data model.

flowchart TD
    START2["Is a new version of an<br/>existing game being released?"]
    START2 -->|No| PRIMARY["Classify using the<br/>primary decision tree above"]
    START2 -->|Yes| CORE["Are the core rules<br/>fundamentally the same?"]

    CORE -->|Yes| EDITION["✅ New GameEdition<br/>of the existing entity<br/>(use EditionDelta for<br/>property differences)"]
    CORE -->|No| REPLACE["Does it share the same<br/>name/family and explicitly<br/>replace the original?"]

    REPLACE -->|Yes| REIMPL["✅ New entity with<br/>reimplements relationship<br/>to the original"]
    REPLACE -->|No| NEW["✅ New entity<br/>(classify using primary<br/>decision tree)"]

The core rules test: If a player who knows the old version could sit down at the new version and play correctly after a brief explanation of changes, they are editions of the same entity. If the rules teaching is essentially from scratch, they are different entities.

Worked Examples – Clear Cases

• Cosmic Encounter – Standalone game, independently designed. -> base_game
• Wingspan: European Expansion – Requires Wingspan to play, adds new birds/powers/end-of-round goals. -> expansion
• Dominion: Intrigue (2nd Ed.) – Playable alone, shares Dominion family, includes base cards, designed to mix with other Dominion sets. -> standalone_expansion
• Azul: Special Factories Promo – Single tile with new rules, small scope, convention handout. -> promo
• Terraforming Mars Playmat – No gameplay content, just a play surface. -> accessory
• Gloomhaven: Homebrew Class Pack – Not published by Cephalofair. -> fan_expansion
• Carcassonne (2014 new art edition) – Same core rules as original, updated art and minor rule clarifications. -> New GameEdition, not a new entity.

Worked Examples – Grey Zone Cases

Grey Zone 1: promo vs accessory

Catan: Oil Springs – A scenario tile that adds new rules, a new resource type, and a new victory condition path. Even though it is a single tile, the presence of gameplay rules makes it a promo, not an accessory.

Contrast: “Catan Dice Tower” – a physical component with no new rules. -> accessory.

The test: Does the product add new rules, new decision points, new win conditions, or new player options? If yes, it contains gameplay content and is NOT an accessory.

Grey Zone 2: expansion vs standalone_expansion

Dominion: Intrigue (2nd Edition) – Can be played as a complete game by itself (it includes base cards) AND can be mixed with other Dominion sets. -> standalone_expansion.

Contrast: “Dominion: Seaside” cannot be played without base cards from Dominion or Intrigue. -> expansion.

The test: Open the box. Can you play a complete game tonight with nothing else? The presence of a “basic” or “starter” mode does not count – the full game must be playable.

Grey Zone 3: base_game vs standalone_expansion

Pandemic Legacy: Season 2 – Playable alone and shares the Pandemic family name. But it was designed as an independent game with its own rules and story arc, not as a variant of the original Pandemic. The family connection is branding, not mechanical dependency. -> base_game with a recommends relationship to Season 1.

Contrast: “Star Realms: Colony Wars” – same core rules as Star Realms, explicitly designed to be mixed with it, compatible card pool. -> standalone_expansion.

The test: A standalone_expansion must satisfy BOTH conditions: (a) self-sufficient, AND (b) mechanically designed to integrate with an existing game family (shared card pool, compatible components, explicit mix-and-match design). Games that merely share thematic branding but are mechanically independent are base_game.

Grey Zone 4: new entity vs new edition

Tigris & Euphrates (1997) vs Yellow & Yangtze (2018) – Different core mechanics (hexes vs squares, different scoring, different tile placement rules). Even though the designer describes Y&Y as a spiritual successor, the rules are substantially different. -> New entity (base_game) with reimplements relationship.

Contrast: “Carcassonne (2014 new art edition)” – same tile placement, same scoring, updated art and minor rule clarifications. -> New GameEdition with EditionDelta.

The test: Could a player of the original sit down and play correctly after a 2-minute delta explanation? If yes, it’s an edition. If the rules teaching is essentially from scratch, it’s a new entity.

Grey Zone 5: expansion vs fan_expansion

Root: The Clockwork Expansion – Published by Leder Games (the publisher of Root). -> expansion.

Contrast: A homebrew Root faction posted on BGG as a print-and-play PDF by a community member. -> fan_expansion.

The test: Is the content published by, or formally licensed by, the original game’s publisher or rights holder? If a fan expansion is later officially published, it transitions from fan_expansion to expansion (tracked via data correction workflow per ADR-0030).

Grey Zone 6: big promo vs small expansion

Azul: Special Factories Promo (1 tile) – Free convention handout, single component, no packaging. -> promo.

Contrast: “Wingspan: Oceania Expansion (95 cards, new boards, new food tokens)” – separately purchased, has its own box, multiple components, retail product. -> expansion.

The test: A promo is typically free or bundled, 1-5 components, no box, no separate retail SKU. An expansion is separately purchased, has its own packaging, multiple components, and a retail presence. The 5-component guideline is a soft threshold – a 3-card promo pack is a promo; a 3-card expansion with its own box, rulebook, and retail SKU is an expansion.

Grey Zone Rules

1. Gameplay content test (promo vs accessory): If the product adds new rules, new decision points, new win conditions, or new player options, it contains gameplay content and is NOT an accessory. Upgraded components (metal coins, custom dice, playmats) that do not change gameplay are accessories.

2. Self-sufficiency test (expansion vs standalone_expansion): Can a person who has never purchased the parent game play a complete game session with only this product? If yes -> standalone_expansion. If no -> expansion. The presence of a “basic” or “starter” mode does not count – the full game must be playable.

3. Family identity test (base_game vs standalone_expansion): A standalone_expansion must satisfy BOTH conditions: (a) self-sufficient (passes the self-sufficiency test above), AND (b) mechanically designed to integrate with or extend an existing game family (shared card pool, compatible components, explicit mix-and-match design). Games that merely share thematic branding but are mechanically independent are base_game with appropriate relationships.

4. Core rules test (new entity vs new edition): If the core gameplay loop, primary mechanics, and victory conditions are substantially the same, it is a new GameEdition. If any of these are fundamentally different, it is a new entity. “Substantially the same” means a player of the original could play the new version after a brief explanation of changes. “Fundamentally different” means the game requires fresh teaching.

5. Publisher authority test (expansion vs fan_expansion): Published by or formally licensed by the game’s publisher or rights holder -> expansion (or promo). All other community-created content -> fan_expansion. License status is determined by explicit publisher acknowledgment, not by marketplace availability.

6. Scope test (promo vs expansion): Promos are small-scope additions (typically 1-5 components, no separate packaging, often distributed as convention freebies or Kickstarter stretch goals). Expansions have their own packaging, retail presence, and larger component count. When scope is ambiguous, prefer promo for content distributed free/bundled and expansion for separately purchased content.

7. When in doubt, prefer the more specific type. If a product could be either base_game or standalone_expansion, and it clearly belongs to a game family, prefer standalone_expansion. The more specific classification carries more information.

BGG Migration Rules

BGG uses boardgame, boardgameexpansion, and boardgameaccessory as its type system – much coarser than OpenTabletop’s six types. These rules guide the import pipeline (ADR-0032).

Key migration principles

• No standalone_expansion in BGG. These are listed as either boardgame or boardgameexpansion on BGG. During import, any boardgameexpansion that lacks a requires link should be flagged for self-sufficiency review.
• No promo/expansion distinction in BGG. Both are boardgameexpansion. Use component count and distribution method as heuristics, but flag ambiguous cases for human review.
• No edition system in BGG. When multiple BGG entries represent different editions of the same game (discoverable via reimplements links between entries with very similar names), the import pipeline should create one Game entity with multiple GameEdition records, keeping the highest-rated or most-voted entry as the canonical edition.

RFC Reviewer Checklist

When evaluating a proposed entity addition or type classification:

• Decision tree: Does the entity pass the primary decision tree flowchart?
• Self-sufficiency verified: If typed as base_game or standalone_expansion, has someone confirmed it is playable alone?
• Family identity checked: If typed as standalone_expansion, is the game family identified and the integration mechanism described?
• Edition check: Could this entity be an edition of an existing entity? Has the core rules test been applied?
• Publisher authority: If typed as anything other than fan_expansion, is the publisher or license confirmed?
• Scope check: If typed as promo, is the component count small (typically 1-5) and the product non-retail?
• Relationships created: Are the appropriate typed relationships (ADR-0011) created alongside the entity? (e.g., expands for expansions, reimplements for re-releases, integrates_with for standalone expansions)
• BGG cross-reference: If a BGG ID exists, does the chosen type align with or justifiably differ from BGG’s classification?
• Grey zone documented: If the classification involves a grey zone judgment, is the rationale documented in the entity’s notes or the RFC discussion?

People & Organizations

Board games are created by people and published by organizations. The data model captures both with explicit, many-to-many relationships to games.

Person Entity

A Person represents an individual who contributed to a game’s creation.

Game-Person Relationships

The association between a game and a person includes a role that specifies the nature of their contribution:

Roles

A person can have multiple roles on the same game. A single individual might be both designer and developer, and those are recorded as two separate associations.

Many-to-Many

The relationship is fully many-to-many:

• A game can have multiple designers: Pandemic is designed by Matt Leacock (solo), but 7 Wonders Duel is designed by Antoine Bauza and Bruno Cathala.
• A person can design multiple games: Uwe Rosenberg designed Agricola, Caverna, A Feast for Odin, Patchwork, and dozens more.

flowchart LR
    subgraph "Published by Leder Games"
        RT["Root<br/><i>(2018)</i>"]
        UW["Root: The Underworld<br/><i>(2020)</i>"]
        OT["Oath<br/><i>(2021, IP sold 2026)</i>"]
    end

    subgraph "Published by Buried Giant Studios"
        AR["Arcs<br/><i>(2024, IP purchased 2026)</i>"]
        ONF["Oath: New Foundations<br/><i>(2026)</i>"]
    end

    subgraph People
        CW["Cole Wehrle<br/><i>designer</i>"]
        KF["Kyle Ferrin<br/><i>artist</i>"]
    end

    CW -->|designer| RT
    CW -->|designer| UW
    CW -->|designer| OT
    CW -->|designer| AR
    CW -->|designer| ONF
    KF -->|artist| RT
    KF -->|artist| UW
    KF -->|artist| OT
    KF -->|artist| AR
    KF -->|artist| ONF

The same people (Cole Wehrle, Kyle Ferrin) appear on games across two different publishers. The person entities stay the same – only the game-organization relationships change. This is why people and organizations are modeled independently rather than nesting people under their publisher.

Organization Entity

An Organization represents a company involved in bringing a game to market.

Organization Types

Game-Organization Relationships

A game commonly has multiple publishers for different regions:

• Root is published by Leder Games (US), Matagot (France), Schwerkraft-Verlag (Germany), and others.

The region field disambiguates which publisher is responsible for which market. The year field handles cases where publishing rights change over time.

Publisher Transitions

Publishing relationships are not permanent. Designers move between studios, and new expansions for an existing game family may ship under a different publisher. The data model must capture this without rewriting history.

Case study: Leder Games -> Buried Giant Studios. Cole Wehrle and Kyle Ferrin were the lead designer and artist at Leder Games (founded by Patrick Leder), where they created Root (2018), Oath (2021), and Arcs (2024). In January 2026, Wehrle announced that he and Ferrin were leaving to form Buried Giant Studios, joined by Drew Wehrle, Ted Caya, Josh Yearsley, and other longtime collaborators.

Crucially, Buried Giant purchased the rights to both Oath and Arcs from Leder Games outright – this is a full IP transfer, not a license. Root remains at Leder Games. The Oath: New Foundations Kickstarter (funded mid-2024) is now fulfilled by Buried Giant.

In the data model, this produces the following game-organization records:

Note that Oath and Arcs retain their original Leder Games publisher records – that is historical fact. The IP transfer does not rewrite history; it means new products in those families are published by Buried Giant. The person records (Cole Wehrle, Kyle Ferrin) are unchanged across both eras – they are credited on Leder-era and Buried Giant-era games through the same person entities. This is a key reason why people are modeled independently from organizations: a designer’s body of work spans their entire career, not just their tenure at one company.

Querying

Get all games by a designer

GET /people/cole-wehrle/games?role=designer

Returns all games where Cole Wehrle is credited as designer – spanning both the Leder Games and Buried Giant Studios eras.

{
  "data": [
    {
      "id": "01912f4c-a1b2-7c3d-8e4f-5a6b7c8d9e0f",
      "slug": "root",
      "name": "Root",
      "type": "base_game",
      "year_published": 2018,
      "role": "designer",
      "_links": {
        "self": { "href": "/games/root", "title": "Root" }
      }
    },
    {
      "id": "01912f4c-b2c3-7d4e-9f5a-6b7c8d9e0f1a",
      "slug": "oath",
      "name": "Oath: Chronicles of Empire and Exile",
      "type": "base_game",
      "year_published": 2021,
      "role": "designer",
      "_links": {
        "self": { "href": "/games/oath", "title": "Oath" }
      }
    },
    {
      "id": "01912f4c-c3d4-7e5f-af6b-7c8d9e0f1a2b",
      "slug": "arcs",
      "name": "Arcs",
      "type": "base_game",
      "year_published": 2024,
      "role": "designer",
      "_links": {
        "self": { "href": "/games/arcs", "title": "Arcs" }
      }
    },
    // ... Root: The Underworld Expansion, Root: The Marauder Expansion,
    //     Oath: New Foundations, Pax Pamir (Second Edition), etc.
  ],
  "_links": {
    "self": { "href": "/people/cole-wehrle/games?role=designer" }
  }
}

Get all publishers for a game

GET /games/root/organizations?role=publisher

Returns all organizations with a publisher role for Root, disambiguated by region and year.

{
  "data": [
    {
      "organization_id": "01913e5a-1a2b-7c3d-8e4f-5a6b7c8d9e0f",
      "name": "Leder Games",
      "slug": "leder-games",
      "role": "publisher",
      "region": "US",
      "year": 2018,
      "_links": {
        "organization": { "href": "/organizations/leder-games", "title": "Leder Games" }
      }
    },
    {
      "organization_id": "01913e5a-2b3c-7d4e-9f5a-6b7c8d9e0f1a",
      "name": "Matagot",
      "slug": "matagot",
      "role": "publisher",
      "region": "FR",
      "year": 2019,
      "_links": {
        "organization": { "href": "/organizations/matagot", "title": "Matagot" }
      }
    },
    {
      "organization_id": "01913e5a-3c4d-7e5f-af6b-7c8d9e0f1a2b",
      "name": "Schwerkraft-Verlag",
      "slug": "schwerkraft-verlag",
      "role": "publisher",
      "region": "DE",
      "year": 2019,
      "_links": {
        "organization": { "href": "/organizations/schwerkraft-verlag", "title": "Schwerkraft-Verlag" }
      }
    }
    // ... additional regional publishers
  ],
  "_links": {
    "self": { "href": "/games/root/organizations?role=publisher" }
  }
}

Get all artists who worked on games in a family

GET /families/root/people?role=artist

Returns all people credited as artist on any game in the Root family.

{
  "data": [
    {
      "id": "01913d4f-6f7a-7b8c-9d0e-1f2a3b4c5d6e",
      "slug": "kyle-ferrin",
      "name": "Kyle Ferrin",
      "role": "artist",
      "games": [
        { "slug": "root", "name": "Root" },
        { "slug": "root-the-underworld-expansion", "name": "Root: The Underworld Expansion" },
        { "slug": "root-the-marauder-expansion", "name": "Root: The Marauder Expansion" },
        { "slug": "root-the-homeland-expansion", "name": "Root: The Homeland Expansion" }
      ],
      "_links": {
        "self": { "href": "/people/kyle-ferrin", "title": "Kyle Ferrin" }
      }
    }
  ],
  "_links": {
    "self": { "href": "/families/root/people?role=artist" }
  }
}

Players & Collections

Games don’t exist in a vacuum – they’re played by people. The specification models games, the people who create them (People & Organizations), and the people who play them. The Player entity captures who is behind the votes, ratings, play logs, and collection data that power every community-sourced metric in the specification.

Without Player data, every voter is interchangeable. A first-time casual gamer’s weight vote counts the same as a 20-year veteran’s. A voter who uses a 1-5 scale is averaged with one who uses 6-10. A rating from someone who played once is indistinguishable from someone who played 50 times. The Player entity makes these differences visible and actionable.

The Player Entity

The Player entity is deliberately minimal. Most of the richness comes from relationships – what games they own, play, and rate – not from fields on the entity itself.

Collection

A player’s collection captures their relationship to specific games:

A player can have multiple statuses for the same game over time (owned → for_trade → previously_owned). The collection is a time-series of the player’s relationship with each game.

Collection as Demand Signal

Aggregate collection data produces the demand signals that publishers use for print run planning:

These aggregates are surfaced on the Game entity via ADR-0041. The Player entity is where the underlying per-player data lives.

Play Logs

Each play session is recorded as a structured log entry:

Play logs are the foundation of:

• Community playtime data – aggregated into the Play Time Model
• Experience-bucketed playtime – ADR-0034
• Player count ratings – “how many times have you played at this count?” comes from the player’s logs
• Engagement metrics – plays-per-owner ratio on the Game entity

Taste Profile (Derived)

A player’s taste profile is computed from their collection, ratings, and play history – never self-declared. Self-declared preferences are unreliable (“I like all kinds of games” says the person whose collection is 90% heavy euros). Behavioral data is honest.

These are derived, not stored as fields on the entity. Implementations compute them from the underlying data. The specification defines what they mean, not how to compute them – different algorithms may produce slightly different profiles.

Player Archetypes

Archetypes are clusters of players with similar behavioral profiles. They are derived from data, not self-declared labels. A player isn’t “labeled” a eurogamer – their collection, ratings, and play patterns cluster with other eurogamers.

Example archetypes (implementation-defined, not spec-mandated):

Archetypes enable corpus-based analysis: “What do players who own 50+ cooperative games think of this game at 2 players?” This is fundamentally different from – and more useful than – “What does the BGG average say?”

Why Players Matter for Data Quality

The Player entity directly addresses the data quality problems documented across the model docs:

Corpus-Based Filtering

The Player entity enables a fundamentally new kind of filtering for Pillar 2:

Traditional filtering: “Show me cooperative games, weight 2.5-3.5, best at 2 players” – filters on game properties.

Corpus-based filtering: “Show me cooperative games rated above 4.0 by players whose collection is similar to mine” – filters on game properties as assessed by a specific player population.

This is the difference between “what does the crowd think?” and “what do people like me think?” The Player entity makes the second question answerable.

Example Queries

“Games rated highly by players like me”:

GET /games/search?mechanics=cooperative&weight_min=2.5&weight_max=3.5
    &corpus=similar_to_player:01912f4c-a1b2-7c3d-8e4f-5a6b7c8d9e0f
    &corpus_rating_min=4.0

{
  "data": [
    {
      "slug": "pandemic",
      "name": "Pandemic",
      "weight": 2.42,
      "average_rating": 7.6,
      "corpus_rating": 8.9,
      "corpus_match": {
        "similar_players": 342,
        "corpus_rating_count": 287
      },
      "_links": {
        "self": { "href": "/games/pandemic" }
      }
    },
    {
      "slug": "the-crew-mission-deep-sea",
      "name": "The Crew: Mission Deep Sea",
      "weight": 2.07,
      "average_rating": 8.1,
      "corpus_rating": 8.7,
      "corpus_match": {
        "similar_players": 342,
        "corpus_rating_count": 198
      },
      "_links": {
        "self": { "href": "/games/the-crew-mission-deep-sea" }
      }
    }
    // ...
  ],
  "_links": {
    "self": { "href": "/games/search?mechanics=cooperative&weight_min=2.5&weight_max=3.5&corpus=similar_to_player:01912f4c-a1b2&corpus_rating_min=4.0" }
  }
}

Note corpus_rating (8.9) vs average_rating (7.6) for Pandemic – players with similar collections rate it significantly higher than the general population. This is the corpus signal: the undifferentiated crowd rates it 7.6, but people like you rate it 8.9.

“Top solo games according to solo gamers”:

GET /games/search?corpus=archetype:solo-gamer&top_at=1&sort=corpus_rating

{
  "data": [
    {
      "slug": "mage-knight",
      "name": "Mage Knight",
      "weight": 4.28,
      "average_rating": 8.1,
      "corpus_rating": 9.2,
      "corpus_match": {
        "archetype": "solo-gamer",
        "archetype_voters": 1847,
        "corpus_rating_count": 1203
      },
      "player_count_ratings": {
        "1": { "average_rating": 4.8, "rating_count": 1589 }
      },
      "_links": {
        "self": { "href": "/games/mage-knight" }
      }
    }
    // ...
  ]
}

The solo-gamer archetype rates Mage Knight at 9.2 vs the general population’s 8.1 – and the per-count rating at 1 player is 4.8/5. This is a game that the broader community likes, but solo gamers love.

These queries are aspirational – the specification defines the data model that makes them possible, but the query syntax and implementation are future RFC topics.

Privacy Considerations

Player data is sensitive. The specification defines these principles:

• Opt-in. Player profiles are created voluntarily. Anonymous voting remains possible – a vote without a linked Player entity is valid but lacks the context metadata.
• Aggregation without exposure. Archetype distributions, corpus-based ratings, and voter population analysis can be computed without exposing individual player identities or collections.
• Player controls their data. A player can delete their profile, which anonymizes their votes (the votes remain, the Player link is severed).
• No required disclosure. Fields like declared_rating_scale and experience_level are optional. Players provide what they’re comfortable with.

Relationship to Other Entities

flowchart LR
    P["Player"]
    G["Game"]
    C["Collection Entry"]
    PL["Play Log"]
    R["Rating / Vote"]

    P -->|owns/wishlists| C
    C -->|references| G
    P -->|logs plays of| PL
    PL -->|for game| G
    P -->|rates / votes on| R
    R -->|for game| G

The Player is the hub connecting games to the community data about them. Every rating, weight vote, player count rating, playtime log, and collection status traces back to a Player – or to an anonymous voter whose data is valid but uncontextualized.

Rating Model

Game ratings are the most visible number in any board game database – and the most misunderstood. A rating of 8.3 does not mean a game is objectively “8.3 out of 10 good.” It means a self-selected population of voters produced that average. The OpenTabletop specification stores ratings as raw distributional data, exposing the inputs rather than a single opaque output.

How OpenTabletop Stores Ratings

The Game entity carries these rating fields:

The rating and rating_votes are the source data. The bayes_rating is a derived value that implementations may compute using their own parameters (Layer 4). The rating_confidence is the spec-level trust signal (Layer 3). The rating_distribution histogram exposes the full shape of voter opinion.

BGG’s Bayesian Average (“Geek Rating”)

BoardGameGeek computes its rankings using a Bayesian average. BGG has never published the exact formula, but reverse-engineering analysis estimates it adds approximately 1,500 dummy votes each rated at 5.5 (the midpoint of the 1-10 scale) to every game’s actual votes:

geek_rating = (sum_of_real_ratings + 1500 × 5.5) / (real_vote_count + 1500)

Purpose: This prevents a game with two 10/10 ratings from outranking a game with 50,000 votes averaging 8.5. By pulling all games toward 5.5, the formula requires a large number of high ratings to climb the rankings.

Example: A game with 100 real votes averaging 9.0 gets a geek rating of ~5.72 (still pulled heavily toward 5.5). A game with 50,000 real votes averaging 8.5 gets a geek rating of ~8.41 (barely affected by the dummy votes). The dummy votes wash out as real votes accumulate.

Known Problems with the BGG Rating Model

1. Secret, Non-Reproducible Algorithm

The exact number of dummy votes, their value, and the definition of “regular voter” are not public. Reverse-engineering efforts estimate ~1,500 dummy votes at ~5.5 (with best-fit values ranging from 5.494 to 5.554 depending on methodology), but BGG has never confirmed any parameter, and they may change over time. A specification built on a secret algorithm is not a specification – it’s a black box.

2. Opaque Vote Scrubbing

BGG removes ratings it considers suspicious – likely from new accounts, inactive accounts, or patterns suggesting manipulation. The criteria are unpublished, which means the same raw data can produce different rankings depending on which votes BGG decides to include. This is understandable as an anti-manipulation measure but makes the ranking non-deterministic from an outside observer’s perspective.

3. Dummy Votes Don’t Distinguish New from Niche

A game with 50 votes might be new (and will accumulate more) or niche (and 50 votes is its steady state). The Bayesian average penalizes both equally. A niche wargame beloved by its small community and a recently-released party game both get pulled toward 5.5, but for entirely different reasons. The formula cannot distinguish these cases.

4. Inconsistent Scale Usage

The 1-10 scale is used inconsistently across voters:

• Some voters use the full range (1-10). Others effectively rate on a 5-10 scale, never rating below 5.
• Some voters use a 1-5 mental scale mapped onto BGG’s 1-10 range – their “5 out of 5” game gets a 5, not a 10. This makes them appear to rate everything extremely low compared to voters using the full range. A voter whose highest rating is a 5 and another whose lowest is a 6 are using incompatible scales, but their votes are averaged together as if they weren’t.
• Some voters only rate games they own (biasing upward). Others rate games they disliked and traded away.
• Some voters treat ratings as a personal ranking tool (their #1 game gets a 10, their #50 gets a 6). Others treat the scale as absolute.
• The result: a “7” from one voter is not comparable to a “7” from another. There is no calibration mechanism – BGG does not normalize ratings across voters or detect incompatible scale usage.

5. Complexity Bias

Dinesh Vatvani’s analysis demonstrates a significant correlation between game complexity (weight) and BGG rating. The heaviest games on BGG average roughly 2.5 points higher than the lightest games (regression slope ~0.63 on the 1-5 weight scale mapped to the 1-10 rating scale). This is not because complex games are objectively better – it’s because BGG’s voter population disproportionately values complexity. See Weight Model for deeper analysis.

6. Self-Selection Bias

Only people who care enough to rate games on BoardGameGeek – whether through the website, the BGG app, or third-party apps that sync plays and ratings back to BGG – are represented. This population skews toward experienced hobbyist gamers who prefer medium-to-heavy strategy games and are engaged enough in the hobby to track their plays and maintain ratings. Casual gamers, families, and non-English-speaking communities are underrepresented. The BGG top 100 is a popularity contest within a specific demographic, not a universal quality ranking.

OpenTabletop addresses this structurally: because the specification is language-agnostic and designed for multiple independent implementations, a Japanese board game community, a German community, or a Brazilian community can each run conforming servers with their own voting populations. Ratings from these communities reflect their preferences, not BGG’s English-speaking demographic. The same API contract serves all of them, and applications can query across communities or within a specific one. See Data Provenance & Bias.

OpenTabletop’s Approach

Input Contract

The rating model follows the specification’s Input Contract principles:

The Four-Layer Model

OpenTabletop uses a four-layer model that addresses the fundamental problems with BGG’s approach:

Layer 1: Voter-Declared Scale

The specification captures each voter’s personal scale preference as metadata at vote time. A voter can declare “I rate on a 1-5 scale” or “I rate on a 1-10 scale” or “I only use the 5-10 range.” This declaration is the normalization key: a voter whose declared max is 5 has their 5 mapped to 10 on the canonical 1-10 scale.

This eliminates the “1-5 voter looks like they hate everything” problem at the source rather than trying to correct for it statistically. It also makes the normalization transparent to the voter (“your 4/5 is recorded as 8/10 on the canonical scale”).

Where declared scale data is unavailable (e.g., legacy BGG imports), implementations may fall back to statistical inference (see Item Response Theory below), but the spec’s native path is explicit declaration.

Layer 2: Raw Normalized Data

All aggregate statistics are computed from votes normalized to the canonical 1-10 scale:

• average_rating – Arithmetic mean of normalized votes. No dummy votes, no scrubbing, no secret formula.
• rating_count – Sample size. Consumers assess reliability themselves.
• rating_distribution – Full 1-10 histogram revealing distribution shape:
  • Tight bell curve around 7-8 = broad consensus.
  • Bimodal (peaks at 4 and 9) = polarizing game.
  • Left-skewed = most like it, a few hate it.
  • The shape tells a richer story than any average.
• rating_stddev – Standard deviation quantifying voter agreement (0.8 = tight consensus, 2.5 = wild disagreement).

Layer 3: Confidence Score

A spec-defined confidence metric (0.0 to 1.0) that answers: “How much should you trust this rating?” Computed from:

• Sample size – Wilson-style penalty for small n. A game with 50 votes gets lower confidence than one with 50,000, even if both average 8.5.
• Distribution shape – Tight consensus (low std dev) increases confidence. Polarized distributions (high std dev, bimodal) decrease it.
• Deviation from global mean – Ratings far from the population mean require more evidence. A 9.5 average with 100 votes gets lower confidence than a 7.5 average with 100 votes, because extraordinary claims require extraordinary evidence.

The confidence formula is published, reproducible, and deterministic – any consumer can verify it. It replaces bayes_rating as the spec-level field, because confidence is a more honest signal than an opaque adjusted number.

Layer 4: Implementation-Recommended Ranking

For implementations that need to sort games (leaderboards, “top 100” lists), the specification recommends Bayesian scoring with a Dirichlet prior over the 10-point rating distribution:

Instead of BGG’s estimated approach (adding ~1,500 dummy votes all at a single value of ~5.5), the Dirichlet method assigns per-bucket prior votes across the full rating distribution. This is mathematically sound (the Dirichlet distribution is the conjugate prior for categorical data) and more expressive – the prior can encode “we expect a game to have a roughly normal distribution centered at 6” rather than collapsing all prior weight onto a single point.

score = Σ(utility[i] × (prior_votes[i] + actual_votes[i])) / Σ(prior_votes[i] + actual_votes[i])

Where utility[i] maps each rating bucket to a value (e.g., 1 through 10) and prior_votes[i] is the per-bucket prior. The spec documents reference parameters; implementations may tune their own.

This layer is implementation guidance, not a spec requirement. The spec guarantees Layers 1-3. Layer 4 is a recommendation for implementations that need ranking.

Statistical Models Considered

The following models were evaluated for the rating system. This analysis is documented to inform the commons group and future RFC discussions.

Anti-Gaming Considerations

A published, transparent formula is essential for a commons – but transparency creates a target for manipulation. The rating model must be designed to resist:

Fan brigading. Coordinated groups inflating or deflating ratings. Mitigations: account age requirements before rating, play log verification (must log at least one play before rating), weighting by voter history diversity, anomaly detection on sudden vote spikes.

Publisher self-promotion. Publishers or affiliates inflating their own games. Mitigations: the spec supports conflict-of-interest metadata – a voter’s relationship to the game’s publisher or designer can be declared or detected, and implementations can weight those votes differently (not discard them – transparency, not censorship).

Spite voting. Organized downvoting campaigns against a competing game. Same mitigations as brigading, plus the Dirichlet prior naturally bounds the impact – no single vote or small group of votes can dramatically shift a well-established rating.

Formula exploitation. Sophisticated actors optimizing voting patterns to maximize impact. The Dirichlet prior model is inherently robust here: each individual vote’s marginal impact decreases as total votes increase, and the per-bucket prior prevents extreme distributions from dominating with few votes.

The specification recommends that conforming implementations:

1. Publish their scoring formula. Transparency is non-negotiable for a commons standard.
2. Bound individual vote influence. No single vote should be able to move a game’s rating by more than a defined maximum percentage.
3. Implement velocity limits. Maximum N ratings per account per time period.
4. Flag, don’t silently discard. Suspicious patterns should be flagged transparently with reason codes – not secretly scrubbed as BGG does. The community should be able to audit moderation decisions.

Case Study: Pre-Release Brigading

In early 2026, an unreleased crowdfunded game announced the use of AI-generated art. The community response on BGG was immediate and extreme: organized 1-star voting as a protest against the publisher’s decision. This triggered a counter-response of defensive 10-star votes attempting to offset the damage. The result was a rating distribution that contains almost no quality signal:

Key statistics: 479 total votes. Average: 4.10. Standard deviation: 4.16 – against a theoretical maximum of 4.5 for a 1-10 scale. This distribution is at 92% of maximum possible disagreement. 93% of all votes are at the two extremes (1 or 10); only 7% fall in the 2-9 range. The game has not been released – none of these votes reflect play experience.

What BGG reports: BGG displays the raw average (4.1) to users in the UI. Under the hood, the Bayesian average (~1,500 dummy votes at ~5.5) produces an estimated geek rating of approximately 5.16, which determines the game’s ranking position – but this number is never shown to users. A casual observer sees “4.1” and assumes it’s a low-rated game. Nothing in BGG’s interface signals that 93% of votes are political protest/counter-protest, not quality assessment. And the hidden ranking score of ~5.16 would place this unreleased, unplayed game alongside legitimately mediocre games that people have actually experienced.

What OpenTabletop’s model reports:

The confidence score of 0.27 (on a 0-1 scale) immediately signals: do not trust this rating. The high vote count (479) is not the problem – the sample size factor is fine (0.95). The problem is the distribution shape factor (0.07) – a std dev of 4.16 on a 1-10 scale is nearly indistinguishable from random noise at the extremes. The confidence score captures what BGG’s Bayesian average cannot: that a number can be statistically “precise” (small margin of error around 4.10) while being semantically meaningless (the votes don’t measure game quality).

What the input contract would add: If the specification requires “number of plays” as vote context metadata, every vote on this unreleased game would be flagged as a 0-play rating. Implementations could display these votes separately (“0-play ratings: 4.10 avg / 479 votes / confidence: 0.27”) from post-release play-based ratings, letting consumers see the protest signal without it contaminating the quality signal.

Detection heuristics: This pattern is detectable:

• Std deviation above 3.5 on a 1-10 scale (healthy games rarely exceed 2.5)
• More than 80% of votes at the two extremes (1 and 10)
• Sudden vote spike correlated with a news event rather than gradual accumulation
• Zero or near-zero play logs associated with the votes

Further Reading

• How Not To Sort By Average Rating (Evan Miller, 2009) – Why Wilson score intervals beat simple averages for binary ratings
• Bayesian Scoring of Ratings (Jules Jacobs, 2015) – Dirichlet-prior approach for star ratings, extending beyond binary
• Reverse Engineering the BoardGameGeek Ranking – Technical analysis of BGG’s Bayesian average formula
• Complexity Bias in BGG (Vatvani, 2018) – Quantitative analysis of the weight-rating correlation
• Debiasing the BoardGameGeek Ranking – Methodology for removing complexity bias from rankings
• Adjusted Board Game Geek Ratings (2025 update) – Updated interactive analysis
• Crowdsourcing with Difficulty: A Bayesian Rating Model for Heterogeneous Items (2024) – IRT-based approach for crowdsourced ratings
• Data Provenance & Bias – OpenTabletop’s philosophical foundation for handling subjective data

Weight Model

“Weight” is the board game community’s term for perceived complexity. It is the single most misunderstood metric in board game databases – treated as an objective property of a game when it is actually a perception that varies by voter, context, and community.

How OpenTabletop Stores Weight

The Game entity carries these weight fields:

The specification treats weight as a community perception metric, not an intrinsic game property. The weight_votes field is critical context: a weight of 3.5 with 5,000 votes is a stable signal; 3.5 with 12 votes is noise.

The 1.0-5.0 Scale

The weight scale uses anchor games as calibration reference points (see Taxonomy Criteria for the full table):

What Weight Actually Measures (And Doesn’t)

Weight conflates several distinct dimensions into a single number:

• Rules complexity – How many rules are there? How many exceptions? How long does the rulebook take to read?
• Strategic depth – How much does skill matter? How many meaningful decisions per turn?
• Decision density – How many choices does each turn present? How much do they interact?
• Cognitive load – How much state must a player track mentally? How far ahead must they plan?
• Fiddliness – How many physical components must be manipulated? How many bookkeeping steps per round?
• Game length – Longer games tend to be rated heavier, even if individual turns are simple.

A game like Twilight Imperium is heavy on nearly every dimension. But a game like Go has trivial rules complexity, zero fiddliness, and extreme strategic depth – yet gets a moderate weight rating because voters mentally average across all dimensions. The single-number weight rating cannot distinguish these profiles.

Known Problems with the Weight Model

1. Weight Is Perceptual, Not Objective

The same game receives genuinely different weight perceptions from different populations:

• An experienced strategy gamer who plays Mage Knight weekly might rate Terraforming Mars a 2.5 (“moderate – fewer subsystems than what I usually play”).
• A casual gamer encountering Terraforming Mars for the first time might rate it 4.5 (“one of the most complex games I’ve ever played”).
• Both assessments are valid within their reference frames. The aggregate average reflects the voter population, not the game.

2. No Calibration Mechanism

Unlike the rating scale (where everyone agrees “10 means I love it”), the weight scale has no universally understood anchors. The informal anchor games listed above help, but voters rarely consult them before voting. Most weight votes are intuitive, based on how a game felt relative to the voter’s personal experience – not an objective assessment against a calibrated scale.

3. Complexity Bias in Ratings

Dinesh Vatvani’s analysis quantifies a significant correlation between weight and BGG rating:

• Regression slope: ~0.63 – For each point increase in weight (1-5 scale), the average BGG rating increases by ~0.63 points (1-10 scale).
• Total effect: ~2.5 points – The heaviest games on BGG average roughly 2.5 rating points higher than the lightest games.
• This is not because complex games are better. It’s because BGG’s voter population disproportionately values complexity. Experienced hobbyists who rate games on BGG tend to prefer heavier games, and the same population votes on both weight and rating.

The practical effect: light games that are excellent for their audience (party games, family games, gateway games) are systematically underrated relative to heavy games. A brilliant party game like Codenames sits at 7.6 while a heavy strategy game of comparable design quality sits at 8.5+.

4. “The Tail of Spite”

Vatvani’s analysis identifies a cluster of old, mass-market games with both low weight and extremely low ratings: Monopoly (4.4), Candy Land (3.2), Snakes and Ladders (2.8). These games are rated by people who grew up with them and now rate them harshly from the perspective of experienced hobbyists. The ratings don’t reflect these games’ fitness for their intended audience (children, families, casual play) – they reflect the BGG community’s disdain for simplicity.

5. Self-Selected Voter Population

The people who rate weight on BGG are overwhelmingly experienced hobbyist gamers. Their perception of “how complex is this?” is calibrated against hundreds of games they’ve played. A casual gamer’s 4.0 rating and a hardcore gamer’s 2.5 rating for the same game are both “correct” within their frame – but only the hardcore gamer’s vote is likely to be recorded on BGG.

This means weight ratings are most accurate for the middle-to-heavy portion of the spectrum (2.5-4.5) where BGG’s voter population has the most experience. Very light games (1.0-2.0) and the extremes of heaviness (4.5-5.0) are less reliably rated because fewer voters have extensive experience at those ends.

6. Experience Modifies Perception

A game’s perceived weight decreases with experience. Spirit Island might feel like a 4.5 on first play and a 3.5 after twenty plays – but the voter only submits one number. When that number was submitted matters, and BGG doesn’t track whether a weight vote came from a first-time player or a veteran. The aggregate weight reflects an unknowable mix of experience levels.

OpenTabletop’s Approach

The specification acknowledges weight’s limitations while preserving its utility as the best available community signal for complexity:

1. Store the raw average and vote count. The weight and weight_votes fields provide the signal and its sample size. Consumers can assess reliability.

2. Expose the distribution where possible. The specification’s commitment to distributional data (see Data Provenance & Bias) means implementations are encouraged to store and expose weight vote distributions, not just averages. A bimodal weight distribution (many 2.0 votes and many 4.0 votes) signals that different player populations perceive the game very differently.

3. Don’t treat weight as absolute. The specification never says a game “is” a specific weight. It says the community rated it at that weight. Applications should present weight in context: “Rated 3.86 by 5,127 voters” rather than “Weight: 3.86.”

4. Anchor games provide calibration. The Taxonomy Criteria weight scale with anchor games gives voters and implementations a shared reference frame. When a voter considers whether Brass: Birmingham is a 3.5 or a 4.0, comparing it to the anchor games at each level produces more consistent results than an unaided gut feeling.

5. Consider debiasing for rankings. Implementations that rank games should consider complexity-bias correction – a simple linear regression that produces “complexity-agnostic” ratings. This surfaces excellent light games that the raw rankings bury.

Input Contract

The weight model follows the specification’s Input Contract principles. Because weight conflates multiple distinct dimensions (see What Weight Actually Measures above), the specification supports two input modes:

Quick Mode

A single composite rating for voters who want a fast, familiar experience:

Detailed Mode (Dimensional Survey)

An optional decomposed survey where each dimension of “weight” is rated independently. This eliminates the “what does weight mean?” ambiguity by asking concrete, answerable questions:

The composite weight is computed as the mean of the dimensional ratings (or an implementation-defined weighted average). Implementations may choose to weight certain dimensions more heavily – for example, weighting strategic depth higher than fiddliness if their audience considers depth more important than busywork.

Why Dimensional Data Matters

Dimensional weight data enables queries that a single number cannot:

• “Show me games with high strategic depth but low fiddliness” – separates good complexity from tedious complexity.
• “Show me games with low rules complexity but high decision density” – finds elegant designs with simple rules and deep decisions (e.g., Go, Azul).
• “Show me games where cognitive load is high but rules complexity is low” – finds games that are easy to learn but hard to master.

A game like Go has trivial rules complexity (1/5), zero fiddliness (1/5), but extreme strategic depth (5/5) and high cognitive load (5/5). Its composite weight of ~3.0 looks “medium” – but the dimensional profile reveals it is anything but average. A game like Twilight Imperium scores 4-5 on every dimension – its 4.4 composite accurately represents uniform heaviness. The single number hides the profile; the dimensions reveal it.

Partial Responses

Voters may answer any subset of dimensions. A voter who answers 3 of 6 dimensions still provides useful signal. The composite is computed from available dimensions only, with the response count tracked per dimension for confidence assessment.

Backward Compatibility

Quick mode produces the same single-number weight that existing consumers expect. Implementations that support only quick mode are fully conforming. Detailed mode is additive – it enriches the data without breaking any existing interface.

Further Reading

• Complexity Bias in BGG (Vatvani, 2018) – Quantitative analysis of the weight-rating correlation
• Adjusted Board Game Geek Ratings (2025 update) – Interactive, updated debiased rankings
• Debiasing the BoardGameGeek Ranking – Methodology for removing complexity bias
• Weight: Depth vs. Complexity (BGG forum) – Community discussion of what weight actually measures
• Data Provenance & Bias – OpenTabletop’s philosophical foundation for handling subjective data
• Rating Model – Companion document on BGG’s rating system and its problems

Player Count Model

Player count is not a single number. A game that “supports 1-4 players” may be excellent at 2, good at 3, mediocre at 1, and actively bad at 4. The player count model captures this nuance through three layers: publisher range, community ratings per count, and effective range with expansions.

Publisher Range

The min_players and max_players fields on the Game entity store what the publisher prints on the box. These are factual – the publisher says the game supports this range – but they say nothing about quality.

Example: Terraforming Mars is listed as 1-5 players. This is accurate in the sense that the rules work for any count in that range – but it says nothing about quality. The solo mode is essentially a different game (beating a timer rather than competing), and 5-player games can run over three hours.

Community Player Count Ratings

The PlayerCountRating entity captures how the community rates the experience at each supported player count. Each voter independently rates each player count on a 1-5 scale (1 = poor, 5 = excellent). This produces a real numeric distribution per player count that can be analyzed with standard statistical tools.

Key properties of this model:

• Independent ratings. A voter who thinks 3p and 4p are both excellent can rate both 5/5. No forced ranking.
• No overlapping categories. A single numeric scale has no ambiguity about where “good” ends and “great” begins – those are thresholds consumers choose.
• Standard statistics. Mean, median, std dev, percentiles, confidence intervals – all standard tools apply directly.
• Per-count distributions. Implementations are encouraged to store the full vote distribution (how many 1s, 2s, 3s, 4s, 5s) per player count, not just the average.

Example: Terraforming Mars Player Count Ratings

From this data, a consumer can derive:

• Highest rated at 3 (4.7/5 with tight consensus at std dev 0.5).
• Well-rated at 2 and 4 (both above 3.5, the “good” threshold).
• Poorly rated at 1 and 5 (both below 2.5, suggesting these counts are not the intended experience).
• Polarization visible at 1p and 5p via high standard deviation – voters disagree, some love the solo mode while others don’t consider it a real game.

The specification stores the raw rating data, not derived labels. Different applications may use different thresholds: a hardcore strategy app might set “recommended” at 4.0+, while a family app might set it at 3.0+. The raw data enables any interpretation.

Player count rating data reflects the voting community’s experience and preferences. This community tends to be experienced hobbyist gamers whose priorities at different player counts – tolerance for downtime, game length, and complexity scaling – may differ from casual players, families, or groups new to the hobby. See Data Provenance & Bias.

BGG Legacy Data

For migration from BoardGameGeek (ADR-0032), the specification also supports the PlayerCountPollLegacy schema, which preserves BGG’s three-tier voting model (Best / Recommended / Not Recommended). This data is imported during migration and available via the API, but it is not the native model.

The three-tier model has known statistical limitations – overlapping categories, forced ranking, missing middle ground, and anchoring bias – documented in ADR-0043. Implementations may convert legacy three-tier data to approximate numeric ratings (e.g., Best -> 5, Recommended -> 3.5, Not Recommended -> 1.5) for unified querying, but should flag the source as "bgg_converted" for transparency.

Derived Fields

For convenience, the Game entity includes pre-computed derived fields based on the rating data:

These thresholds are implementation-defined. The specification documents them as convenience fields – the raw per-count rating data is always available for custom analysis.

“Highly Rated at 2” vs “Supports 2”

This distinction – between factual support and community quality sentiment – is critical and is something no existing board game API captures well:

• “Supports 2” means the rules work with 2 players. This is a binary fact derived from min_players <= 2 <= max_players.
• “Highly rated at 2” means the community rates the 2-player experience well (e.g., above 4.0/5). This is a community assessment derived from per-count ratings.
• “Acceptable at 2” means the community considers 2 at least a reasonable experience (e.g., above 3.0/5). This is a softer threshold.

All three are independently filterable. When you search for games with players=4, you get games that support 4. When you search with top_at=4, you get games the community rates highly at 4. When you search with recommended_at=4, you get games where 4 is at least a decent experience. The specific threshold values are application-defined – the API provides the raw per-count ratings and lets consumers set their own cutoffs.

Effective Player Count with Expansions

When effective mode is enabled, player count filtering considers expansion combinations. The ExpansionCombination entity can override player count ranges and community ratings:

• Cosmic Encounter base: supports 3-5, highest rated at 5 (4.6/5)
• Cosmic Encounter + Cosmic Incursion: supports 3-6, highest rated at 5-6 (4.5+/5)
• Cosmic Encounter + Cosmic Incursion + Cosmic Conflict: supports 3-7, highest rated at 5-6 (4.4+/5)
• Cosmic Encounter + all expansions: supports 3-8, highest rated at 5-6 (4.3+/5)

Effective mode searches across all known combinations, so a query for players=7&effective=true would surface the Cosmic Encounter + Incursion + Conflict combination even though the base game only supports up to 5.

See Property Deltas & Combinations for how these effective properties are determined.

Beyond the Range

Community ratings sometimes include data for player counts outside the publisher range. A game listed as 2-4 players might have ratings for 1 player (via an unofficial solo variant) or 5 players (via a fan expansion or house rule). These ratings are stored if they exist but are clearly outside the publisher-stated range, and the API distinguishes them accordingly.

OpenTabletop’s Approach

Input Contract

The player count model follows the specification’s Input Contract principles:

Known Limitations

The numeric per-count rating model addresses the major flaws of BGG’s three-tier system (see ADR-0043), but has its own considerations:

• Scale calibration. What does “3 out of 5” mean for a player count? The specification does not yet define anchor descriptions (unlike the weight scale). This is a future RFC topic.
• BGG data conversion. Converting three-tier BGG data to numeric ratings requires mapping assumptions (e.g., Best -> 5, Recommended -> 3.5, NR -> 1.5). Different mappings produce different results. Implementations should document their conversion formula.
• Voter adoption. The numeric model requires voters to learn a new interface. Implementations that also support the familiar BGG-style three-tier input as an alternative should convert those inputs to numeric values internally.
• Population bias. Regardless of the voting model, the voter population skews toward experienced hobbyist gamers. The rating data reflects their priorities (tolerance for downtime, strategic depth at each count), not a universal assessment. See Data Provenance & Bias.

Play Time Model

Play time is one of the most commonly misrepresented data points in board gaming. The publisher says “60 minutes,” but your first game took 3 hours. The data model addresses this with a dual-source approach: publisher-stated times and community-reported times as separate, independent fields.

Publisher-Stated Play Time

The min_playtime and max_playtime fields store what appears on the box, in minutes:

These are factual records of what the publisher claims. They are useful for comparison across games (a “60-90 minute” game is in a different category than a “180-240 minute” game), but they should not be taken as accurate predictions of actual play time.

Why Publisher Times Are Optimistic

Publisher play time estimates are systematically biased toward lower numbers for several reasons:

• Marketing pressure. A shorter play time makes the game more appealing to a wider audience. “90 minutes” sounds more accessible than “2-3 hours.”
• Experienced players assumed. Publishers often time with their own playtest groups who know the game intimately. First-time players will be significantly slower.
• Setup and teardown excluded. The timer starts when the first turn begins, not when you open the box. For complex games, setup can add 15-30 minutes.
• Analysis paralysis not modeled. Real players think longer than ideal players, especially in strategy-heavy games.
• Player count variation ignored. Many publishers list a single time range that does not scale with player count, even when a 5-player game takes twice as long as a 2-player game.

Community-Reported Play Time

The community_min_playtime and community_max_playtime fields are derived from actual play logs submitted by community members:

These represent the range within which most community-reported plays fall. The specification defines “most” as the 10th to 90th percentile of reported play times, excluding obvious data entry errors (plays under 5 minutes or over 24 hours for non-campaign games).

Data Source

Community play times come from logged plays where the player recorded a duration. Not all logged plays include duration, and the ones that do are self-reported, so there is inherent noise. With enough data points, the aggregate provides a more detailed picture than publisher estimates – though it still reflects the play patterns of people who log their games, who tend to be more experienced hobbyist gamers. See Data Provenance & Bias for more on how community data is shaped by who contributes it.

Example: Ark Nova

The publisher says 90-150 minutes. The community data tells a different story: even experienced 2-player games rarely finish under 2 hours, and 4-player games with new players can exceed 3.5 hours. The publisher’s 90-minute lower bound assumes experienced players making fast decisions – a condition that rarely holds for a game with this much card variety and decision density.

Example: Gloomhaven

The publisher’s optimistic “60-120 minutes” per scenario misses that most groups, especially in early scenarios with new characters, spend 90-180 minutes. Setup and teardown alone can take 20 minutes.

Filtering by Play Time

The filter dimensions support both sources:

• playtime_min / playtime_max – Filter using whichever source is selected by playtime_source
• playtime_source=publisher – Use publisher-stated times (default)
• playtime_source=community – Use community-reported times

Why default to publisher times? Because publisher times are available for nearly every game, while community times require sufficient play log data. For less popular games, community data may not exist. Defaulting to publisher ensures the broadest coverage while allowing users who want accuracy to opt into community times.

Play Time with Expansions

Expansions frequently change play time. Adding content means more decisions, more setup, and longer games. The property delta system captures these changes:

• Base game publisher time: 90-120 min
• With expansion: 90-150 min (individual delta)
• With two expansions: 120-180 min (explicit combination)

When effective mode is enabled, play time filtering considers these expansion effects.

Experience-Adjusted Play Time

All playtime data – publisher-stated, community-reported, and expansion-modified – implicitly assumes experienced players. But a first play of Agricola takes roughly 60% longer than an experienced play – the card combinations, feeding mechanics, and action optimization are overwhelming on first encounter. The experience-adjusted playtime model (ADR-0034) addresses this by bucketing community play data by experience level.

Experience Levels

How It Works

Community play logs include a self-reported experience level. The system aggregates these into per-level median and percentile times. Multipliers are derived per-game as median[level] / median[experienced].

Example: Agricola

Agricola’s first-play multiplier is 1.58× – a first-time group should budget nearly twice the box’s “30 minutes per player” estimate. The card combinations, feeding pressure, and action space are overwhelming on first encounter. The expert multiplier of 0.74× reflects that veteran players who have internalized the occupation/improvement combos and optimal action sequences can finish remarkably quickly.

Why Per-Game Multipliers Matter

Different games have fundamentally different experience curves:

• Party games (Codenames, Wavelength): Near-zero first-play penalty. Rules take 2 minutes to explain, and play speed barely changes with experience.
• Medium-weight euros (Wingspan, Everdell): Moderate first-play penalty (~1.3×). The rules are learnable in one session, but card familiarity speeds up experienced play.
• Heavy games (Agricola, Through the Ages): High first-play penalty (~1.5-2.0×). Complex interlocking systems, large decision trees, and frequent rules references extend first plays dramatically.

A global multiplier would be wrong for all three categories. Game-specific data from community play logs captures these differences accurately.

Filtering by Experience Level

The playtime_experience parameter adjusts playtime filtering:

GET /games?playtime_max=120&playtime_source=community&playtime_experience=first_play

This asks: “Show me games where a first play fits in 2 hours.” Agricola’s community max (130 min) adjusted for first_play (× 1.58 = 205 min) exceeds 120, so it is correctly excluded – a first play of Agricola will not fit in 2 hours.

See Filter Dimensions for the full parameter reference.

Games Without Experience Data

Games with fewer than a minimum number of experience-tagged play logs fall back to global default multipliers (derived from aggregate data across all games). The sufficient_data flag in the experience profile indicates whether game-specific or global multipliers are in use.

OpenTabletop’s Approach

Input Contract

The playtime model follows the specification’s Input Contract principles:

Future: Play Time Distribution

The current model stores the range (min/max). A future version of the specification may include full distribution data:

• Median play time
• Percentile breakdown (25th, 50th, 75th, 90th)
• Play time by player count (2p median, 3p median, etc.)
• Play time trend over time (are plays getting faster as the community learns the game?)

This data exists in play logs and is planned for the statistics foundation. The current range fields are a pragmatic starting point.

Age Recommendation Model

Age recommendations serve two audiences: parents choosing games for children, and groups gauging whether a game’s complexity matches their comfort level. The publisher prints “14+” on the box, but the community may consider 12 perfectly appropriate. The age recommendation model captures both perspectives as separate, independent data points.

Publisher-Stated Age

The min_age field on the Game entity stores what the publisher prints on the box:

This is a factual record of what the publisher claims. It is useful for filtering and comparison, but it reflects the publisher’s judgment – which is shaped by factors beyond gameplay suitability.

Why Publisher Ages Are Conservative

Publisher age recommendations are systematically biased toward higher numbers for several reasons:

• Liability. A lower age recommendation increases the publisher’s exposure if a parent considers the game inappropriate. Erring high is the safer legal default.
• Complexity conflation. A “14+” rating often means “this is a complex strategy game,” not “this game contains content inappropriate for 13-year-olds.” The age number conflates cognitive difficulty with content suitability.
• Regulatory variation. Different countries have different safety and labeling requirements. The “3+” CE marking in the EU is about small parts and choking hazards, not gameplay difficulty. Publishers sometimes set a higher age floor to sidestep regulatory categories entirely.
• One size fits all. A single number cannot capture “simple enough at 10 with parental guidance, independently at 14.” Publisher ratings must collapse a spectrum into a single threshold.

Community Age Polls

The CommunityAgePoll entity captures community votes on what minimum age they would recommend:

Community members vote on the age they believe is appropriate. Unlike player count polls (which offer Best/Recommended/Not Recommended), age polls are simpler: voters pick the minimum age they would suggest. The distribution of votes reveals how the community’s assessment compares to the publisher’s.

The Game entity includes a pre-computed derived field:

This is computed as the median of all votes, providing a single representative value. The raw poll data is always available for custom analysis.

Example: Pandemic

Pandemic is a cooperative strategy game. The publisher rates it at 8+.

The community suggested age is 10 – two years higher than the publisher’s box rating. While an 8-year-old can physically play (move pawns, draw cards), the cooperative strategy layer – managing hand cards across players, planning multi-turn cure sequences, and prioritizing outbreak containment – requires the kind of forward planning that most voters consider a 10-year-old task. The gap between “can play” and “can meaningfully contribute to strategy” is exactly what the community poll captures.

Example: Ticket to Ride

Ticket to Ride is a gateway game. The publisher rates it at 8+.

The community suggested age is 8 – aligning with the publisher. Simpler games tend to show stronger publisher-community agreement because there is less ambiguity between “can physically play” and “can strategically engage.”

Age with Expansions

Expansions can change age recommendations. Pandemic Legacy: Season 1 is publisher-rated at 13+ while the base Pandemic is 8+ – the legacy campaign introduces mature themes (permanent city destruction, character death, narrative tension) and requires a sustained multi-session commitment that raises the appropriate age significantly.

Age changes are modeled through the same property delta system as player count and play time:

• PropertyModification: An expansion can set a new min_age value (e.g., Pandemic Legacy: Season 1 sets min_age to 13).
• ExpansionCombination: An explicit combination record can include an effective_min_age when the combined age recommendation has been community-verified.

Multi-expansion combination ages are not assumed from individual expansion data. The system only includes effective_min_age when the value has been explicitly curated – it does not guess from individual expansion ages.

When effective mode is enabled, age filtering considers expansion-modified recommendations where available.

OpenTabletop’s Approach

Input Contract

The age recommendation model follows the specification’s Input Contract principles:

Data Provenance

Community age polls reflect the voting community’s perspective – predominantly experienced hobbyist gamers who may assess age appropriateness differently from parents, educators, or child development specialists. A hobbyist who taught their 8-year-old Pandemic may vote “8” based on their child’s specific aptitude, while a parent browsing for family games may have a more conservative threshold.

The raw vote distribution enables consumers to apply their own interpretive thresholds appropriate to their audience. See Data Provenance & Bias for more on how community data is shaped by who contributes it.

Identifiers

Every entity in the OpenTabletop data model has two native identifiers and can carry any number of external cross-references. This three-layer system balances machine efficiency, human readability, and interoperability with existing platforms.

UUIDv7

The primary identifier for every entity is a UUIDv7 – a universally unique identifier that embeds a millisecond-precision timestamp.

01967b3c-5a00-7000-8000-000000000001
└─────────┘
 timestamp

Why UUIDv7

• Time-sortable. UUIDv7s sort chronologically by creation time. This means database indexes on primary keys are naturally ordered, IDs in paginated results have a meaningful sequence, and you can extract the approximate creation time from any ID without a database lookup.
• Globally unique. No coordination between servers is needed to generate IDs. Any implementation can mint UUIDv7s independently with negligible collision probability.
• No information leakage. Unlike sequential integer IDs, you cannot determine how many entities exist by looking at an ID. An ID of 01967b3c-5a00-7000-8000-000000000001 does not tell you whether this is the first game or the hundred-thousandth.
• Standard format. UUIDv7 is defined in RFC 9562 and supported by every major language and database.

UUIDv4 was considered but rejected because it is not time-sortable, which degrades B-tree index performance and makes keyset pagination less efficient. Integer auto-increment was considered but rejected because it leaks entity counts, creates coordination requirements in distributed systems, and makes cross-system merging difficult.

Slugs

Every entity also has a slug – a human-readable, URL-safe identifier:

twilight-imperium
war-of-the-ring
reiner-knizia
days-of-wonder

Slug Rules

• Lowercase ASCII letters, digits, and hyphens only
• No leading or trailing hyphens
• No consecutive hyphens
• Maximum 100 characters
• Unique within each entity type (a Game slug and a Person slug may collide, but two Game slugs may not)
• Immutable after creation (if a game is renamed, the slug stays the same; an alias may be added)

Why Both

UUIDv7 is for machines. Slugs are for humans. Both are valid lookup keys:

GET /games/01967b3c-5a00-7000-8000-000000000001
GET /games/twilight-imperium

Both return the same Game entity. The API accepts either form wherever a game identifier is expected. Internally, the slug resolves to the UUIDv7 and all storage and indexing uses the UUID.

Slugs appear in URLs, documentation, examples, and conversation. UUIDv7s appear in machine-to-machine communication, foreign keys, and bulk operations.

External Identifiers

The Identifier entity stores cross-references to external systems:

Known Sources

The source field is an open vocabulary – new sources can be added without a specification change. The known sources above are documented as conventions, not an exhaustive list.

Lookup by External ID

GET /games?identifier_source=bgg&identifier_value=233078

Returns the OpenTabletop Game entity that maps to BGG thing ID 233078 (Twilight Imperium: Fourth Edition). This is essential for migration: applications moving from BGG’s API can look up their existing BGG IDs to find the corresponding OpenTabletop UUIDs.

Multiple External IDs

A single game can have multiple identifiers from the same source. This handles cases like:

• A game listed separately on BGG for different editions (original and revised)
• Multiple ISBNs for different printings
• Regional EAN/UPC codes

{
  "id": "01967b3c-5a00-7000-8000-000000000001",
  "slug": "twilight-imperium",
  "identifiers": [
    { "source": "bgg", "external_id": "233078" },
    { "source": "bga", "external_id": "twilightimperium" },
    { "source": "ean", "external_id": "0841333106652" },
    { "source": "wikidata", "external_id": "Q1748930" }
  ]
}

Identifier Stability

OpenTabletop identifiers (UUIDv7 and slug) are permanent. Once assigned, they never change and are never reused. If a game is removed from the database, its IDs are retired – they will return a 410 Gone response, not a 404, and will never be assigned to a different entity.

External identifiers may change if the external system reassigns them, but the OpenTabletop cross-reference is updated to reflect the current state. Historical mappings may be preserved with a deprecated flag in future specification versions.

Data Provenance & Bias

Every number in a board game database is somebody’s opinion. Weight, playtime, ratings, player count recommendations – none of these are intrinsic properties of a game. They are perceptions, shaped by who measured them, how they measured, and what they compared against. The OpenTabletop specification is designed with this reality in mind.

Two Layers of Subjectivity

Board game data has two distinct sources, and both are subjective:

Layer 1: Designer Intent

The values printed on the box – player count range, play time, recommended age – come from the designer and playtesters. These are educated estimates made by a small group of people deeply familiar with the game, often in controlled testing conditions:

• Playtime is estimated during playtesting, typically with experienced players who know the rules. First-time players, groups prone to analysis paralysis, or players unfamiliar with the genre may take 50-200% longer.
• Player count is what the designer validated the rules for. Whether the game is good at those counts is a separate question the designer may not be positioned to answer objectively.
• Age recommendation reflects the designer’s judgment about cognitive complexity, not a rigorous developmental assessment.

These values are useful as a baseline, but they represent a single data point from a specific (and non-representative) group.

Layer 2: Community Perception

Community-sourced data – weight ratings, play time logs, player count polls, game ratings – comes from voters on platforms like BoardGameGeek. This data has several structural biases:

• Self-selection. The people who rate games, log plays, and vote on player counts are not a random sample of “gamers.” They are engaged hobbyists who spend time on board game websites – a population that, on platforms like BGG, skews toward experienced, Western, English-speaking enthusiasts. OpenTabletop’s design as a specification (not a single platform) enables multiple independent communities to maintain their own voting populations. A Japanese implementation reflects Japanese gamer preferences; a German implementation reflects German preferences. The bias is a property of who contributes to a specific instance, not the specification itself.
• Experience asymmetry. Experienced players are overrepresented. Someone who has played Everdell 50 times contributes the same one vote as someone who played it once. But their perception of weight and playtime will be very different.
• Recency and novelty. Games get the most votes shortly after release, when excitement is high. Ratings may drift downward (or upward) as the initial enthusiasm fades and more critical voices weigh in.
• Cultural context. Different gaming cultures value different things. The German-speaking eurogame community, the American thematic/Ameritrash community, the East Asian gaming community, and the wargaming community would each produce different top-100 lists, different weight calibrations, and different player count recommendations.

What This Means for Specific Metrics

Ratings Are Taste

A game rated 8.3 is not objectively “better” than one rated 7.8. Ratings reflect the intersection of game design and voter population preferences. The BGG top 100 is a popularity contest within a specific demographic – experienced hobbyist gamers who self-select into an English-language board game community and spend time rating games.

Different populations would produce entirely different top-100 lists:

• Families with young children would elevate accessible, shorter games.
• Wargamers would surface hex-and-counter simulations that rarely appear on BGG’s overall rankings.
• Party gamers would rank social deduction and word games much higher.
• Non-Western markets would include games with limited distribution in North America and Europe.

None of these lists would be more “correct” than any other. They would each accurately reflect their community’s preferences. Because OpenTabletop is a specification – not a centralized platform – these different communities can each run conforming servers with their own data, producing population-specific rankings that honestly represent their audience rather than pretending to be universal.

Weight Is Perceptual

A game does not “have” a weight of 3.86. A specific population of voters rated it 3.86. This number is a useful signal – it tells you where that community places the game on a complexity spectrum – but it is not an intrinsic property of the game.

Consider Everdell. An experienced strategy gamer who plays heavy euros might rate it 2.0 (“light – straightforward tableau building with limited interaction”). A casual gamer encountering it for the first time might rate it 4.0 (“complex – many card combos, resource types, and seasonal timing to track”). Both are valid assessments from different reference frames.

The specification exposes weight as a vote distribution, not just an average, precisely because the distribution tells a richer story. A bimodal distribution (many 2.0 votes and many 4.0 votes) signals genuine disagreement about complexity – likely because the voter population spans different experience levels.

Player Count Ratings Are Population-Dependent

When the community rates Everdell at 4.8/5 at 2 players and 2.9/5 at 4 players, those ratings reflect the priorities of experienced BGG voters who value low downtime and tight resource competition. A casual group playing for the aesthetics and card combos might find 4-player Everdell perfectly enjoyable – their threshold for “too much downtime” may be different.

The specification stores raw vote distributions so that consumers can apply their own interpretive thresholds. An app targeting hardcore gamers might use stricter thresholds for “recommended”; a family-oriented app might use looser ones.

Playtime Is Contextual

The same game at the same player count can take wildly different amounts of time depending on:

• Player experience. First plays routinely take 1.5-2x longer than experienced plays. The specification’s experience-adjusted playtime model (ADR-0034) addresses this, but even within experience levels there is high variance.
• Analysis paralysis. Some groups deliberate every decision; others play on instinct. A “90 minute game” can take 45 minutes with fast players or 3 hours with deliberative ones.
• Teaching overhead. A play session that includes rules explanation can double the total time. Community play logs rarely distinguish “time spent teaching” from “time spent playing.”
• Group dynamics. Social conversation, side discussions, food breaks – all extend real-world play time in ways that are culturally variable and not captured by any logging system.

Community play time data provides a more detailed picture than publisher estimates, but it still reflects the play patterns of people who log their games – who tend to be more experienced hobbyist gamers playing with other experienced gamers.

Age Recommendations Are Culturally Variable

A publisher’s “14+” rating and a community’s “12” recommendation both reflect specific cultural assumptions about what children can handle. A European gaming family may consider a 10-year-old ready for medium-weight strategy; an American parent may draw the line at 14. Neither is wrong – they apply different thresholds for cognitive challenge, thematic content, and session length tolerance.

The specification stores both publisher-stated and community-assessed ages as independent data points. See Age Recommendation Model.

Why the Specification Exposes Distributions

This is the philosophical core of Pillar 3: Statistical Foundation. By exposing raw vote distributions, percentiles, and per-player-count breakdowns, the specification lets consumers decide how to interpret the data for their own audience.

The specification does not say “this game is heavy.” It says “here is how N people voted on complexity – here is the distribution, the mean, the spread.” An application serving experienced eurogamers can interpret that distribution differently than an application helping families find game-night picks.

The raw data is the foundation. The interpretation belongs to the consumer.

Input Contract

Every voter-facing data collection point in the specification – ratings, weight, player count quality, playtime, age recommendations – must follow an input contract that ensures the data is interpretable before any statistical model touches it. If voters don’t understand what they’re being asked, no amount of mathematical sophistication fixes the resulting data.

The Four Principles

1. The question must be unambiguous. The voter must know exactly what they’re rating. “Rate this game” is insufficient – rate what about it? Each model doc specifies the exact question to present.

2. The scale must be defined and visible at input time. Anchor definitions (what does 1 mean? what does 5 mean?) must be shown to the voter before they vote, not buried in documentation. Scale calibration reduces the variance caused by voters interpreting numbers differently.

3. The voter’s context must be captured as metadata. Declared scale preference (if the model supports it), experience level with this specific game, number of plays, and any other relevant context – recorded alongside the vote, not inferred after the fact. Context is the normalization key.

4. What happens with the data must be transparent. If a vote is normalized, weighted, or adjusted, the voter should understand how. “Your 4/5 is recorded as 8/10 on the canonical scale because you declared a 1-5 preference” – not a black box.

Per-Model Contracts

Each community-input model defines its own specific input contract:

Voter Context and the Player Entity

The context captured per-vote (declared scale, experience level, play count) is a subset of the voter’s persistent profile. When a voter has a Player entity, their declared preferences (rating scale, experience level) are stored once and applied across all their votes – they don’t need to re-declare their scale preference every time they rate a game.

For anonymous votes (no linked Player entity), per-vote context metadata is still captured where possible, but lacks the longitudinal continuity that a Player profile provides. See Players & Collections for how the Player entity connects to each model’s input contract and enables corpus-based analysis.

Implications for Implementations

Conforming implementations should consider data provenance when serving their users:

• Be transparent about sources. If weight data comes from BGG, say so. If it comes from a different community (a Japanese board game site, a wargaming forum), that context matters for interpretation.
• Consider your audience. If your implementation serves casual/family gamers, BGG-sourced weight ratings may not align with your users’ perceptions. Providing your own community’s weight data alongside BGG-sourced data lets users see both perspectives.
• Don’t conflate sample size with accuracy. More votes does not mean “more correct” – it means more precise within that population. 10,000 votes from experienced eurogamers still only tells you what experienced eurogamers think.
• Expose the distribution. The specification’s data structures are designed for distributional data precisely so that downstream consumers can make informed interpretations. Collapsing a distribution to a single number loses the signal that matters most: the shape of disagreement.

Materialization

The OpenTabletop data model separates raw input data from materialized aggregates. This is a deliberate architectural decision, not an implementation detail. Understanding the two tiers explains why certain fields on the Game entity are not computed in real time, when they refresh, and how they relate to the snapshot infrastructure described in ADR-0036.

Two Data Tiers

Tier 1: Raw Input Data

Raw input data is the individual, immutable records submitted by users and communities:

• Rating votes – Individual 1-10 ratings with voter-declared scale preference (see Rating Model)
• Weight votes – Individual 1.0-5.0 complexity votes (see Weight Model)
• Play logs – Individual session records with duration, player count, and experience level
• Player count poll responses – Per-count best/recommended/not-recommended votes (see Player Count Model)
• Age poll votes – Individual suggested-age votes
• Collection records – Per-user ownership, wishlist, and play status entries

These records are append-only. A new rating vote is inserted; it does not update a running total in place. This preserves the full distribution for statistical analysis and makes the raw data exportable (Pillar 3).

Tier 2: Materialized Aggregates

Materialized aggregates are the derived fields that appear on the Game entity and related responses. They are computed periodically from Tier 1 data:

• Averages, counts, and distributions (e.g., average_rating, rating_distribution)
• Confidence scores that depend on global statistics
• Rankings that are relative to the entire dataset
• Bayesian priors that use global parameters
• Derived fields like top_player_counts and experience multipliers

These fields are read-optimized snapshots of computations over the raw data. They are not updated on every write to Tier 1.

Why Not Real-Time

Computing aggregates on every incoming vote is wasteful and, for several fields, architecturally impossible without full table scans:

• rating_distribution across 50,000 votes requires reading every vote to build the histogram. Recomputing this on every new vote is O(n) per write instead of O(1).
• rating_confidence depends on the global mean across all games – a single new vote on one game could theoretically shift the confidence score of every other game. Recomputing globally on every write is infeasible.
• rank_overall is a relative ordering of all games by bayes_rating. A single new vote that changes one game’s Bayesian average requires re-sorting and re-ranking the entire dataset.
• bayes_rating uses a Dirichlet prior whose parameters are derived from the global rating distribution. The prior itself is a materialized value.
• Experience multipliers require grouping play logs by experience level and computing per-level medians – an aggregation over the full play log table.

Batch materialization converts these from O(n) per write to O(n) per scheduled run, amortized across all writes in the interval. For a dataset with thousands of votes per day, this is the difference between seconds of compute per vote and seconds of compute per day.

Materialization Schedule

The recommended default is daily materialization. This balances freshness against compute cost:

The updated_at field on the Game entity indicates when aggregates were last refreshed. API consumers can check this timestamp to assess staleness. An updated_at of yesterday means the aggregates reflect all votes through yesterday’s materialization run; votes submitted today are in Tier 1 but not yet reflected in Tier 2.

Field-to-Source Mapping

Every materialized field on the Game entity traces back to a specific raw data source and a defined computation:

For the detailed specification of each field, see: Rating Model, Weight Model, Player Count Model, Play Time Model.

Data Flow

The materialization pipeline is a scheduled batch process that reads Tier 1, computes Tier 2, and writes the results back to the Game entity:

flowchart LR
    subgraph "Tier 1: Raw Input Data"
        RV["Rating Votes"]
        WV["Weight Votes"]
        PL["Play Logs"]
        PC["Player Count Polls"]
        AP["Age Poll Votes"]
        CL["Collections"]
    end

    MJ["Materialization Job<br/><i>(daily cron)</i>"]

    subgraph "Tier 2: Materialized Output"
        GA["Game Entity<br/>Aggregates"]
        GS["GameSnapshot<br/><i>(ADR-0036)</i>"]
    end

    RV --> MJ
    WV --> MJ
    PL --> MJ
    PC --> MJ
    AP --> MJ
    CL --> MJ
    MJ --> GA
    MJ --> GS

    style MJ fill:#f57c00,color:#fff
    style GA fill:#388e3c,color:#fff
    style GS fill:#1976d2,color:#fff

GameSnapshot as Materialization Artifact

The GameSnapshot schema exists to enable longitudinal trend analysis – tracking how a game’s rating, rank, and activity metrics change over time. The materialization job is the natural place to capture these snapshots.

When the daily materialization runs:

1. Raw votes are aggregated into the Game entity’s materialized fields (Tier 2).
2. The freshly-computed aggregates are copied into a new GameSnapshot record timestamped to the current run.

The snapshot is the materialized state at that point in time. There is no separate “snapshot job” – the snapshot is a side effect of materialization. This guarantees that the snapshot’s average_rating, bayes_rating, rank_overall, and other fields are internally consistent (they were all computed from the same Tier 1 state in the same run).

This also means snapshot frequency is tied to materialization frequency. If you materialize daily, you get daily snapshots. If you materialize weekly, you get weekly snapshots. The Trend Analysis documentation covers how these snapshots power longitudinal queries.

For implementations that want less frequent snapshots (e.g., monthly) but daily materialization, the job can conditionally emit a snapshot only on the first run of each month. The materialization itself still runs daily to keep Game entity aggregates fresh.

Pillar 2: Filtering & Windowing

Filtering is the showcase feature of OpenTabletop. The data model defines what the data looks like; filtering defines how you ask questions of it. And the questions people actually want to ask – the ones they cannot answer today – are multi-dimensional.

The Problem

It is game night. You have 4 people, about 90 minutes, and your group prefers medium-weight cooperative games. One person does not like space themes. You want suggestions.

Today, there is no way to answer this question with a single query to any existing board game service:

• BGG’s XML API2 supports collection-status filters (owned, want to trade, wishlist, rated, played) and personal rating filters (min/max rating, min/max BGG rating, min/max plays) on the Collection endpoint. The Search endpoint only filters by name and type. But there are no game-property filters – you cannot query by player count, play time, weight, mechanics, or theme via the API. To find “cooperative games for 4 players under 90 minutes,” you must fetch all games and filter client-side.
• BGG’s advanced search (on the website, not the API) supports some game-property filters, but they cannot be combined effectively. You cannot filter by “best at 4” vs “supports 4.” You cannot exclude themes. You cannot use community play times.
• Board Game Atlas had limited filtering before it shut down. It supported player count and play time but not weight, not mechanics combinations, and not expansion-aware effective mode.

The result is that every board game recommendation app, collection manager, and “what should we play” tool either builds its own filtering on top of scraped data or punts the problem to the user with a spreadsheet.

What the OpenTabletop Specification Enables

OpenTabletop defines nine filter dimensions that compose using boolean logic, ordered to match the Pillar 1 data model:

flowchart LR
    subgraph Input
        Q["Search Query"]
    end

    subgraph Dimensions
        D1["Rating & Confidence"]
        D2["Weight"]
        D3["Player Count"]
        D4["Play Time"]
        D5["Age"]
        D6["Game Type & Mechanics"]
        D7["Theme"]
        D8["Metadata"]
        D9["Corpus (aspirational)"]
    end

    subgraph Logic
        AND["Cross-dimension: AND"]
        OR["Within dimension: OR"]
    end

    subgraph Output
        R["Filtered Results"]
    end

    Q --> D1
    Q --> D2
    Q --> D3
    Q --> D4
    Q --> D5
    Q --> D6
    Q --> D7
    Q --> D8
    Q --> D9

    D1 --> AND
    D2 --> AND
    D3 --> AND
    D4 --> AND
    D5 --> AND
    D6 --> AND
    D7 --> AND
    D8 --> AND
    D9 --> AND

    AND --> R

Each dimension can contain multiple criteria (combined with OR logic within the dimension), and all active dimensions are combined with AND logic across dimensions. See Dimension Composition for the full boolean model.

The Key Differentiators

1. Rating confidence. Filter not just by rating value but by rating reliability. A confidence score (0-1) captures whether a rating is trustworthy or the product of brigading, tiny sample size, or extreme polarization. See Rating Model.

2. Dimensional weight. Filter by composite weight or by individual dimensions – “high strategic depth but low fiddliness” separates good complexity from tedious bookkeeping. See Weight Model.

3. Community-aware player count. Filter by “supports 4” OR “highly rated at 4” OR “acceptable at 4.” These are three different questions with three different answer sets, using numeric per-count ratings rather than categorical buckets. See Player Count Model.

4. Dual play time sources. Filter by publisher-stated time or community-reported time, with experience-level adjustment. “Show me games where a first play fits in 2 hours” is a real query. See Play Time Model.

5. Expansion-aware effective mode. The effective=true flag searches across expansion combinations. A game that only supports 4 players in its base form but supports 6 with an expansion will appear in a players=6&effective=true search. No other API can do this. See Effective Mode.

6. Age recommendation sources. Filter by publisher-stated age or community-suggested age. Publisher ages tend to be conservative; community data provides an alternative view. See Age Recommendation Model.

7. Theme exclusion. Not just “include cooperative games” but “exclude space-themed games.” Negative filters are first-class. See Filter Dimensions.

8. Mechanic composition. Find games that have ALL of a set of mechanics (mechanics_all=["cooperative", "hand-management"]) or ANY of a set (mechanics=["cooperative", "hand-management"]). See Filter Dimensions.

9. Single endpoint, JSON body. Complex queries use POST /games/search with a JSON body instead of URL parameter soup. See Search Endpoint.

10. Corpus-based filtering (aspirational). “What do players like me think?” – filter by player archetype or collection similarity, enabled by the Player entity.

The Game Night Query

The scenario from the introduction, as an actual API call:

POST /games/search HTTP/1.1
Content-Type: application/json

{
  "players": 4,
  "playtime_max": 90,
  "playtime_source": "community",
  "weight_min": 2.0,
  "weight_max": 3.5,
  "mechanics": ["cooperative"],
  "theme_not": ["space"],
  "sort": "rating_desc",
  "limit": 20
}

This query asks: “Find games that support exactly 4 players, with community-reported play time under 90 minutes, at medium weight (2.0-3.5), using cooperative mechanics, excluding space-themed games, sorted by rating, top 20 results.”

Every parameter maps to a specific filter dimension. Every dimension is documented with its full parameter reference in Filter Dimensions. The way they combine is documented in Dimension Composition. Real-world scenarios with full request/response examples are in Real-World Examples.

Filter Dimensions

The filtering system is organized into nine dimensions, ordered to match the Pillar 1 data model sequence. Each dimension addresses a distinct aspect of the query, and they combine using the composition rules described in Dimension Composition.

Dimension 1: Rating & Confidence

Filter games by community rating quality and reliability.

Notes:

• rating_min=7.0&min_rating_votes=1000 finds well-rated games with enough votes to be statistically meaningful.
• confidence_min=0.7 filters out games with unreliable ratings (brigaded, too few votes, or highly polarized). See the pre-release brigading case study for why this matters.
• Confidence captures what vote count alone cannot: a game with 500 votes and std dev 4.0 has low confidence despite a reasonable sample size.

Dimension 2: Weight (Complexity)

Filter games by their community-voted complexity score.

Notes:

• weight_min=2.0&weight_max=3.5 selects “medium weight” games – substantial decisions without being overwhelming.
• Weight is a community-voted value on a 1.0-5.0 scale. See Weight Model for the scale interpretation and known limitations.
• Games with fewer than a configurable threshold of weight votes (default: 30) can be excluded with min_weight_votes=30.

Dimensional Weight Filters (Implementation-Dependent)

Implementations that support the detailed weight mode may expose per-dimension filters:

These enable queries like “high strategic depth but low fiddliness” – separating good complexity from tedious bookkeeping. These parameters are optional – only available if the implementation collects dimensional weight data.

Dimension 3: Player Count

Filter games by how many people can play them.

Semantics:

Notes:

• players=4 means “supports exactly 4 players” – the game’s range includes 4.
• top_at=4 means “the community rates the 4-player experience highly.” This is a much smaller set than players=4. The threshold is implementation-defined (e.g., 4.0+/5).
• recommended_at=4 is broader than top_at=4 – it includes games where 4 is acceptable but not necessarily the sweet spot. The threshold is implementation-defined (e.g., 3.0+/5).
• players_min=3 returns games that require 3+ players (excludes solo and 2-player games). players_max=4 returns games that cap at 4 or fewer (excludes 5+ player games).
• Per-count ratings use the numeric model from ADR-0043. Legacy BGG three-tier data (Best/Recommended/Not Recommended) is converted to numeric ratings for filtering. See Player Count Model.

Dimension 4: Play Time

Filter games by how long they take to play.

Notes:

• playtime_max=90 with playtime_source=publisher matches games where the publisher’s max_playtime <= 90.
• playtime_max=90 with playtime_source=community matches games where community_max_playtime <= 90.
• You can use community_playtime_max directly instead of the playtime_source toggle for explicit control.
• When effective=true, play time considers expansion combinations. See Effective Mode.
• playtime_experience=first_play adjusts game times upward before comparison. A game with community max 90 min and a 1.5x first-play multiplier is treated as 135 min for filtering. This composes with playtime_source and effective=true: source is selected first, then expansion resolution, then experience adjustment, then comparison.

Dimension 5: Age Recommendation

Filter games by age appropriateness.

Notes:

• age_max=10 with age_source=publisher matches games where the publisher’s min_age <= 10.
• age_max=10 with age_source=community matches games where community_suggested_age <= 10.
• You can use community_age_max directly instead of the age_source toggle for explicit control.
• Publisher age recommendations tend to be conservative (see Age Recommendation Model). Community age data provides an alternative perspective based on actual play experience.

Dimension 6: Game Type & Mechanics

Filter by the game’s type discriminator and its mechanical classification.

Notes:

• type defaults to ["base_game", "standalone_expansion"] because most queries want playable games, not individual expansions or promos.
• mechanics=["cooperative", "deck-building"] matches games with cooperative OR deck-building (or both).
• mechanics_all=["cooperative", "hand-management"] matches games with BOTH cooperative AND hand-management.
• mechanics_not=["player-elimination"] excludes games with player elimination.
• These three mechanic parameters can be combined: mechanics_all=["cooperative"]&mechanics_not=["dice-rolling"] finds cooperative games that do not use dice.

Dimension 7: Theme

Filter by thematic setting.

Notes:

• theme=["fantasy", "mythology"] matches games themed around fantasy OR mythology.
• theme_not=["space"] excludes all space-themed games.
• Theme inclusion and exclusion can be combined: theme=["historical"]&theme_not=["war"] finds historical games that are not war-themed.

Dimension 8: Metadata

Filter by publication metadata and creators.

Notes:

• designer=["cole-wehrle"] finds all games by Cole Wehrle.
• year_min=2020&year_max=2025 finds games published in the 2020s.
• family=["pandemic"] finds all games in the Pandemic family, regardless of type.
• language_dependence=["no_text", "some_text"] finds games playable without significant language knowledge – useful for international groups or non-native speakers.

Dimension 9: Corpus & Archetype (Aspirational)

Filter by player population or behavioral archetype. This dimension is enabled by the Player entity and represents a fundamentally new kind of filtering: “what do players like me think?” rather than “what does the undifferentiated crowd think?”

Example queries:

• corpus=similar_to_player:01912f4c-a1b2&corpus_rating_min=4.0 – “games rated 4.0+ by players whose collection resembles mine”
• corpus=archetype:solo-gamer&top_at=1 – “games solo gamers rate highly at 1 player”

Status: This dimension is aspirational. The Player entity and archetype model define the data structures that make it possible, but the query syntax and implementation details are future RFC topics. Implementations may experiment with corpus-based filtering before the syntax is formally specified.

Sorting

Results can be sorted by:

Default sort is rating_desc.

Pagination

All filtered results are paginated using keyset cursors. See Pagination.

Dimension Composition

Filter dimensions compose using a simple, predictable boolean model. The rules are:

• Cross-dimension: AND. All active dimensions must be satisfied. A game must match the player count filter AND the play time filter AND the weight filter AND every other active dimension.
• Within dimension: OR. Multiple values within a single dimension are combined with OR logic. theme=["fantasy", "mythology"] matches games with fantasy OR mythology.
• Exclusion: NOT. Parameters ending in _not exclude matches. theme_not=["space"] removes all space-themed games from the result set.

The Filter Pipeline

flowchart TD
    ALL["All Games in Database"]

    subgraph "Dimension Filters (AND across dimensions)"
        RC["Rating & Confidence<br/><i>rating_min, confidence_min</i>"]
        W["Weight<br/><i>weight_min, weight_max</i>"]
        PC["Player Count<br/><i>players, top_at, recommended_at</i>"]
        PT["Play Time<br/><i>playtime_min, playtime_max</i>"]
        AG["Age<br/><i>age_min, age_max</i>"]
        TM["Game Type & Mechanics<br/><i>type, mechanics, mechanics_not</i>"]
        TH["Theme<br/><i>theme, theme_not</i>"]
        MD["Metadata<br/><i>designer, publisher, year, etc.</i>"]
    end

    SORT["Sort"]
    PAGE["Paginate"]
    OUT["Response"]

    ALL --> RC
    RC --> W
    W --> PC
    PC --> PT
    PT --> AG
    AG --> TM
    TM --> TH
    TH --> MD
    MD --> SORT
    SORT --> PAGE
    PAGE --> OUT

The pipeline is conceptual – the actual database query optimizes the execution order. But the logical behavior is as if each dimension filters the result set in sequence, with every game needing to pass all active filters.

Within-Dimension OR

When a dimension accepts an array of values, those values are combined with OR:

{
  "mechanics": ["cooperative", "solo"],
  "theme": ["fantasy", "nature"]
}

This matches games that have (cooperative OR solo mechanics) AND (fantasy OR nature theme). It does NOT require a game to have both cooperative and solo mechanics – any one match within the dimension is sufficient.

Within-Dimension AND

For mechanics specifically, the mechanics_all parameter switches to AND logic:

{
  "mechanics_all": ["cooperative", "hand-management", "area-control"]
}

This matches only games that have ALL THREE mechanics. This is a much narrower filter.

Combining OR and AND

mechanics (OR), mechanics_all (AND), and mechanics_not (NOT) can all be used together:

{
  "mechanics": ["deck-building", "bag-building"],
  "mechanics_all": ["cooperative"],
  "mechanics_not": ["dice-rolling"]
}

This reads as: “Games that have (deck-building OR bag-building) AND have cooperative AND do NOT have dice-rolling.”

In predicate logic:

(deck-building OR bag-building) AND cooperative AND NOT dice-rolling

Cross-Dimension AND

Every active dimension must be satisfied:

{
  "players": 4,
  "playtime_max": 90,
  "weight_min": 2.0,
  "weight_max": 3.5,
  "mechanics": ["cooperative"],
  "theme_not": ["space"]
}

A game appears in the results only if ALL of these are true:

1. It supports 4 players (player count dimension)
2. Its play time is at most 90 minutes (play time dimension)
3. Its weight is between 2.0 and 3.5 (weight dimension)
4. It has the cooperative mechanic (mechanics dimension)
5. It does NOT have the space theme (theme dimension)

If any single dimension fails, the game is excluded.

Inactive Dimensions

A dimension that has no parameters set is inactive and matches everything. If you only specify players=4, then rating, weight, play time, age, mechanics, theme, and metadata are all unconstrained – every game that supports 4 players is returned regardless of those other properties.

Effective Mode Interaction

When effective=true, the player count, play time, and weight dimensions expand their search to include expansion combinations. This does not change the composition rules – it changes the data that each dimension searches against. Instead of checking only the base game’s properties, the filter also checks all known ExpansionCombination entries for that game.

See Effective Mode for the full explanation.

Edge Cases

Empty array parameters. An empty array ("mechanics": []) is treated as an inactive filter, not as “no mechanics.” If you want games with literally no mechanics tagged, use a dedicated parameter (not yet specified; this is a future consideration).

Conflicting constraints. weight_min=4.0&weight_max=2.0 is a valid query that returns zero results. The API does not reject logically impossible combinations – it returns an empty result set.

Null fields. Games missing a field (e.g., no community play time data) are excluded from filters on that field unless a fallback is specified. A game with no community_max_playtime will not appear in community_playtime_max=90 results, even if its publisher play time is under 90 minutes. The two data sources are independent.

Effective Mode

Effective mode is the feature that distinguishes OpenTabletop from every other board game API. When effective=true, the filtering system does not just search base game properties – it searches across all known expansion combinations.

The Problem Effective Mode Solves

Spirit Island supports 1-4 players in its base form. If you search for games that support 6 players, Spirit Island does not appear. But if you own Spirit Island and the Jagged Earth expansion, you can play with 6 people. The data exists – Jagged Earth adds support for 5-6 players – but no API exposes it as a searchable property.

Effective mode bridges this gap. With effective=true, the query:

{
  "players": 6,
  "effective": true
}

will return Spirit Island because the system knows that the Spirit Island + Jagged Earth combination supports 6 players.

How It Works

The effective properties resolution pipeline has four stages, applied in order:

flowchart TD
    Q["Query: players=6, effective=true"]

    subgraph "Resolution Pipeline"
        E["(1) Select edition"]
        ED["(2) Apply edition deltas"]
        EX["(3) Apply expansion resolution"]
        XP["(4) Apply experience adjustment"]
    end

    subgraph "Filter evaluation"
        BG["Check resolved properties: max_players >= 6?"]
    end

    Q --> E
    E --> ED
    ED --> EX
    EX --> XP
    XP --> BG
    BG -->|Yes| INCLUDE["Include in results"]
    BG -->|No| EXCLUDE["Exclude from results"]

    style INCLUDE fill:#388e3c,color:#fff
    style EXCLUDE fill:#d32f2f,color:#fff

For each game in the database, effective mode:

1. Selects the edition. If the query specifies an edition parameter, that edition’s deltas are used. Otherwise the canonical edition (marked with is_canonical=true) is used. If no edition data exists, this step is a no-op.
2. Applies edition deltas to produce the edition-adjusted base properties. Edition deltas are relative to the canonical edition and modify player count, play time, weight, etc. See ADR-0035.
3. Applies expansion resolution using the edition-adjusted base as the starting point. This follows the three-tier resolution: explicit ExpansionCombination records, summed individual deltas, or base fallback.
4. Applies experience adjustment (ADR-0034) if the query includes an experience parameter, scaling playtime values by experience-level multipliers.
5. Compares the resolved properties against filter values. If any combination of edition + expansions satisfies the filter, the game is included.

What Gets Searched

Effective mode applies to four filter dimensions:

Other dimensions (rating, mechanics, theme, metadata) are not affected by effective mode – they operate on the base game’s properties regardless.

Integration modifier

By default, effective mode only considers expansions linked via expands relationships. Products linked via integrates_with – such as standalone introductory versions whose components are physically compatible with the full game – are excluded unless the consumer opts in with include_integrations=true. See the Spirit Island example for why this distinction matters.

Spirit Island Example

Suppose the database contains these expansion combinations for Spirit Island:

Rows marked (integration) only appear when include_integrations=true.

Spirit Island also has Horizons of Spirit Island, a standalone introductory version (1-3 players, weight 3.56, 60-90 min). As a standalone_expansion, Horizons has its own base properties and appears independently in non-effective searches. Its components – including five introductory spirits – are compatible with the full game via the integrates_with relationship, so Horizons spirits can be shuffled into a base Spirit Island game. These cross-product combinations are valid but opt-in: they only appear in effective mode results when include_integrations=true.

The rationale for making integrations opt-in: expands products are designed as add-ons to a specific base game, so their combinations are predictable and expected. integrates_with products are separate games whose components happen to be compatible – combining them may fundamentally change the experience in ways a casual searcher would not expect. A consumer who owns both products and wants to see all possibilities can opt in; a consumer browsing for games to buy sees only the standard expansion landscape.

Feather & Flame is a compilation that bundles both of Spirit Island’s original Promo Packs (Promo Pack 1 and Promo Pack 2) into a single product. It adds new spirits – including Finder of Paths Unseen, one of the most challenging spirits in the game – along with adversaries, fear cards, scenarios, and aspect cards. While Feather & Flame does not change player count or play time, the added complexity is reflected in its weight (4.55 vs the base game’s 4.08). This means Feather & Flame can be the reason Spirit Island matches a weight filter it would not otherwise match.

Now consider these queries:

Query: players=6 (effective=false) Spirit Island is excluded. Base game max is 4.

Query: players=6&effective=true Spirit Island is included. The “Jagged Earth”, “Nature Incarnate”, and all multi-expansion combinations that include either support 6 players.

Query: top_at=4&effective=true Spirit Island is included. The “B&C + JE”, “JE + NI”, and “B&C + JE + NI” combinations have 4 in their top_at lists.

Query: weight_min=4.4&weight_max=4.6&effective=true Spirit Island is included. Multiple combinations fall in this range: “Nature Incarnate” (4.46), “Jagged Earth” (4.52), “B&C + NI” (4.52), “Feather & Flame” (4.55), “B&C + JE” (4.56), “JE + NI” (4.60). The system returns the first matching combination.

Query: weight_min=4.55&weight_max=4.65&effective=true Spirit Island is included via “Feather & Flame” (4.55), “B&C + JE” (4.56), “JE + NI” (4.60), and “B&C + JE + NI” (4.65). Without effective mode, Spirit Island (weight 4.08) would be excluded.

Query: playtime_max=120&effective=true Spirit Island is included via the base game (max 120), the Jagged Earth combination (max 120), and the Feather & Flame combination (max 120). The Nature Incarnate combinations with max 180 would not be the matching path. The system finds the combination that satisfies the constraint.

Query: weight_max=4.0&effective=true Spirit Island is excluded. No standard expansion combination has weight <= 4.0 (the base game is 4.08). The Horizons integration combinations (3.82, 3.98) would match, but they are not searched because include_integrations defaults to false.

Query: weight_max=4.0&effective=true&include_integrations=true Spirit Island is included via the “+ Horizons” integration combination (weight 3.82). This represents a game of Spirit Island using Horizons spirits, which lowers the overall complexity. The matched_via response includes "integration": true so the consumer knows the match involves a cross-product combination.

Response Format

When effective mode produces a match through an expansion combination (not the base game), the response includes metadata about which combination matched:

{
  "id": "01967b3c-5a00-7000-8000-000000000001",
  "slug": "spirit-island",
  "name": "Spirit Island",
  "matched_via": {
    "type": "expansion_combination",
    "combination_id": "01967b3c-6000-7000-8000-000000000055",
    "expansions": [
      { "slug": "spirit-island-branch-and-claw", "name": "Branch & Claw" },
      { "slug": "spirit-island-jagged-earth", "name": "Jagged Earth" },
      { "slug": "spirit-island-nature-incarnate", "name": "Nature Incarnate" }
    ],
    "effective_properties": {
      "min_players": 1,
      "max_players": 6,
      "top_at": [2, 3, 4],
      "weight": 4.65,
      "min_playtime": 120,
      "max_playtime": 180,
      "min_age": 14
    },
    "resolution_tier": 1
  }
}

The matched_via object tells the consumer exactly how the game satisfied the filter:

• type: "base" if the base game matched, "expansion_combination" if a combination matched, "delta_sum" if individual deltas were summed.
• expansions: Which expansions are in the matching combination.
• effective_properties: The actual property values used for matching.
• resolution_tier: 1 (explicit combination), 2 (delta sum), or 3 (base fallback).

Performance Considerations

Effective mode is more expensive than standard filtering because the database must check multiple rows per game (one for each known expansion combination). The specification does not mandate a specific implementation strategy, but reference implementation notes:

• Expansion combinations are pre-computed and indexed. The query adds a JOIN, not a recursive computation.
• Games without any expansion data are checked only against their base properties (no overhead).
• The type filter defaults to ["base_game", "standalone_expansion"], which already excludes individual expansion entities from results. Effective mode searches through expansions but returns base games.

For most queries, effective mode adds modest overhead. For very broad queries (no other filters, large result sets), it may be noticeably slower. Consumers should use effective mode intentionally when expansion-aware results are needed, not as a default for every query.

Real-World Examples

Six scenarios demonstrating the filtering system in practice. Each includes the natural-language question, the API request, and an annotated response.

Example 1: Game Night – 4 Players, 90 Minutes, Medium Weight

Scenario: Four friends have 90 minutes. They want medium-weight cooperative games, no space themes.

Request:

POST /games/search HTTP/1.1
Content-Type: application/json

{
  "players": 4,
  "playtime_max": 90,
  "playtime_source": "community",
  "weight_min": 2.0,
  "weight_max": 3.5,
  "mechanics": ["cooperative"],
  "theme_not": ["space"],
  "sort": "rating_desc",
  "limit": 5
}

Response:

{
  "data": [
    {
      "id": "01967b3c-5a00-7000-8000-000000000010",
      "slug": "pandemic",
      "name": "Pandemic",
      "type": "base_game",
      "year_published": 2008,
      "min_players": 2,
      "max_players": 4,
      "community_max_playtime": 60,
      "weight": 2.42,
      "rating": 7.58
    },
    {
      "id": "01967b3c-5a00-7000-8000-000000000011",
      "slug": "the-crew-mission-deep-sea",
      "name": "The Crew: Mission Deep Sea",
      "type": "base_game",
      "year_published": 2021,
      "min_players": 2,
      "max_players": 5,
      "community_max_playtime": 25,
      "weight": 2.07,
      "rating": 8.06
    },
    {
      "id": "01967b3c-5a00-7000-8000-000000000012",
      "slug": "mysterium",
      "name": "Mysterium",
      "type": "base_game",
      "year_published": 2015,
      "min_players": 2,
      "max_players": 7,
      "community_max_playtime": 50,
      "weight": 2.18,
      "rating": 7.22
    }
  ],
  "meta": {
    "total": 87,
    "limit": 5,
    "cursor": "eyJyYXRpbmciOjcuMjIsImlkIjoiMDE5NjdiM2MifQ==",
    "filters_applied": {
      "players": 4,
      "playtime_max": 90,
      "playtime_source": "community",
      "weight_min": 2.0,
      "weight_max": 3.5,
      "mechanics": ["cooperative"],
      "theme_not": ["space"]
    },
    "sort": "rating_desc",
    "effective": false
  }
}

Why this works: Community play time is used (playtime_source: "community"), so games that publishers claim are “60 minutes” but actually take 110 are excluded. The space theme exclusion removes games like Beyond the Sun or Xia that might otherwise match mechanically.

Example 2: Solo Gaming – Heavy, Engine-Building, Recent

Scenario: A solo player wants heavy engine-building games published in the last 3 years.

Request:

POST /games/search HTTP/1.1
Content-Type: application/json

{
  "players": 1,
  "top_at": 1,
  "weight_min": 3.5,
  "mechanics_all": ["engine-building", "solo"],
  "year_min": 2023,
  "sort": "weight_desc",
  "limit": 10
}

Response:

{
  "data": [
    {
      "id": "01967b3c-5a00-7000-8000-000000000020",
      "slug": "ark-nova",
      "name": "Ark Nova",
      "type": "base_game",
      "year_published": 2023,
      "min_players": 1,
      "max_players": 4,
      "weight": 3.73,
      "rating": 8.52
    }
  ],
  "meta": {
    "total": 12,
    "limit": 10,
    "cursor": null,
    "filters_applied": {
      "players": 1,
      "top_at": 1,
      "weight_min": 3.5,
      "mechanics_all": ["engine-building", "solo"],
      "year_min": 2023
    },
    "sort": "weight_desc",
    "effective": false
  }
}

Why top_at matters: players=1 finds games that support solo play, but many of those are mediocre solo experiences (a multiplayer game with a tacked-on solo mode). top_at=1 narrows to games the community rates highly at 1 player (above the high threshold, e.g., 4.0+/5), dramatically improving recommendation quality.

Example 3: Large Group – Party Games for 6-8 People

Scenario: A group of 7 wants light party games under 30 minutes.

Request:

POST /games/search HTTP/1.1
Content-Type: application/json

{
  "players": 7,
  "playtime_max": 30,
  "weight_max": 1.5,
  "category": ["party"],
  "sort": "rating_desc",
  "limit": 10
}

Response:

{
  "data": [
    {
      "id": "01967b3c-5a00-7000-8000-000000000030",
      "slug": "codenames",
      "name": "Codenames",
      "type": "base_game",
      "year_published": 2015,
      "min_players": 2,
      "max_players": 8,
      "max_playtime": 15,
      "weight": 1.31,
      "rating": 7.58
    },
    {
      "id": "01967b3c-5a00-7000-8000-000000000031",
      "slug": "wavelength",
      "name": "Wavelength",
      "type": "base_game",
      "year_published": 2019,
      "min_players": 2,
      "max_players": 12,
      "max_playtime": 30,
      "weight": 1.08,
      "rating": 7.42
    },
    {
      "id": "01967b3c-5a00-7000-8000-000000000032",
      "slug": "just-one",
      "name": "Just One",
      "type": "base_game",
      "year_published": 2018,
      "min_players": 3,
      "max_players": 7,
      "max_playtime": 20,
      "weight": 1.00,
      "rating": 7.54
    }
  ],
  "meta": {
    "total": 43,
    "limit": 10,
    "cursor": "eyJyYXRpbmciOjcuNTQsImlkIjoiMDE5NjdiM2MifQ==",
    "filters_applied": {
      "players": 7,
      "playtime_max": 30,
      "weight_max": 1.5,
      "category": ["party"]
    },
    "sort": "rating_desc",
    "effective": false
  }
}

Example 4: Effective Mode – 6-Player Games with Expansions

Scenario: A group of 6 wants strategy games. They are willing to buy expansions if needed.

Request:

POST /games/search HTTP/1.1
Content-Type: application/json

{
  "players": 6,
  "effective": true,
  "weight_min": 2.5,
  "weight_max": 4.6,
  "category": ["strategy"],
  "sort": "rating_desc",
  "limit": 5
}

Response:

{
  "data": [
    {
      "id": "01967b3c-5a00-7000-8000-000000000001",
      "slug": "spirit-island",
      "name": "Spirit Island",
      "type": "base_game",
      "year_published": 2017,
      "min_players": 1,
      "max_players": 4,
      "weight": 4.08,
      "rating": 8.31,
      "matched_via": {
        "type": "expansion_combination",
        "expansions": [
          { "slug": "jagged-earth", "name": "Jagged Earth" }
        ],
        "effective_properties": {
          "min_players": 1,
          "max_players": 6,
          "weight": 4.52
        },
        "resolution_tier": 1
      }
    },
    {
      "id": "01967b3c-5a00-7000-8000-000000000040",
      "slug": "scythe",
      "name": "Scythe",
      "type": "base_game",
      "year_published": 2016,
      "min_players": 1,
      "max_players": 5,
      "weight": 3.42,
      "rating": 8.22,
      "matched_via": {
        "type": "expansion_combination",
        "expansions": [
          { "slug": "scythe-invaders-from-afar", "name": "Scythe: Invaders from Afar" }
        ],
        "effective_properties": {
          "min_players": 1,
          "max_players": 7,
          "weight": 3.45
        },
        "resolution_tier": 1
      }
    }
  ],
  "meta": {
    "total": 28,
    "limit": 5,
    "cursor": "eyJyYXRpbmciOjguMjIsImlkIjoiMDE5NjdiM2MifQ==",
    "filters_applied": {
      "players": 6,
      "effective": true,
      "weight_min": 2.5,
      "weight_max": 4.6,
      "category": ["strategy"]
    },
    "sort": "rating_desc",
    "effective": true
  }
}

Key insight: Neither Spirit Island (1-4p) nor Scythe (1-5p) supports 6 players in base form. Both appear because effective mode found expansion combinations that reach 6. The matched_via object tells the consumer exactly which expansions to buy.

Example 5: Designer Deep Dive – All Uwe Rosenberg Games

Scenario: A fan wants to explore all medium-to-heavy Uwe Rosenberg games sorted by year.

Request:

POST /games/search HTTP/1.1
Content-Type: application/json

{
  "designer": ["uwe-rosenberg"],
  "weight_min": 2.5,
  "type": ["base_game"],
  "sort": "year_desc",
  "limit": 20
}

Response:

{
  "data": [
    {
      "id": "01967b3c-5a00-7000-8000-000000000050",
      "slug": "a-feast-for-odin",
      "name": "A Feast for Odin",
      "type": "base_game",
      "year_published": 2016,
      "weight": 3.86,
      "rating": 8.16
    },
    {
      "id": "01967b3c-5a00-7000-8000-000000000051",
      "slug": "caverna",
      "name": "Caverna: The Cave Farmers",
      "type": "base_game",
      "year_published": 2013,
      "weight": 3.78,
      "rating": 7.90
    },
    {
      "id": "01967b3c-5a00-7000-8000-000000000052",
      "slug": "agricola",
      "name": "Agricola",
      "type": "base_game",
      "year_published": 2007,
      "weight": 3.64,
      "rating": 7.94
    }
  ],
  "meta": {
    "total": 14,
    "limit": 20,
    "cursor": null,
    "filters_applied": {
      "designer": ["uwe-rosenberg"],
      "weight_min": 2.5,
      "type": ["base_game"]
    },
    "sort": "year_desc",
    "effective": false
  }
}

Note: type: ["base_game"] excludes Rosenberg’s expansions and promos, focusing only on his standalone designs. Without this filter, results would include expansion entries for Agricola, Caverna, etc.

Example 6: First-Time Play – “We Have 2 Hours and Nobody Knows the Game”

Scenario: A group of 3 wants to try a new cooperative game tonight. They have 2 hours. They have never played whatever game they pick, so the first-play time needs to fit within 2 hours.

Request:

POST /games/search HTTP/1.1
Content-Type: application/json

{
  "players": 3,
  "playtime_max": 120,
  "playtime_source": "community",
  "playtime_experience": "first_play",
  "weight_min": 2.0,
  "weight_max": 3.5,
  "mechanics": ["cooperative"],
  "sort": "rating_desc",
  "limit": 5,
  "include": ["experience_playtime"]
}

Response:

{
  "data": [
    {
      "id": "01967b3c-5a00-7000-8000-000000000010",
      "slug": "pandemic",
      "name": "Pandemic",
      "type": "base_game",
      "year_published": 2008,
      "min_players": 2,
      "max_players": 4,
      "community_max_playtime": 60,
      "weight": 2.42,
      "rating": 7.58,
      "experience_playtime": {
        "levels": [
          { "experience_level": "first_play", "median_minutes": 75, "total_reports": 891 },
          { "experience_level": "experienced", "median_minutes": 50, "total_reports": 2104 }
        ],
        "multipliers": { "first_play": 1.50, "learning": 1.20, "experienced": 1.0, "expert": 0.90 },
        "sufficient_data": true
      }
    },
    {
      "id": "01967b3c-5a00-7000-8000-000000000080",
      "slug": "horrified",
      "name": "Horrified",
      "type": "base_game",
      "year_published": 2019,
      "min_players": 1,
      "max_players": 5,
      "community_max_playtime": 55,
      "weight": 2.02,
      "rating": 7.32,
      "experience_playtime": {
        "levels": [
          { "experience_level": "first_play", "median_minutes": 65, "total_reports": 234 },
          { "experience_level": "experienced", "median_minutes": 45, "total_reports": 567 }
        ],
        "multipliers": { "first_play": 1.44, "learning": 1.15, "experienced": 1.0, "expert": 0.92 },
        "sufficient_data": true
      }
    }
  ],
  "meta": {
    "total": 34,
    "limit": 5,
    "cursor": "eyJyYXRpbmciOjcuMzIsImlkIjoiMDE5NjdiM2MifQ==",
    "filters_applied": {
      "players": 3,
      "playtime_max": 120,
      "playtime_source": "community",
      "playtime_experience": "first_play",
      "weight_min": 2.0,
      "weight_max": 3.5,
      "mechanics": ["cooperative"]
    },
    "sort": "rating_desc",
    "effective": false
  }
}

Key insight: Spirit Island is NOT in these results. Its community max playtime is 150 minutes, and adjusted for first play (× 1.57) that is 235 minutes – well over the 2-hour budget. Pandemic fits because its first-play adjusted time (60 × 1.50 = 90 min) is within 120. The experience_playtime include shows the consumer exactly what to expect: “Pandemic will take about 75 minutes for your first game.”

Without experience adjustment, this query would have returned Spirit Island (community max 150 min > 120, still excluded) but would have included games whose experienced play time is 80 minutes but whose first play realistically takes 130+ minutes – setting up the group for a game that runs over their time budget.

Search Endpoint

The primary filtering endpoint is POST /games/search. It accepts a JSON body containing all filter parameters, sort order, and pagination controls. A GET /games endpoint with query parameters exists for simple lookups, but the POST endpoint is the recommended interface for multi-dimensional queries.

Why POST for Search

Complex filter queries involve arrays, nested parameters, and boolean logic that map poorly to URL query strings:

• mechanics=["cooperative","hand-management"]&mechanics_not=["dice-rolling"] is awkward as query parameters and ambiguous across HTTP client implementations.
• URL length limits (practical limit around 2000 characters) can be exceeded by queries with many filter values.
• JSON bodies have well-defined semantics for arrays, nulls, and nested objects.

The POST /games/search endpoint is not creating a resource – it is a query. This follows the established pattern used by Elasticsearch, Algolia, and other search APIs. The endpoint returns 200 OK, not 201 Created.

Request Schema

{
  // Dimension 1: Rating & Confidence
  "rating_min": null,
  "rating_max": null,
  "min_rating_votes": null,
  "confidence_min": null,

  // Dimension 2: Weight
  "weight_min": 2.0,
  "weight_max": 3.5,
  "effective_weight": false,
  "min_weight_votes": null,

  // Dimension 3: Player Count
  "players": 4,
  "players_min": null,
  "players_max": null,
  "top_at": null,
  "recommended_at": null,
  "effective": false,              // search across expansion combinations
  "include_integrations": false,   // include integrates_with products in effective mode
  "edition": null,                 // edition slug for edition-specific resolution

  // Dimension 4: Play Time
  "playtime_min": null,
  "playtime_max": 90,
  "community_playtime_min": null,
  "community_playtime_max": null,
  "playtime_source": "publisher",  // "publisher" or "community"
  "playtime_experience": null,     // "first_play", "learning", "experienced", "expert"

  // Dimension 5: Age Recommendation
  "age_min": null,
  "age_max": null,
  "community_age_min": null,
  "community_age_max": null,
  "age_source": "publisher",       // "publisher" or "community"

  // Dimension 6: Game Type & Mechanics
  "type": ["base_game", "standalone_expansion"],
  "mode": null,                    // shorthand: "all", "playable", "addons"
  "mechanics": ["cooperative"],    // OR logic
  "mechanics_all": null,           // AND logic
  "mechanics_not": null,           // exclusion

  // Dimension 7: Theme
  "theme": null,                   // OR logic
  "theme_not": ["space"],          // exclusion

  // Dimension 8: Metadata
  "designer": null,
  "publisher": null,
  "family": null,
  "category": null,
  "year_min": null,
  "year_max": null,
  "language_dependence": null,

  // Dimension 9: Corpus & Archetype (aspirational)
  "corpus": null,
  "corpus_rating_min": null,

  // Resource embedding
  "include": null,                 // e.g., ["mechanics", "experience_playtime"]

  // Pagination & sort
  "sort": "rating_desc",
  "limit": 20,
  "cursor": null
}

All fields are optional. Omitted or null fields are treated as inactive filters (no constraint on that dimension).

Field Types

Dimensional weight filters: Implementations that support the detailed weight mode may also accept per-dimension weight filters (weight_rules_complexity_min, weight_strategic_depth_min, etc.). See Dimensions: Dimensional Weight Filters.

GET Equivalent

For simple queries, GET /games accepts a subset of parameters as query strings:

GET /games?players=4&playtime_max=90&mechanics=cooperative&sort=rating_desc&limit=20

Array parameters use comma-separated values in GET:

GET /games?mechanics=cooperative,hand-management&theme_not=space

The GET endpoint supports all the same parameters but is less ergonomic for complex queries. Use POST when:

• You have more than 3-4 active filters
• You use array parameters with multiple values
• You use both inclusion and exclusion parameters on the same dimension
• Your query might exceed URL length limits

Response Schema

See Response Metadata for the full response structure.

Validation

The API validates the request body and returns RFC 9457 Problem Details for validation errors:

{
  "type": "https://api.opentabletop.org/errors/validation",
  "title": "Validation Error",
  "status": 422,
  "detail": "weight_min must be between 1.0 and 5.0",
  "errors": [
    {
      "field": "weight_min",
      "message": "must be between 1.0 and 5.0",
      "value": 6.0
    }
  ]
}

Validation Rules

• rating_min and rating_max must be between 1.0 and 10.0
• confidence_min must be between 0.0 and 1.0
• weight_min and weight_max must be between 1.0 and 5.0
• limit must be between 1 and 100
• type values must be valid game type discriminators
• mechanics, theme, category values must be valid slugs in the taxonomy
• playtime_source must be “publisher” or “community”
• age_source must be “publisher” or “community”
• playtime_experience must be “first_play”, “learning”, “experienced”, or “expert”
• language_dependence values must be valid dependence levels
• sort must be a valid sort key
• Unknown fields are ignored (forward compatibility)

Response Metadata

Every search response includes a meta object alongside the data array. The metadata provides pagination controls, filter echo-back, and aggregate information about the result set.

Response Structure

{
  "data": [
    { "...game object..." },
    { "...game object..." }
  ],
  "meta": {
    "total": 87,
    "limit": 20,
    "cursor": "eyJyYXRpbmciOjcuNTQsImlkIjoiMDE5NjdiM2MtNWEwMC03MDAwIn0=",
    "filters_applied": {
      "players": 4,
      "playtime_max": 90,
      "playtime_source": "community",
      "weight_min": 2.0,
      "weight_max": 3.5,
      "mechanics": ["cooperative"],
      "theme_not": ["space"]
    },
    "sort": "rating_desc",
    "effective": false,
    "include_integrations": false
  }
}

Meta Fields

FilterSummary (filters_applied)

The filters_applied object echoes back every filter that was active in the query, using the same field names as the request body. This serves two purposes:

1. Debugging. Consumers can verify that their query was interpreted correctly. If you sent playtime_source: "community" but see playtime_source: "publisher" in the response, something went wrong.
2. Permalink construction. A frontend can reconstruct the exact query from the response metadata, enabling shareable filter URLs.

Only active filters appear. Default values and null parameters are omitted:

// Request with these defaults:
{
  "type": ["base_game", "standalone_expansion"],
  "sort": "rating_desc",
  "limit": 20
}

// Response filters_applied is empty because all values are defaults:
{
  "filters_applied": {}
}

// Request with explicit non-default type:
{
  "type": ["base_game", "expansion"],
  "sort": "rating_desc"
}

// Response includes type because it differs from default:
{
  "filters_applied": {
    "type": ["base_game", "expansion"]
  }
}

Pagination

The cursor field implements keyset pagination. See Pagination for details.

• First request: omit cursor (or set to null).
• Next page: pass the cursor value from the previous response.
• Last page: cursor is null – no more results.

The cursor is an opaque string. Do not parse, construct, or modify it. Its format may change between API versions.

Total Count

The total field provides the count of all matching games, not just those on the current page. This enables UI patterns like “Showing 1-20 of 87 results.”

Computing exact totals can be expensive for very broad queries. The specification allows implementations to return an estimate for totals above a configurable threshold (default: 10,000). If the total is estimated, a boolean total_estimated field is set to true:

{
  "meta": {
    "total": 15200,
    "total_estimated": true
  }
}

For most filtered queries, the total is small enough to be exact.

Future: Facet Counts

A planned extension to the response metadata is facet counts – aggregate counts of how many results match each value of a given dimension. For example:

{
  "meta": {
    "facets": {
      "mechanics": {
        "cooperative": 87,
        "hand-management": 42,
        "deck-building": 31,
        "area-control": 18
      },
      "weight_histogram": {
        "1.0-1.5": 3,
        "1.5-2.0": 12,
        "2.0-2.5": 28,
        "2.5-3.0": 25,
        "3.0-3.5": 15,
        "3.5-4.0": 4
      }
    }
  }
}

Facet counts enable progressive filtering UIs where the user sees how many results each additional filter would produce. This is on the statistics roadmap but not in the initial specification.

Pillar 3: Statistical Foundation

The third pillar of OpenTabletop is a commitment: raw data is a first-class output. Every opinion-based data point in the system – player count polls, weight votes, community play times, expansion property modifications – is available as exportable, analyzable data. The specification does not lock consumers into one algorithm for “best player count” or one definition of “weight.” It provides the underlying distributions and lets consumers decide.

Why This Matters

Board game data is full of derived values that obscure the underlying reality:

• BGG’s “best player count” is a single number derived from poll data using an undocumented algorithm. You cannot see the vote distribution. You cannot apply a different threshold. You cannot ask “is this game controversial at 4 players?” because the raw votes are not exposed.

• BGG’s “weight” is an average. You cannot see whether the average of 3.5 comes from a bimodal distribution (half say 2.0, half say 5.0) or a consensus (everyone says 3.5). These are very different signals about a game’s complexity.

• BGG’s “geek rating” applies a Bayesian average that penalizes games with few votes. The formula is not public. You cannot recompute it, adjust it, or replace it with your own ranking system.

OpenTabletop’s position is that these derived values are useful but they belong in application logic, not in the data specification. The specification provides the raw inputs – vote distributions, individual data points, exportable collections – and lets applications build whatever derived values serve their users.

What the Statistical Foundation Provides

1. Raw Vote Distributions

Every poll-based value exposes the full vote breakdown:

• Player count polls: For each supported player count, the exact number of Best, Recommended, and Not Recommended votes. See Data Structures.
• Weight votes: The distribution of weight votes (how many people voted 1.0, how many voted 2.0, etc.), not just the average.
• Rating votes: The distribution of rating votes across the 1-10 scale.

2. Expansion Delta Data

Property modifications and expansion combinations are not just used internally for effective mode filtering – they are queryable and exportable entities. A data scientist can download all property modifications to analyze patterns like:

• “How much does adding an expansion typically increase play time?”
• “Do expansions tend to increase or decrease the best player count?”
• “Is there a correlation between expansion weight delta and expansion rating?”

3. Bulk Export

The /export endpoints provide full dataset downloads in machine-friendly formats. Every filter dimension available in the search API is also available in the export API, so you can export “all cooperative games published since 2020 with their player count polls” rather than downloading the entire database.

See Data Export for format specifications.

Design Principles

Transparency. Every derived value in the API has a documented derivation path back to raw data. If the API returns best_player_counts: [2, 3], you can look at the PlayerCountPoll data and verify the derivation yourself.

Reproducibility. Given the same raw data and the same algorithm, you should get the same derived values. The specification documents the default derivation algorithms but does not require implementations to use them.

Exportability. Data locked in an API is only half-useful. The export system ensures that researchers, analysts, and alternative implementations can work with the full dataset offline.

Composability. Export uses the same filter dimensions as search. You do not need a separate query language or data model for analytics.

Data Structures

The statistical foundation is built on specific data structures that capture community opinion as raw distributions rather than pre-computed summaries.

Player Count Ratings

The player count rating is the most important statistical data structure in the specification. For each game and each supported player count, it records a numeric community rating on a 1-5 scale – not categorical buckets, but real numbers that support standard statistical analysis. See Player Count Model for the full design rationale.

Schema

Example: Lost Ruins of Arnak

From this raw data, a consumer can derive:

• Highest rated at 2 (4.5/5 with tight consensus at std dev 0.6).
• Well-rated at 2-3: Both above 4.0, the “highly rated” threshold.
• 4 is acceptable but divisive (3.1/5 with high std dev) – the added downtime between turns divides opinion.
• Solo is middling (3.4/5) – the AI opponent is functional but lacks the competitive tension of multiplayer.

Different applications set different thresholds. A hardcore strategy app might set “recommended” at 4.0+; a family app might set it at 3.0+. The raw numeric data supports any interpretation – no fixed categories constrain the analysis.

Accessing Rating Data

GET /games/lost-ruins-of-arnak/player-count-ratings

{
  "game_id": "01967b3c-5a00-7000-8000-000000000095",
  "ratings": [
    { "player_count": 1, "average_rating": 3.4, "rating_count": 876, "rating_stddev": 1.0 },
    { "player_count": 2, "average_rating": 4.5, "rating_count": 1234, "rating_stddev": 0.6 },
    { "player_count": 3, "average_rating": 4.2, "rating_count": 1089, "rating_stddev": 0.7 },
    { "player_count": 4, "average_rating": 3.1, "rating_count": 745, "rating_stddev": 1.1 }
  ]
}

BGG Legacy Data

For data migrated from BoardGameGeek, the PlayerCountPollLegacy schema preserves BGG’s three-tier voting model (Best / Recommended / Not Recommended). This data is available via the API but is not the native model – it is maintained for backward compatibility and transparency during migration. Legacy three-tier data can be converted to approximate numeric ratings for unified querying. See Player Count Model: BGG Legacy Data.

Weight Votes

The weight field on a Game is an average. The weight vote distribution provides the underlying data.

Schema

Example: Great Western Trail

Great Western Trail’s weight is concentrated in the 3.5-4.0 range, reflecting strong agreement that the game sits firmly in the “heavy-medium” band. The tight cluster suggests voters – despite varying experience levels – perceive the game’s complexity similarly. The small tail of 1.0-2.0 votes may reflect voters who found the cattle-market loop more intuitive than the weight suggests.

A bimodal distribution (many 2.0 votes and many 4.0 votes) would suggest the game’s complexity is debated, which is useful information that an average hides.

Dimensional Weight Data

Implementations that support the detailed weight mode store per-dimension vote distributions – rules complexity, strategic depth, decision density, cognitive load, fiddliness, and game length – each rated independently on a 1-5 scale. These per-dimension distributions are exportable alongside the composite weight distribution, enabling analyses like “which games have high strategic depth but low fiddliness?” that a single composite number cannot answer.

Accessing Weight Distribution

GET /games/great-western-trail/weight-votes

{
  "game_id": "01967b3c-5a00-7000-8000-000000000090",
  "votes": {
    "1.0": 5,
    "1.5": 3,
    "2.0": 18,
    "2.5": 67,
    "3.0": 312,
    "3.5": 1489,
    "4.0": 2134,
    "4.5": 876,
    "5.0": 142
  },
  "total_votes": 5046,
  "average": 3.72
}

Rating Distribution

The average_rating on a Game is a single number that hides the distribution shape. The rating distribution exposes the full histogram of voter opinion, a confidence score, and standard deviation. See Rating Model for the four-layer rating architecture.

Schema

Example: Dune: Imperium

The distribution reveals what the average hides:

• Bell curve centered at 8-9 – strong consensus that this is a top-tier game.
• Low std dev (1.38) – voters agree. Compare to a brigaded game where std dev exceeds 3.5.
• High confidence (0.86) – large sample, tight consensus. This number is trustworthy.

A bimodal distribution (peaks at 3 and 9) would indicate a polarizing game – some love it, some hate it. The average might be 6.0 in both cases, but the distribution shape tells a completely different story.

The confidence score (0.0-1.0) synthesizes sample size, distribution shape, and deviation from the global mean into a single trust signal. See Rating Model: Confidence Score for the formula, and the pre-release brigading case study for a real-world example where confidence correctly flags a meaningless rating.

Accessing Rating Distribution

GET /games/dune-imperium/rating-distribution

{
  "game_id": "01967b3c-5a00-7000-8000-000000000091",
  "average_rating": 8.32,
  "rating_count": 42876,
  "rating_distribution": [98, 112, 245, 502, 1234, 3456, 8912, 14567, 10234, 3516],
  "rating_stddev": 1.38,
  "confidence": 0.86
}

Community Age Poll

The community age poll captures voter recommendations for the minimum appropriate age for a game. Unlike player count ratings (which use a numeric scale), age polls are simple: voters pick the minimum age they would suggest. The distribution reveals how the community’s view compares to the publisher’s box rating. See Age Recommendation Model.

Schema

The Game entity includes a derived field:

Example: Viticulture

The publisher rates Viticulture at 13+. The community sees it differently:

The community suggested age is 12 – one year lower than the publisher’s box rating. Despite the wine theme, the gameplay is abstract enough (place workers, collect resources, fill orders) that voters consider the mechanics accessible to a 12-year-old. The publisher’s conservative 13+ likely reflects the thematic subject matter rather than mechanical complexity. The gap between “thematically appropriate” and “mechanically capable” is exactly the kind of nuance the community poll captures.

Accessing Age Poll Data

GET /games/viticulture/age-poll

{
  "game_id": "01967b3c-5a00-7000-8000-000000000092",
  "community_suggested_age": 12,
  "votes": [
    { "suggested_age": 8, "vote_count": 34 },
    { "suggested_age": 10, "vote_count": 189 },
    { "suggested_age": 12, "vote_count": 312 },
    { "suggested_age": 14, "vote_count": 87 },
    { "suggested_age": 16, "vote_count": 11 }
  ],
  "total_votes": 633
}

Community Play Time Data

Community-reported play times are derived from individual play logs. The statistical foundation exposes aggregate data.

Schema

Example: Concordia

This data shows what the publisher’s single estimate cannot capture:

• The publisher says 100 minutes. The community median is 105 – unusually close for a strategy game.
• 2-player games are fast (70 min median) – Concordia scales well downward.
• 5-player games take over twice as long as 2-player (155 vs 70 min) – the scaling factor is dramatic.
• The 90th percentile is 160 minutes – some groups spend nearly 3 hours.
• The per-player-count breakdown reveals that player count is the dominant factor in play time.

Accessing Play Time Data

GET /games/concordia/community-playtime

{
  "game_id": "01967b3c-5a00-7000-8000-000000000093",
  "total_plays": 6234,
  "min_reported": 40,
  "max_reported": 240,
  "median": 105,
  "p10": 65,
  "p25": 80,
  "p75": 130,
  "p90": 160,
  "by_player_count": {
    "2": { "median": 70, "plays": 2845 },
    "3": { "median": 100, "plays": 1987 },
    "4": { "median": 125, "plays": 1134 },
    "5": { "median": 155, "plays": 268 }
  }
}

Experience Playtime Poll

The experience playtime poll captures community-reported play times bucketed by player experience level. Like PlayerCountRating, it stores raw distributions rather than pre-computed summaries. See ADR-0034.

Schema

Example: Gloomhaven: Jaws of the Lion

From this data, multipliers are derived: first_play = 120/70 = 1.71, expert = 55/70 = 0.79. This tells consumers that a first scenario of Gloomhaven: Jaws of the Lion takes 71% longer than an experienced play – the tutorial scenarios help, but the card combo system and enemy AI rules create a steep initial learning curve. By expert level, optimized play and familiar monster patterns cut session time significantly.

Accessing Experience Playtime Data

GET /games/gloomhaven-jaws-of-the-lion/experience-playtime

{
  "game_id": "01967b3c-5a00-7000-8000-000000000094",
  "levels": [
    { "experience_level": "first_play", "median_minutes": 120, "min_minutes": 90, "max_minutes": 180, "total_reports": 456 },
    { "experience_level": "learning", "median_minutes": 90, "min_minutes": 65, "max_minutes": 130, "total_reports": 712 },
    { "experience_level": "experienced", "median_minutes": 70, "min_minutes": 50, "max_minutes": 100, "total_reports": 1534 },
    { "experience_level": "expert", "median_minutes": 55, "min_minutes": 40, "max_minutes": 80, "total_reports": 389 }
  ],
  "multipliers": { "first_play": 1.71, "learning": 1.29, "experienced": 1.0, "expert": 0.79 },
  "sufficient_data": true,
  "total_reports": 3091
}

Analytical Questions Enabled

• Which games have the steepest learning curve? Sort by first_play multiplier descending – games where the gap between first play and experienced play is largest.
• Which games are “easy to learn”? Low first_play multiplier means play time barely changes with experience.
• Expert speedrun potential: Which games have the lowest expert multiplier, suggesting the most room for optimization?
• Data sufficiency: Which games have enough experience-tagged play logs to produce reliable multipliers?

Expansion Deltas as Analyzable Data

Property modifications and expansion combinations are not just internal data for effective mode – they are exportable entities. See Data Export for how to bulk-download this data.

Interesting analyses enabled by this data:

• Average weight increase per expansion: Do expansions tend to make games more complex?
• Player count expansion patterns: How often do expansions increase the max player count? By how much?
• Playtime inflation: Do expansions make games longer? By what percentage?
• Best-at shift: Does adding expansions change which player counts are considered best?

These questions are unanswerable without structured, exportable expansion delta data. OpenTabletop makes them trivial.

Data Export

The export system provides bulk access to data from a conforming implementation in machine-friendly formats. It uses the same filter dimensions as the search API, so you can export targeted slices of the dataset rather than downloading everything.

Export Endpoint

GET /export/games?format=jsonl&mechanics=cooperative&year_min=2020

Parameters

Include Options

GET /export/games?format=jsonl&include=base,polls,taxonomy&weight_min=3.0

JSON Lines Format

Each line is a self-contained JSON object representing one game with all requested includes:

{"id":"01967b3c-5a00-7000-8000-000000000096","slug":"barrage","name":"Barrage","type":"base_game","min_players":1,"max_players":4,"weight":4.02,"rating":8.12,"mechanics":["worker-placement","area-control","engine-building"],"categories":["strategy","economic"],"player_count_ratings":[{"player_count":1,"average_rating":2.8,"rating_count":312,"rating_stddev":1.2},{"player_count":2,"average_rating":3.9,"rating_count":534,"rating_stddev":0.8},{"player_count":3,"average_rating":4.6,"rating_count":687,"rating_stddev":0.5},{"player_count":4,"average_rating":4.4,"rating_count":498,"rating_stddev":0.7}]}
{"id":"01967b3c-5a00-7000-8000-000000000097","slug":"castles-of-burgundy","name":"The Castles of Burgundy","type":"base_game","min_players":1,"max_players":4,"weight":3.00,"rating":8.28,"mechanics":["dice-rolling","drafting","engine-building"],"categories":["strategy"],"player_count_ratings":[{"player_count":1,"average_rating":3.2,"rating_count":456,"rating_stddev":1.0},{"player_count":2,"average_rating":4.7,"rating_count":1823,"rating_stddev":0.4},{"player_count":3,"average_rating":3.8,"rating_count":987,"rating_stddev":0.8},{"player_count":4,"average_rating":3.3,"rating_count":612,"rating_stddev":0.9}]}

JSON Lines (.jsonl) is chosen because:

• Each line can be parsed independently – streaming and parallel processing are trivial.
• Appending new records does not require modifying existing data.
• Tools like jq, pandas, and duckdb handle JSON Lines natively.
• It is the de facto standard for data engineering pipelines.

CSV Format

Flat tabular export for spreadsheet users and simple analysis:

id,slug,name,type,min_players,max_players,weight,rating,confidence,mechanics,categories
01967b3c-5a00-7000-8000-000000000096,barrage,Barrage,base_game,1,4,4.02,8.12,0.81,"worker-placement|area-control|engine-building","strategy|economic"
01967b3c-5a00-7000-8000-000000000097,castles-of-burgundy,The Castles of Burgundy,base_game,1,4,3.00,8.28,0.85,"dice-rolling|drafting|engine-building","strategy"

CSV limitations:

• Array fields are pipe-delimited within a single column (cooperative|hand-management).
• Nested data (polls, vote distributions) is flattened or excluded.
• CSV export supports include=base,taxonomy but nested includes like polls produce one row per poll entry (game x player_count), not one row per game.

For anything beyond basic game metadata, JSON Lines is the recommended format.

ExportManifest

Every export response begins with a manifest header (in JSON Lines format) or is accompanied by a manifest endpoint:

GET /export/manifest?format=jsonl&mechanics=cooperative&year_min=2020

{
  "export_id": "01967b3c-7000-7000-8000-000000000099",
  "format": "jsonl",
  "filters_applied": {
    "mechanics": ["cooperative"],
    "year_min": 2020
  },
  "includes": ["base", "polls", "taxonomy"],
  "total_games": 342,
  "generated_at": "2026-03-12T10:00:00Z",
  "spec_version": "1.0.0",
  "checksum": "sha256:a1b2c3d4e5f6..."
}

The manifest provides:

• Reproducibility: The exact filters and includes used, so someone can regenerate the export later.
• Integrity: A SHA-256 checksum of the export data.
• Versioning: The spec version the data conforms to.
• Metadata: Total count, timestamp, unique export ID.

Streaming

Export responses are streamed. The server begins sending data as soon as the first row is ready, without buffering the entire result set. This means:

• Large exports (100k+ games) work without timeouts.
• Clients can begin processing before the download completes.
• Memory usage is bounded on both client and server.

The Content-Type header is application/x-ndjson for JSON Lines and text/csv for CSV. The Transfer-Encoding is chunked.

Rate Limiting

Export endpoints are rate-limited separately from search endpoints. The default limits:

• 10 export requests per hour per API key
• Maximum 100,000 games per export (use filters to stay under)
• No limit on export size in bytes (but larger exports take longer)

These are the specification’s recommended defaults. Implementations may adjust limits based on their infrastructure.

For full-dataset exports exceeding the per-request limit, use the cursor parameter to paginate through the export in batches.

Use Cases

• Academic research: Export all games with weight votes and player count polls for a study on complexity perception.
• Alternative ranking systems: Export ratings and vote counts to compute your own Bayesian ranking.
• Collection management: Export your owned games (filtered by a list of IDs) with full metadata for a local database.
• Data journalism: Export games by year to analyze trends in board game design.
• Machine learning: Export the full dataset as training data for a recommendation engine.

Trend Analysis

The board game hobby is a living ecosystem. Mechanics rise and fall in popularity. Rating consensus shifts as communities mature. Publishing channels transform – Kickstarter barely existed for board games before 2012; by 2020 it was the dominant funding model for mid-tier publishers. The OpenTabletop specification provides the schema and endpoints to make these dynamics queryable.

Two Types of Trends

Trend analysis splits into two fundamentally different problems, each requiring different data and different endpoints.

Cross-Sectional Trends

Cross-sectional trends aggregate existing game data over year_published. They answer questions about the population of games at each point in time:

• “How many cooperative games were published per year?”
• “What’s the average weight of games published each decade?”
• “What percentage of 2024 games support solo play?”
• “When did deck-building peak as a mechanic?”

These require no new data collection. Every game already has a year_published, mechanics, weight, min_players, and other filterable fields. Cross-sectional trends are pure aggregation – grouping and counting over existing records.

Note that cross-sectional trends reflect what is in the dataset, not necessarily all games published in a given year. If an implementation’s data skews toward popular or well-known games, the trends will reflect that subset. Similarly, metrics like “average weight published per year” depend on who is rating those games – see Data Provenance & Bias.

Longitudinal Trends

Longitudinal trends track the same entities over time. They answer questions about how individual games or rankings change, as perceived by the measuring population:

• “What was BGG #1 in 2019?”
• “How did Gloomhaven’s rating change from 2018 to 2024?”
• “When did Brass: Birmingham overtake Terraforming Mars?”
• “Do legacy games’ ratings decline after the campaign ends?”

These require periodic snapshots – point-in-time captures of each game’s rating, weight, rank, and activity metrics. This is new data that does not exist in the current model. The GameSnapshot schema (see ADR-0036) defines the snapshot format; implementations choose the snapshot frequency (monthly, quarterly, or yearly) based on their resources.

flowchart LR
    subgraph "Cross-Sectional"
        EXISTING["Existing Game Data<br/><i>year_published, mechanics,<br/>weight, players, ...</i>"]
        AGG["Aggregate Endpoints<br/><i>GROUP BY year</i>"]
        EXISTING --> AGG
    end

    subgraph "Longitudinal"
        SNAP["GameSnapshot Data<br/><i>Periodic captures of<br/>rating, rank, plays, ...</i>"]
        HIST["History Endpoints<br/><i>Time series per game</i>"]
        SNAP --> HIST
    end

    style EXISTING fill:#388e3c,color:#fff
    style AGG fill:#1976d2,color:#fff
    style SNAP fill:#f57c00,color:#fff
    style HIST fill:#1976d2,color:#fff

Cross-Sectional Endpoints

These endpoints aggregate over existing game data. All accept the standard filter dimensions (mechanic, category, theme, player count, weight range) so you can ask “how did cooperative games’ average weight change over time?” – not just “how did all games’ average weight change?”

Publication Trends

GET /statistics/trends/publications?group_by=year&mechanic=cooperative&year_min=2000

{
  "data": [
    { "period": 2000, "game_count": 12, "avg_weight": 2.9, "avg_rating": 6.8 },
    { "period": 2008, "game_count": 34, "avg_weight": 2.7, "avg_rating": 7.2 },
    { "period": 2017, "game_count": 187, "avg_weight": 2.6, "avg_rating": 7.0 },
    { "period": 2024, "game_count": 342, "avg_weight": 2.8, "avg_rating": 7.1 }
  ]
}

The 2008 inflection point is visible – Pandemic’s release triggered an explosion of cooperative game design. By 2024, cooperative games are nearly 30x more common than in 2000.

Mechanic Adoption

GET /statistics/trends/mechanics?year_min=2000&limit=5

{
  "data": [
    { "period": 2007, "mechanic": "deck-building", "game_count": 0, "pct_of_period": 0.0 },
    { "period": 2008, "mechanic": "deck-building", "game_count": 1, "pct_of_period": 0.1 },
    { "period": 2012, "mechanic": "deck-building", "game_count": 87, "pct_of_period": 4.2 },
    { "period": 2020, "mechanic": "deck-building", "game_count": 156, "pct_of_period": 3.8 }
  ]
}

Dominion launched in 2008 as a single game. By 2012, deck-building was 4.2% of all published games. These mechanic adoption curves map directly to the phylogenetic model – every mechanic’s origin_game and origin_year in the taxonomy data marks the start of its adoption curve.

Weight Distribution

GET /statistics/trends/weight?group_by=year&scope=top100

{
  "data": [
    { "period": 2010, "avg_weight": 3.4, "median_weight": 3.3, "weight_p25": 2.8, "weight_p75": 3.9 },
    { "period": 2020, "avg_weight": 3.1, "median_weight": 3.0, "weight_p25": 2.5, "weight_p75": 3.6 },
    { "period": 2025, "avg_weight": 3.2, "median_weight": 3.1, "weight_p25": 2.6, "weight_p75": 3.7 }
  ]
}

The scope parameter controls which games are included:

• top100 – Current top 100 ranked games, grouped by publication year
• published – All games published in each year (the broadest view)
• all – All games in the dataset, regardless of rank or year

Player Count Trends

GET /statistics/trends/player-count?year_min=2015

{
  "data": [
    { "period": 2015, "avg_min_players": 1.8, "avg_max_players": 4.1, "solo_support_pct": 22.4 },
    { "period": 2020, "avg_min_players": 1.4, "avg_max_players": 4.2, "solo_support_pct": 38.5 },
    { "period": 2025, "avg_min_players": 1.3, "avg_max_players": 4.3, "solo_support_pct": 45.2 }
  ]
}

Solo support nearly doubled from 2015 to 2025 – a clear industry-wide shift toward accommodating solo gamers. The 2020 inflection is particularly sharp: the COVID-19 pandemic drove an explosion of solo and small-group game design as lockdowns removed the regular game night. Kickstarter campaigns advertising solo modes surged during 2020-2021, and publishers who had treated solo as an afterthought began designing for it from the start. The trend persisted well after lockdowns ended, suggesting the pandemic accelerated a shift that was already underway rather than creating a temporary spike.

Longitudinal Endpoints

These endpoints query GameSnapshot data. They require implementations to collect periodic snapshots (see ADR-0036). Longitudinal trend quality improves over time as more snapshots accumulate.

Game History

GET /games/spirit-island/history?metric=rating&granularity=yearly

{
  "game": { "id": "01912f4c-...", "slug": "spirit-island", "name": "Spirit Island" },
  "metric": "rating",
  "granularity": "yearly",
  "data": [
    { "date": "2018-01-01", "average_rating": 8.05, "rating_count": 8420 },
    { "date": "2019-01-01", "average_rating": 8.18, "rating_count": 14230 },
    { "date": "2020-01-01", "average_rating": 8.25, "rating_count": 21500 },
    { "date": "2024-01-01", "average_rating": 8.31, "rating_count": 27842 }
  ]
}

Spirit Island’s rating has been steadily climbing – a sign of a game with strong staying power that the community values more over time, not less.

Ranking History

GET /statistics/rankings/history?scope=overall&top=10&date=2020-01-01

{
  "scope": "overall",
  "date": "2020-01-01",
  "data": [
    { "rank": 1, "game_slug": "gloomhaven", "bayes_rating": 8.85 },
    { "rank": 2, "game_slug": "pandemic-legacy-season-1", "bayes_rating": 8.62 },
    { "rank": 3, "game_slug": "brass-birmingham", "bayes_rating": 8.59 }
  ]
}

Ranking Transitions

GET /statistics/rankings/transitions?scope=overall&top=10&year_min=2018&year_max=2025

{
  "scope": "overall",
  "top": 10,
  "from": "2018-01-01",
  "to": "2025-01-01",
  "entered": [
    { "game_slug": "brass-birmingham", "entered_rank": 3, "entered_date": "2019-01-01", "current_rank": 1 },
    { "game_slug": "ark-nova", "entered_rank": 6, "entered_date": "2022-01-01", "current_rank": 5 }
  ],
  "exited": [
    { "game_slug": "7-wonders-duel", "exited_rank": 9, "exited_date": "2023-01-01", "peak_rank": 4 }
  ],
  "stable": [
    { "game_slug": "gloomhaven", "rank_2018": 1, "rank_2025": 2 }
  ]
}

The response groups games into three arrays: entered (climbed into the top N during the window), exited (fell out), and stable (remained throughout). This is the data behind narratives like “the era of legacy games” or “the heavy euro resurgence.”

Funding Source

To track the impact of crowdfunding on the hobby, the specification includes an optional funding_source field on the Game entity:

funding_source:
  enum: [retail, kickstarter, gamefound, backerkit, self_published, other]

This enables queries like:

GET /statistics/trends/publications?group_by=year&funding_source=kickstarter&year_min=2012

{
  "data": [
    { "period": 2012, "game_count": 42, "kickstarter_pct": 1.8 },
    { "period": 2016, "game_count": 285, "kickstarter_pct": 8.4 },
    { "period": 2020, "game_count": 612, "kickstarter_pct": 14.7 },
    { "period": 2024, "game_count": 489, "kickstarter_pct": 11.2 },
    { "period": 2025, "game_count": 310, "kickstarter_pct": 7.8 },
    { "period": 2026, "game_count": 274, "kickstarter_pct": 6.9 }
  ]
}

Kickstarter-funded games peaked around 2020 at nearly 15% of all published titles. The slight decline by 2024 reflects the rise of Gamefound and BackerKit as alternatives – which is why the funding_source enum includes multiple crowdfunding platforms rather than treating “crowdfunded” as a single category.

The 2025 US tariffs on Chinese imports add another dimension to this data. The board game industry relies heavily on Chinese manufacturing – publishers like Panda Game Manufacturing, LongPack, and WinGo produce the majority of hobbyist titles. Tariffs raise the per-unit cost of component-heavy games (miniatures, custom inserts, large box formats) disproportionately, and crowdfunded games are especially exposed: backer pricing is locked months or years before fulfillment, leaving publishers to absorb cost increases they could not have predicted. Cross-referencing funding_source=kickstarter with the weight distribution endpoint would reveal whether crowdfunded games shift toward lighter component profiles in response, or whether publishers absorb the cost and pass it to backers through higher pledge tiers. The publication trends endpoint itself may show a volume dip in 2025-2026 as smaller publishers delay or cancel projects – a pattern visible in the game_count field the same way the COVID-19 pandemic’s effects appeared in the player count data above.

Connecting Trends to Taxonomy

The cross-sectional trend endpoints connect naturally to the taxonomy’s phylogenetic model. Every mechanic in the controlled vocabulary has an origin_game, origin_year, and ancestor_slugs – the game that created or codified that mechanic, and the lineage it descended from. These speciation events are the inflection points visible in trend data, and the parent-child relationships reveal how design innovations propagate through the hobby.

Lineage Waves

When a speciation event creates a new mechanic, the parent’s trend curve often shifts simultaneously. Hand Management (Rummy, 1890) has 9 children in the taxonomy. When Deck Building (Dominion, 2008) branched off, it did not replace hand management – both curves grew, but deck building’s was steeper. The /statistics/trends/mechanics endpoint can overlay parent and child mechanic adoption curves to visualize this branching pattern. Querying with a parent=hand-management parameter would return the adoption curves for all nine descendants, showing when each branch emerged and how quickly it grew.

Convergent Evolution

Some mechanics descend from two parent lineages. Dice Placement (Alien Frontiers, 2010) combines Worker Placement’s blocking-and-scarcity with Dice Rolling’s randomness. Pattern Building (Azul, 2017) merges Tile Placement’s spatial reasoning with Set Collection’s combinatorial goals. These convergence points appear in trend data as inflection points where two previously independent curves develop a correlated descendant – a signal that designers are cross-pollinating between established mechanic families.

Dormancy and Revival

Roll and Write originated with Yahtzee in 1956 but was largely dormant as a design space for decades. The modern roll-and-write wave (circa 2018, anchored by Welcome To…) revived the mechanic and spawned an explosion of “flip-and-write” and “roll-and-write” games. The trend data would show near-zero roll-and-write publications from 1960 to 2015, then a steep adoption curve. The taxonomy captures the origin; the trend endpoint captures the revival. Cross-referencing both tells the full lifecycle story – and identifies which other dormant mechanics might be candidates for a similar revival.

The taxonomy data provides the what (which game created which mechanic and where it sits in the tree); the trend endpoints provide the so what (how did the hobby change as a result). Together, they let you query “show me all children of worker-placement and their adoption curves” – connecting the phylogenetic tree directly to observable data.

Trends and the Data Model

Several data model refinements in Pillar 1 and Pillar 2 create new dimensions for trend analysis beyond the basic publication counts and averages shown above.

Rating Confidence Trends

The rating model introduces a confidence score (0.0-1.0) that combines sample size, distribution shape, and deviation from the global mean. Confidence is itself a trendable metric – a newly released game starts with low confidence that stabilizes as votes accumulate. The Game History endpoint accepts metric=confidence alongside metric=rating. Rating polarization (bimodal distributions flagged by high standard deviation) is another trendable signal: “are games becoming more polarizing over time, or is consensus strengthening?”

Dimensional Weight Trends

The weight model supports an optional dimensional breakdown: rules complexity, strategic depth, decision density, cognitive load, fiddliness, and game length. Cross-sectional weight trends could break down by dimension, answering questions like “are modern games getting more strategically deep, or just fiddlier?” The documented complexity bias (heavy games averaging ~2.5 rating points higher than light games of similar quality) is itself a trendable hypothesis – is the bias stable over time, or is it narrowing as the voter population diversifies?

Player Count Sentiment Trends

The player count model uses numeric 1-5 per-count ratings rather than the legacy best/recommended/not-recommended categories. This enables richer longitudinal analysis: tracking how a game’s per-count sentiment shifts over time (e.g., does a game’s solo rating improve as the community develops solo strategies?). Cross-sectionally, the industry-wide “solo friendliness” curve can be measured with finer granularity than the binary solo_support_pct shown above – instead, “average solo rating of games published per year” captures the quality of solo support, not just its presence.

Experience-Bucketed Playtime Trends

The experience-adjusted playtime model defines four experience levels (first play, learning, experienced, expert) with per-game multipliers. Trend queries accept a playtime_experience parameter, answering “how has the average first-play time of published games changed over the decade?” The gap between first-play and expert-play times is itself a trendable metric – are modern games getting better at reducing the first-play penalty, or are they front-loading more complexity?

Data Provenance

All trend data inherits the biases documented in Data Provenance & Bias. Cross-sectional trends reflect what is in the dataset, which may skew toward popular and well-known games (see the note in Cross-Sectional Trends above). Longitudinal trends compound this with a temporal dimension: early snapshots capture the community as it was (smaller, more homogeneous); later snapshots reflect an evolving and growing population. A shift in average weight over time could reflect changing game design or a changing voter population – trend consumers should consider both interpretations.

Design Decisions

See ADR-0036 for the full design rationale, including why periodic snapshots were chosen over event sourcing, and the trade-offs between snapshot granularity options.

Statistics Roadmap

The statistical foundation in the initial specification provides raw distributions, bulk export, and transparent derivations. The roadmap below describes planned extensions that build on this foundation – informed by the expanded data model (rating confidence, dimensional weight, player count sentiment, experience-bucketed playtime, and community signals). These are not commitments – they are directional goals that will go through the RFC governance process before being added to the specification.

Near-Term: Cross-Sectional Trend Endpoints

Status: Planned for v1.0

Cross-sectional trends aggregate existing game data over year_published – no new data collection required. Four endpoints:

• GET /statistics/trends/publications – Games published per period, with average weight and rating. Filterable by mechanic, category, theme, funding source.
• GET /statistics/trends/mechanics – Per-mechanic adoption curves (count and percentage of games per year). Tied to the taxonomy’s phylogenetic model.
• GET /statistics/trends/weight – Weight distribution over time (mean, median, percentiles). Scoped to top-100, all published, or full dataset.
• GET /statistics/trends/player-count – Player count ranges and solo support percentage over time.

All trend endpoints compose with the standard filter dimensions. The expanded data model enables additional trend dimensions: rating confidence trends, dimensional weight breakdowns, per-count player sentiment curves, and experience-adjusted playtime trends. See Trend Analysis for worked examples with JSON payloads, and ADR-0036 for the design rationale.

Near-Term: Parquet Export

Status: Planned for v1.1

JSON Lines and CSV cover the common cases, but data engineering workflows increasingly rely on columnar formats for analytical queries. Apache Parquet provides:

• Columnar compression: 5-10x smaller than JSON Lines for numerical data (vote counts, ratings, weights).
• Predicate pushdown: Query engines (DuckDB, Spark, BigQuery) can skip irrelevant columns and row groups without reading the entire file.
• Type safety: Schema is embedded in the file. Integers are integers, not strings that happen to contain digits.
• Ecosystem support: Parquet is readable by Pandas, Polars, R, DuckDB, Spark, Snowflake, BigQuery, Athena, and virtually every modern data tool.

The Parquet export will use the same /export/games endpoint with format=parquet. The include parameter (documented in Data Export) controls which nested structures are populated. Full schema:

games.parquet
├── id (string, UUID)
├── slug (string)
├── name (string)
├── type (string, enum)
├── year_published (int32)
├── min_players (int32)
├── max_players (int32)
├── min_playtime (int32)
├── max_playtime (int32)
├── community_min_playtime (int32, nullable)
├── community_max_playtime (int32, nullable)
├── weight (float32)
├── weight_votes (int32)
├── average_rating (float32)
├── rating_count (int32)
├── rating_distribution (fixed_size_list<int32>[10])
├── rating_stddev (float32)
├── rating_confidence (float32)
├── rank_overall (int32, nullable)
├── community_suggested_age (int32, nullable)
├── owner_count (int32, nullable)
├── wishlist_count (int32, nullable)
├── total_plays (int32, nullable)
├── funding_source (string, nullable)
├── mechanics (list<string>)
├── categories (list<string>)
├── themes (list<string>)
├── player_count_ratings (list<struct>)
│   ├── player_count (int32)
│   ├── average_rating (float32)
│   ├── rating_count (int32)
│   └── rating_stddev (float32)
└── experience_playtime (struct, nullable)
    ├── levels (list<struct>)
    │   ├── experience_level (string, enum)
    │   ├── median_minutes (int32)
    │   ├── p10_minutes (int32)
    │   ├── p90_minutes (int32)
    │   └── report_count (int32)
    └── multipliers (struct, nullable)
        ├── first_play (float32)
        ├── learning (float32)
        ├── experienced (float32)
        └── expert (float32)

Key differences from earlier drafts: player_count_ratings uses the ADR-0043 numeric 1-5 model (average rating, count, stddev per player count), replacing the legacy BGG three-tier fields. Rating data is split into distribution, confidence, and stddev fields rather than a single rating float. Community signals (owner_count, wishlist_count, total_plays) and experience-bucketed playtime are included as first-class columns.

Nested structures (ratings, taxonomy lists, experience playtime) are stored as Parquet nested types, not flattened. This preserves the one-row-per-game structure while keeping relational data accessible to predicate pushdown.

Near-Term: Longitudinal Snapshots

Status: Planned for v1.1

Longitudinal trends track the same entities over time. Unlike cross-sectional trends, they require new data – periodic GameSnapshot records capturing a game’s rating, weight, ranking, play count, and owner count at a specific date. Three endpoints:

• GET /games/{id}/history – Time series of a single game’s metrics over time.
• GET /statistics/rankings/history – Historical ranking snapshots at a specific date.
• GET /statistics/rankings/transitions – Games entering and exiting the top N over a date range.

See Trend Analysis for worked examples with JSON payloads. The GameSnapshot schema (spec/schemas/GameSnapshot.yaml) captures average_rating, bayes_rating, rating_count, weight, weight_votes, rank_overall, rank_by_category, play_count_period, and owner_count.

Storage Considerations

Snapshot frequency is implementation-defined:

Historical data before an implementation begins collecting snapshots is not available unless backfilled from external sources. Trend quality improves with history length.

Mid-Term: Correlation APIs

Status: Under discussion

Pre-computed correlations between game properties, exposed as read-only, cacheable API endpoints updated periodically (not real-time). These provide the kind of aggregate analysis that currently requires downloading the full dataset and computing locally.

Mechanic Co-occurrence

“What mechanics most commonly appear together?”

GET /statistics/correlations/mechanics?mechanic=deck-building&limit=10

{
  "mechanic": "deck-building",
  "cooccurrences": [
    { "mechanic": "hand-management", "count": 412, "jaccard": 0.38 },
    { "mechanic": "engine-building", "count": 287, "jaccard": 0.26 },
    { "mechanic": "drafting", "count": 198, "jaccard": 0.18 }
  ]
}

Rating-by-Mechanic

“How have average ratings changed over time for cooperative games?”

GET /statistics/trends/rating?mechanic=cooperative&group_by=year

{
  "mechanic": "cooperative",
  "data": [
    { "period": 2008, "avg_rating": 6.8, "rating_count": 34, "avg_confidence": 0.42 },
    { "period": 2015, "avg_rating": 7.2, "rating_count": 156, "avg_confidence": 0.68 },
    { "period": 2020, "avg_rating": 7.0, "rating_count": 412, "avg_confidence": 0.61 },
    { "period": 2025, "avg_rating": 7.1, "rating_count": 342, "avg_confidence": 0.58 }
  ]
}

The 2020 dip in average confidence alongside rising game count reflects a flood of new cooperative titles that have not yet accumulated enough votes to stabilize.

Rating Confidence Correlations

The rating model introduces a confidence score (0.0-1.0). Correlating confidence with other properties reveals data quality patterns:

GET /statistics/correlations/confidence?group_by=funding_source

{
  "data": [
    { "funding_source": "retail", "avg_confidence": 0.72, "avg_stddev": 1.4, "game_count": 18420 },
    { "funding_source": "kickstarter", "avg_confidence": 0.48, "avg_stddev": 1.9, "game_count": 3215 },
    { "funding_source": "gamefound", "avg_confidence": 0.41, "avg_stddev": 2.1, "game_count": 870 },
    { "funding_source": "self_published", "avg_confidence": 0.34, "avg_stddev": 2.3, "game_count": 1540 }
  ]
}

Crowdfunded and self-published games show systematically lower confidence and higher variance – smaller voter populations and possible self-selection from backers who are already invested in the game’s success.

• “Which mechanics or themes are associated with the most polarized ratings?” – high stddev, low confidence.
• “Does rating confidence correlate with publication year?” – newer games have less data, but the rate of convergence varies.

Weight-by-Mechanic

“What is the average weight of games with each mechanic?”

GET /statistics/correlations/weight-by-mechanic

{
  "data": [
    { "mechanic": "worker-placement", "avg_weight": 3.21, "game_count": 1847, "weight_stddev": 0.72 },
    { "mechanic": "deck-building", "avg_weight": 2.54, "game_count": 1203, "weight_stddev": 0.68 },
    { "mechanic": "roll-and-write", "avg_weight": 1.82, "game_count": 624, "weight_stddev": 0.51 },
    { "mechanic": "wargame-hex-and-counter", "avg_weight": 3.89, "game_count": 312, "weight_stddev": 0.84 }
  ]
}

Dimensional Weight Correlations

The weight model supports an optional 6-dimension breakdown (rules complexity, strategic depth, decision density, cognitive load, fiddliness, game length). Correlation endpoints can leverage these dimensions:

GET /statistics/correlations/weight-dimensions?dimension=strategic_depth&sort_by=correlation

{
  "dimension": "strategic_depth",
  "correlations": [
    { "mechanic": "engine-building", "correlation": 0.74, "avg_dimension_score": 3.8, "game_count": 1420 },
    { "mechanic": "worker-placement", "correlation": 0.71, "avg_dimension_score": 3.6, "game_count": 1847 },
    { "mechanic": "auction-bidding", "correlation": 0.65, "avg_dimension_score": 3.3, "game_count": 890 },
    { "mechanic": "roll-and-write", "correlation": 0.31, "avg_dimension_score": 2.1, "game_count": 624 }
  ]
}

• “Which mechanics correlate with high strategic depth but low fiddliness?” – the “elegant complexity” query.
• “Which weight dimension correlates most strongly with overall rating?” – testing whether strategic depth or rules complexity drives the documented complexity bias.

Experience Playtime Correlations

The experience-adjusted playtime model captures per-game learning curves. Correlating multipliers with game properties answers:

GET /statistics/correlations/experience-curve?sort_by=first_play_multiplier&order=desc

{
  "data": [
    { "mechanic": "legacy", "avg_first_play_multiplier": 1.82, "avg_weight": 3.4, "game_count": 87 },
    { "mechanic": "engine-building", "avg_first_play_multiplier": 1.65, "avg_weight": 3.1, "game_count": 1420 },
    { "mechanic": "worker-placement", "avg_first_play_multiplier": 1.52, "avg_weight": 3.2, "game_count": 1847 },
    { "mechanic": "roll-and-write", "avg_first_play_multiplier": 1.18, "avg_weight": 1.8, "game_count": 624 }
  ]
}

Legacy games have the steepest first-play penalty (1.82x) despite moderate weight – the campaign structure means first sessions include significant overhead that does not recur. Roll-and-write games have the flattest curve, confirming that low-fiddliness mechanics translate directly to faster onboarding.

Community Engagement Correlations

Community signals (owner_count, wishlist_count, total_plays) enable engagement analysis:

GET /statistics/correlations/engagement?metric=plays_per_owner&sort_by=desc

{
  "metric": "plays_per_owner",
  "data": [
    { "game_slug": "codenames", "plays_per_owner": 18.4, "owner_count": 82100, "total_plays": 1510640 },
    { "game_slug": "7-wonders", "plays_per_owner": 12.7, "owner_count": 71200, "total_plays": 904240 },
    { "game_slug": "terraforming-mars", "plays_per_owner": 8.3, "owner_count": 94500, "total_plays": 784350 },
    { "game_slug": "gloomhaven", "plays_per_owner": 4.1, "owner_count": 68400, "total_plays": 280440 }
  ]
}

Codenames at 18.4 plays per owner versus Gloomhaven at 4.1 illustrates the replayability spectrum – party games get replayed constantly while campaign games are played through once. This is a signal that rating alone does not capture.

• “Which wishlisted games convert to purchases fastest?” – wishlist-to-owner velocity.
• “Do lighter games get played more often per owner, or does engagement correlate with weight?”

Long-Term: Recommendation Engine Foundation

Status: Exploratory

The data model and export system provide the raw materials for recommendation engines, but the specification intentionally does not define a recommendation algorithm. Recommendations are subjective and application-specific – “similar games” means different things to different users.

What the specification can provide:

• Feature vectors: A standardized game feature vector that recommendation engines can use as input. The expanded data model provides much richer signals than a simple mechanics-and-weight vector:
  • Mechanics bitmap (unchanged)
  • Dimensional weight profile (6 independent dimensions, not just the composite score)
  • Player count sentiment curve (per-count 1-5 ratings from ADR-0043, not just min/max)
  • Rating confidence score (distinguishes well-understood games from noisy or polarized ones)
  • Experience playtime multipliers (characterizes the learning curve shape)
  • Community engagement signals (plays-per-owner ratio, owner velocity)
• Similarity endpoint: A /games/{id}/similar endpoint that returns games with high feature-vector similarity, using a documented distance metric (e.g., cosine similarity). Dimensional weight and player count curves provide much richer similarity signals than the earlier mechanics-bitmap approach.
• User preference profiles: A schema for expressing user preferences that implementations can use to personalize results. Preferences can now include weight dimension priorities (e.g., “I value strategic depth but dislike fiddliness”), experience-adjusted time constraints (“games that fit in 90 minutes for a first play”), and player count quality thresholds (“best at exactly 2, not just supports 2”).

The key principle: the specification defines the inputs to recommendation (feature vectors, similarity metrics), not the outputs (personalized ranked lists). Implementations are free to build sophisticated recommendation systems on top of the specification’s data.

Long-Term: Data Quality Analytics

Status: Exploratory

Analytics about the data itself – not about games, but about the health and completeness of the dataset. These help the community prioritize curation effort and track data maturity over time.

GET /statistics/data-quality

{
  "snapshot_date": "2026-03-01",
  "resolution_tiers": {
    "games_with_expansions": 8420,
    "tier_1_explicit_pct": 12.4,
    "tier_2_computed_pct": 31.2,
    "tier_3_base_only_pct": 56.4
  },
  "rating_confidence": {
    "above_0_7_pct": 34.8,
    "between_0_4_and_0_7_pct": 41.2,
    "below_0_4_pct": 24.0
  },
  "player_count_ratings": {
    "native_numeric_pct": 28.6,
    "legacy_three_tier_only_pct": 52.1,
    "no_data_pct": 19.3
  },
  "experience_playtime": {
    "sufficient_data_pct": 18.4,
    "partial_data_pct": 22.7,
    "no_data_pct": 58.9
  }
}

Each section maps to a curation priority:

• Resolution tier distribution: What percentage of games with expansions have tier 1 (explicit ExpansionCombination), tier 2 (computed deltas), or tier 3 (base game only) effective-mode data? A dashboard showing “87% of games with expansions have only tier 3 data” motivates contributors to curate combination records.
• Rating confidence distribution: What percentage of games have confidence above 0.7? How does this break down by publication decade or game type? Tracks overall data maturity.
• Player count rating coverage: What percentage of games have native numeric per-count ratings (ADR-0043) vs. only legacy three-tier data vs. no player count data at all? Tracks migration progress.
• Experience playtime coverage: What percentage of games have sufficient_data: true for experience-bucketed playtime? Which weight tiers or mechanics have the worst coverage?

Contributing to the Roadmap

All roadmap items will go through the RFC process described in the Governance Model. To propose a new statistical feature:

1. Open a discussion issue describing the use case and the data required.
2. If there is community interest, draft an RFC with the proposed schema, endpoints, and export format.
3. The RFC goes through the standard review and approval process.