Playbooks: block catalog & JSON schema

A playbookis a saved screen: a tree of filter blocks over every batter and starting pitcher on tonight's MLB slate, plus an optional weighted score that ranks whatever survives. This page is generated from the same registry the builder and the validator read, so it can never drift out of date.

Writing one with an AI assistant? Paste this page into the assistant, ask for a playbook/v1 document, then load it via the builder's JSON tab. Import is fail-closed: an unknown block type or field is rejected with the path that caused it, never silently dropped.

How a playbook is evaluated

The order is fixed, and it matters:

1. scope to the playbook's entity (batter or pitcher)
2. apply the odds policy
3. apply the filter tree          <- a row that fails here is gone
4. score the survivors            <- Advanced Mode only
5. apply the score gate
6. sort by score, then cap to top_n

Scoring runs after filtering, over the survivors only. No weight can bring back a player who failed a filter. The score gate runs before the cap, so top_n never pads the list back out with rows that missed the gate.

Missing data is not zero

A field is NA when it was never measured, no Statcast sample, no posted price, a pitcher with no prior game logs, wind in a domed park. A field is 0only when zero was actually observed. These are never conflated: a screen for “fewer than 1 home run in the last 5” matches a player who genuinely hit none, not a player who has not batted.

Projected vs confirmed lineups

Early in the day most batting orders are projected. Rows carry a lineup_status of projected, confirmed or unknown, and the universe is rebuilt through the evening as orders post, so a saved playbook updates in place. Non-confirmed rows are flagged with an orange ! in the results table. A pitcher row counts as confirmed once the order he faces is posted.

What you cannot screen on

Slatery model output is not available as an input: no model probabilities, no Hit/K/HR sheet numbers, no edges or pick flags. Playbooks are meant to express your own reasoning over raw evidence, and the models are a separate product to be compared against, not fed from. Market prices and book-implied probabilities are allowed. Those are market data.

The playbook/v1 document

{
  "schema": "playbook/v1",
  "meta": {
    "name": "Barrel + Park",
    "entity": "batter",
    "target_market": "hr"
  },
  "policies": {
    "na_default": "remove",
    "odds": "show_without",
    "odds_market": "homeruns"
  },
  "filters": {
    "op": "and",
    "children": [
      {
        "type": "metric_compare",
        "field": "barrel_rate",
        "op": "gte",
        "value": 0.06
      },
      {
        "type": "context_compare",
        "field": "park_hr_factor",
        "op": "gte",
        "value": 1.02
      },
      {
        "type": "sample_gate",
        "field": "pa_l30",
        "value": 30
      },
      {
        "type": "lineup_status",
        "allow": [
          "projected",
          "confirmed"
        ]
      }
    ]
  },
  "advanced": {
    "enabled": true,
    "terms": [
      {
        "field": "barrel_rate",
        "transform": "z_slate",
        "weight": 1.5
      },
      {
        "field": "park_hr_factor_vs_hand",
        "transform": "raw",
        "weight": 0.8
      }
    ],
    "score_gate": null,
    "top_n": 10
  }
}

Block types

Rolling windows

Window blocks (window_count, window_rate, window_streak) do not take a field id. They take a stat and a window. A number of recent games from 1 to 25, and are computed from the player's real game-by-game log rather than from a precomputed column. That is why there is no hr_l7 field: {"type":"window_count","stat":"hr","window":7} is the same question with the window as a parameter.

Counts default to requiring a full window: a player with two games logged reports NA for "HR in the last 7" rather than a count of zero, because those are not the same measurement. Override with min_games.

Rates gate on their own denominator instead (at-bats, plate appearances, batters faced), because a rate already normalises for opportunity. Override with min_denom. A batter with zero at-bats has no average, not an average of .000.

A window can also be scored on. Advanced Mode terms accept the reserved field id w:count:<stat>:<n> or w:rate:<stat>:<n>, for example w:rate:k9:10 is K/9 over the last 10 starts. These are ranked against the whole slate exactly like any catalog field.

Operators & transforms

A score term whose field is NA is skipped, not scored as zero. A missing Statcast sample is a data gap, not evidence of a bad hitter.

Field catalog

185 fields. The same id can mean different things per entity, barrel_rate is contact quality on a batter row and barrels allowed on a pitcher row, so always check the entity column.

Sample-size fields

Used with sample_gateto require a minimum amount of evidence behind a stat. Worth adding to almost any screen: trailing rates stay on a player's record even when they have not played for weeks.

Market odds

Odds come from the same feed the rest of the site quotes, preferring DraftKings, then FanDuel, BetMGM, bet365, Caesars. Player prop coverage in this feed is thin. Most players on a given slate have no posted price, and home runs and RBIs are quoted one-sided (an over price only, no under). Setting the odds policy to require will therefore cut a slate down hard.

Weather is an outdoor reading, even indoors

Temperature, wind speed and wind direction come from a forecast at the ballpark's coordinates. They are reported for every park, including domed and roofed ones, on a recent slate all 60 rows at roofed venues carried a wind speed. That number does not describe indoor play. A screen like wind_mph ≥ 8 will therefore include domed games unless you say otherwise, so pair weather filters with the venue_is block set to open air:

{"op":"and","children":[
  {"type":"context_compare","field":"wind_mph","op":"gte","value":8},
  {"type":"venue_is","dome":"no"}
]}

Known data gaps

Statcast lag. Pitch-level data lands on a delay of a few days, so xwoba, barrel_rate and hardhit_rate reflect games up to roughly three days before today. Trailing box-score fields are current.

Thin prop coverage. Most players on a slate have no posted player prop. Home runs and RBIs are quoted one-sided (an over price only). Setting the odds policy to require a price will cut a slate down hard. On a recent slate it dropped 127 of 162 batters when requiring a hits price. That is the market, not a bug.

Recency vs staleness. Trailing rates like avg_l7stay on a player's record even if they have not played for weeks, and a player with no plate appearances in the window reports NA rather than a zero rate. Add a sample_gate on pa_l30 or games_played_l30 to any screen where that matters. Every shipped template does.

Starter templates

15 worked examples ship in the builder. Load one and edit it rather than starting from an empty canvas.

Missing a block you need? The catalog grows from requests. Tell us the stat, the window and what you would screen for with it. Back to the builder.