Skip to main content
The schedule_schema module validates the shape of packaged F1 schedule payloads. It contains one function, validate_schedule_payload. The tif1.events module calls it on the combined payload of the packaged schedule files the first time it reads them.

Overview

A schedule payload is a dict with this shape:
The metadata key holds per-event metadata. The validator does not check its contents.

validate_schedule_payload

Validate the shape of a schedule payload. The checks are plain type checks; this module does not use pydantic.
Any
required
Decoded JSON payload to validate.
Returns the validated payload, unchanged. The function checks, in this order:
  1. payload is a dict.
  2. payload["schema_version"] equals 1.
  3. payload["years"] is a dict.
Then it checks each year in turn, and does all of these checks for one year before the next year:
  1. The key is a string of digits, for example "2025".
  2. The value is a dict.
  3. events is a list of strings.
  4. sessions is a dict.
  5. For every event name in events: sessions[event_name] is a list of strings. An empty list passes.
The first failed check raises InvalidDataError with a reason string that names the problem and, where possible, the year and event involved. The module raises no other exception type.

Example

This example runs offline.

Error messages

Each failed check has its own reason string:

Where tif1 uses it

tif1.events loads the packaged schedule files from tif1/data/schedules/f1schedule/schedule_{year}.json and converts each year to the shape above. validate_schedule_payload then validates the combined payload, once per process. A validation failure stops event and schedule lookups before they read malformed data. The current season, future seasons, and years outside the packaged files come from the live theOehrly/f1schedule repository and skip this validator. Only the conversion step checks them. A live season that falls back to its packaged file reads it from the validated payload.
Last modified on October 15, 2026