RaceHooks is a motorsports analytics platform, and the feed catalog is its map of how a race weekend actually works. It isn't a list of every signal we could publish — it's a model: nine families, each owning one kind of question about a session, delivered in one consistent shape. This post explains the taxonomy, the design rules underneath it, and why almost none of it is specific to Formula 1.
The nine families
Every feed belongs to exactly one family, and each family answers a different question:
| Family | The question it answers |
|---|---|
| Session core | Is there a session, and what state is it in? |
| Timing | Who is where, and how fast? |
| Strategy | Tyres, stints, pit stops — what is each car's race plan doing? |
| Race control | What has the referee said? |
| Race events | What just happened — overtakes, pit stops, retirements, fastest laps |
| Weather | What are the conditions, and where are they going? |
| Telemetry | The deep per-car record, after the session |
| Results | What did it all count for — classification and standings |
| Analytics | What happens next — the model layer |
The split isn't cosmetic. It follows how decisions are made. A timing screen and a strategy call are different jobs: one is observation, one is projection. An overtake is not a lap time — it's an event, a discrete thing that happened, so it lives in its own family with a shape built for "react when this occurs" rather than "render this table." Weather is separated from timing because conditions have their own cadence and their own forward-looking question (our rain forecasting lives here, next to the observations it extends). And analytics is a family, not a bolt-on flag, because a probability is a different kind of statement than a measurement — it carries model context and deserves a schema that says so.
The rules every payload follows
The families tell you where a feed lives. Five design rules tell you what any payload looks like when it arrives — and they're the reason integrations against RaceHooks stay small.
1. Payloads describe the race, not our infrastructure. Every field is a statement about the session, the cars, or the track. Nothing about pipelines, wire formats, or plumbing ever appears in a payload. If it isn't a fact about racing, it isn't in the JSON.
2. One envelope, everywhere. Every delivery is { feed, sessionId, utc, ... } with
the body in data (or drivers, for per-driver arrays). The feed discriminator means
one endpoint can receive twenty subscriptions and route them with a single switch.
3. Identity is canonical, and it's ours. A circuit is { id: "monaco", name: "Monaco" }.
A session id reads like what it is: the event and the session, not an opaque number. Ids
are stable, human-legible slugs you can log, join on, and cache against for years.
4. An entity has one shape, in every feed. A driver is always the full DriverRef —
number, driver id, constructor id, three-letter code, name, team — whether they appear in
a timing row, a pit event, or a win-probability estimate. You destructure a driver the
same way everywhere; there is no "this feed uses the short form" footnote, and no joining
back to a lookup feed just to learn who car 4 is.
5. Every feed earns its place. If a signal would ship as an undigested blob — no native shape, no consistent identity, nothing composed — it doesn't ship. Some feeds are direct observations; many are things RaceHooks computes: the race-events stream is composed from what's happening on track, the analytics family is generated by our models, weather forecasting is built, not observed. The catalog stays a set of finished products rather than a pile of raw material.
A catalog grows. Rules don't have to. Because shape, identity, and envelope are fixed, the feed you subscribe to next costs a fraction of the first one — your parsing, routing, and driver handling are already written.
Why this translates across motorsport
Look back at the nine families: nothing in that table says Formula 1. Timing, stints, race control, weather, classification — these are properties of racing, not of one championship. That's deliberate, and it's the part of RaceHooks designed to outlive any single series.
The taxonomy is the portable layer. A stage end in NASCAR is a race event. An IndyCar pit cycle is strategy. A caution is race control, whatever the flag protocol looks like. When a new series comes online, it arrives as new sessions inside the same families, speaking the same envelope, with the same canonical identity rules — which means an integration written against RaceHooks today is most of an integration with series that haven't launched yet. Formula 1 is live now; IndyCar and NASCAR are in development, and they inherit this structure rather than forking it.
That's also the honest reason the catalog is organized by question rather than by series: the questions are what carry over. Who's leading, who's pitting, what did race control just do, is rain coming, who won — every paddock in the world runs on those.
RaceHooks feeds are organized by the question they answer, not the wire they arrived on — nine families, one envelope, one identity system — so the taxonomy you integrate for Formula 1 is already the taxonomy for motorsport.