OutlookDetail

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/smarterweather-com/json-schema/smarterweather-com-outlook-detail-schema.json",
  "title": "OutlookDetail",
  "description": "Drill-down detail for one SPC convective outlook day at a\nlocation: the categorical risk band, each probabilistic hazard,\nand the forecaster's written discussion. For the CPC hazards\n(`temperature`, `precipitation`) it carries `periods` instead.\n\nEverything except `day` and `probabilities` is optional. A point\ncan sit inside\na categorical polygon with no probabilistic coverage, and the\nnarrative is ingested separately from the polygons so it can lag\na fresh issuance.\n",
  "x-generated": "2026-10-30",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/smarterweather-com-openapi.yaml#/components/schemas/OutlookDetail",
  "type": "object",
  "required": [
    "day",
    "probabilities"
  ],
  "properties": {
    "day": {
      "type": "integer",
      "minimum": 1,
      "maximum": 8,
      "description": "The outlook day this detail describes (1 = today). For the\nCPC hazards (`temperature`, `precipitation`) it is always `1`\nand carries no meaning; use each period's `valid_start` and\n`valid_end`.\n"
    },
    "categorical": {
      "$ref": "#/$defs/Outlook"
    },
    "dry_thunderstorm": {
      "allOf": [
        {
          "$ref": "#/$defs/Outlook"
        }
      ],
      "description": "The SPC dry-thunderstorm fire band (`IDRT` isolated or `SDRT`\nscattered), present only for `hazard=fire`.\n\nSPC draws two independent fire criteria per day and publishes\neach as its own layer: the wind/RH criterion\n(`elevated`/`critical`/`extremely critical`) in `categorical`,\nand the lightning-ignition criterion here. Either can have\nareas on a day the other has none, and both can cover one\npoint, so read them as separate criteria rather than tiers of\none scale -- a scattered dry thunderstorm area is not \"worse\nthan\" an extremely critical one.\n"
    },
    "probabilities": {
      "type": "array",
      "description": "One entry per probabilistic hazard covering the point. Days\n1-2 break these out as `tornado`, `wind`, and `hail`; day 3\nand beyond issue a single combined `probabilistic` product.\nEmpty when no probabilistic polygon covers the location.\nCategorical bands never appear here.\n",
      "items": {
        "$ref": "#/$defs/Outlook"
      }
    },
    "periods": {
      "type": "array",
      "description": "CPC climate outlooks at the location for\n`hazard=temperature|precipitation`, one per period in the\norder 6-10 day, 8-14 day, week 3-4, monthly. A period with no\noutlook polygon at the location is omitted. Absent for the\nother hazards.\n",
      "items": {
        "$ref": "#/$defs/ClimateOutlook"
      }
    },
    "narrative": {
      "$ref": "#/$defs/OutlookNarrative"
    }
  },
  "$defs": {
    "ClimateOutlook": {
      "type": "object",
      "description": "One CPC temperature or precipitation outlook period at a\nlocation: the tercile CPC favors and the probability bin it\nassigns to it.\n",
      "required": [
        "product_id",
        "period",
        "variable",
        "category",
        "issued_at"
      ],
      "properties": {
        "product_id": {
          "type": "string",
          "description": "Upstream product identifier."
        },
        "period": {
          "type": "string",
          "enum": [
            "610",
            "814",
            "wk34",
            "monthly",
            "seasonal"
          ],
          "description": "`610` (6-10 day), `814` (8-14 day), `wk34` (week 3-4),\n`monthly` (a calendar month), or `seasonal` (a three-month\nseason; see `lead`). `GET /v1/outlooks` returns only the\nfirst four, one entry each. `GET /v1/outlooks/climate` can\nreturn two `monthly` entries per variable: this month, plus\nnext month from CPC's mid-month seasonal release until the\nmonth-end monthly update. Entries are unique by (`period`,\n`variable`, `valid_start`).\n"
        },
        "lead": {
          "type": "integer",
          "minimum": 1,
          "maximum": 13,
          "description": "The seasonal lead, for `period: seasonal` only. CPC issues 13\noverlapping three-month outlooks; lead 1 starts the month\nafter issuance and each later lead starts one month later.\n"
        },
        "valid_label": {
          "type": "string",
          "description": "CPC's name for the outlook window, for `monthly` and\n`seasonal` entries from `GET /v1/outlooks/climate`: a month\n(`Oct 2026`) or a three-month season of month initials\n(`NDJ 2026-2027`).\n"
        },
        "variable": {
          "type": "string",
          "enum": [
            "temperature",
            "precipitation"
          ]
        },
        "category": {
          "type": "string",
          "enum": [
            "above",
            "below",
            "near",
            "equal_chances"
          ],
          "description": "The favored tercile. `near` means near normal is favored;\n`equal_chances` means CPC favors no tercile.\n"
        },
        "probability_min": {
          "type": "number",
          "format": "double",
          "minimum": 0,
          "maximum": 1,
          "description": "Lower edge of the favored category's probability bin,\nfractional (`0.4` = 40%). Omitted for `equal_chances`.\n"
        },
        "probability_max": {
          "type": "number",
          "format": "double",
          "minimum": 0,
          "maximum": 1,
          "description": "Upper edge of the favored category's probability bin,\nfractional. Omitted for `equal_chances`.\n"
        },
        "label": {
          "type": "string",
          "description": "Human-readable category and bin."
        },
        "valid_start": {
          "type": "string",
          "format": "date-time",
          "description": "Start of the outlook period."
        },
        "valid_end": {
          "type": "string",
          "format": "date-time",
          "description": "End of the outlook period (exclusive)."
        },
        "issued_at": {
          "type": "string",
          "format": "date-time",
          "description": "When CPC issued the outlook."
        }
      }
    },
    "Outlook": {
      "type": "object",
      "description": "Single SPC convective outlook (or equivalent product) active for\nthe location.\n",
      "required": [
        "product_id",
        "type",
        "day",
        "risk_label",
        "valid",
        "expires"
      ],
      "properties": {
        "product_id": {
          "type": "string",
          "description": "Upstream product identifier (e.g., `spc_otlk_day1`)."
        },
        "type": {
          "type": "string",
          "description": "Hazard category (`severe`, `tornado`, `hail`, `wind`, etc.)."
        },
        "day": {
          "type": "integer",
          "minimum": 1,
          "maximum": 8,
          "description": "Day number relative to issuance (1 = today)."
        },
        "risk": {
          "type": "string",
          "description": "Raw risk identifier from the upstream source."
        },
        "probability": {
          "type": "number",
          "format": "double",
          "minimum": 0,
          "maximum": 1,
          "description": "Fractional probability (0-1) when the source provides one."
        },
        "risk_label": {
          "type": "string",
          "description": "Human-readable risk label."
        },
        "valid": {
          "type": "string",
          "format": "date-time"
        },
        "expires": {
          "type": "string",
          "format": "date-time"
        },
        "significant": {
          "type": "boolean",
          "description": "The location falls inside SPC's hatched significant-severe\narea for this hazard — tornadoes of EF2+, hail 2 in or\nlarger, or wind gusts of 65 kt or more.\n\nSPC ships this as its own polygon, so it is reported here as\na flag on the hazard it qualifies rather than as a separate\nentry. Absent (or `false`) outside the hatched area.\n"
        }
      }
    },
    "OutlookNarrative": {
      "type": "object",
      "description": "The SPC forecaster's written discussion for an outlook day, as\nissued in the corresponding SWO text product.\n",
      "properties": {
        "awips_id": {
          "type": "string",
          "description": "AWIPS identifier of the source product — `SWODY1`, `SWODY2`,\n`SWODY3` for the single-day outlooks, `SWOD48` for days 4-8,\n`PMDMRD` for the CPC 6-10/8-14 day discussion.\n"
        },
        "issued_at": {
          "type": "string",
          "format": "date-time"
        },
        "body": {
          "type": "string",
          "description": "Full narrative text as written by the forecaster."
        },
        "summary": {
          "type": "string",
          "description": "Short generated summary, when one is available."
        }
      }
    }
  }
}