StoreReadiness

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/sharpapi/main/json-schema/sharpapi-store-readiness-schema.json",
  "title": "StoreReadiness",
  "description": "Explains an empty `/odds` result set. Attached at `meta.store` only when zero rows are returned (September 2026); responses with rows are byte-identical to before and carry no `meta.store`. `books` and `rows` describe the whole snapshot the response was served from, not the matched set. `event_status` and `completed_at` (both optional) additionally name a finished event when the empty page was filtered on exactly one `event_id`.",
  "x-generated": "2026-10-14",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/sharpapi-openapi.json#/components/schemas/StoreReadiness",
  "type": "object",
  "required": [
    "generation",
    "ready",
    "books",
    "rows",
    "reason"
  ],
  "properties": {
    "generation": {
      "type": "integer",
      "description": "Snapshot generation this response was served from. `0` means nothing has been loaded since the process started."
    },
    "ready": {
      "type": "boolean",
      "description": "At least one refresh cycle has completed since the serving instance's last mode transition."
    },
    "books": {
      "type": "integer",
      "description": "Sportsbooks present in the snapshot this response was served from, independent of the query."
    },
    "rows": {
      "type": "integer",
      "description": "Total odds rows held by that snapshot, independent of the query — evidence that the store was populated, not a count of what the query would have matched."
    },
    "reason": {
      "type": "string",
      "enum": [
        "warming",
        "store_empty",
        "no_match"
      ],
      "description": "The field to branch on. `warming` = the serving instance has not completed a refresh cycle since its last mode transition, nothing is loaded yet (retry); `store_empty` = ready but the instance holds zero odds rows, e.g. mid-way through a store swap (retry — do not treat the empty page as authoritative); `no_match` = ready and populated, the query matched nothing (authoritative — retrying will not change the answer)."
    },
    "event_status": {
      "type": "string",
      "enum": [
        "final",
        "gone"
      ],
      "description": "Optional. Present only when the page is empty with `reason: \"no_match\"`, the request filtered on exactly one `event_id`, and that event is known to have ended. `final` = a settled completion is retained — the same record `/events/{eventId}` serves as `status: \"final\"`. `gone` = the event left the schedule within roughly the last hour with no settled completion (postponed, cancelled, or inside the ~5-minute settlement lag) — the same condition under which `/events/{eventId}` answers 410 Gone, and not a claim that it finished. Omitted for live/upcoming events, unknown ids, comma-separated multi-id filters, and on `warming` / `store_empty` pages. The status code is unchanged (200)."
    },
    "completed_at": {
      "type": "string",
      "format": "date-time",
      "description": "Optional. Accompanies `event_status: \"final\"` only — the time the completion was detected (typically a few minutes after the event left the live feed, not the final whistle), identical to `completed_at` on `/events/{eventId}`. Never present with `gone`."
    }
  }
}