{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://www.smokewindow.com/agents/forecast.schema.json",
  "title": "Smoke Window local forecast response",
  "description": "Structured output from the Smoke Window local JavaScript, CLI, browser-runner, and MCP interfaces.",
  "$ref": "#/$defs/response",
  "$defs": {
    "input": {
      "type": "object",
      "properties": {
        "location": {
          "type": "string",
          "minLength": 2,
          "maxLength": 80,
          "description": "Lower-48 U.S. city and state."
        },
        "latitude": {
          "type": "number",
          "minimum": 20,
          "maximum": 55
        },
        "longitude": {
          "type": "number",
          "minimum": -130,
          "maximum": -60
        },
        "name": {
          "type": "string",
          "maxLength": 80
        },
        "state": {
          "type": "string",
          "maxLength": 80
        },
        "timezone": {
          "type": "string",
          "maxLength": 80
        },
        "radiusMiles": {
          "type": "number",
          "minimum": 1,
          "maximum": 200,
          "default": 100
        }
      },
      "oneOf": [
        {
          "required": ["location"],
          "not": {
            "anyOf": [
              { "required": ["latitude"] },
              { "required": ["longitude"] }
            ]
          }
        },
        {
          "required": ["latitude", "longitude"],
          "not": { "required": ["location"] }
        }
      ],
      "additionalProperties": false
    },
    "forecastPoint": {
      "type": "object",
      "required": [
        "valid_time_utc",
        "valid_time_local",
        "forecast_hour",
        "category",
        "concentration_band_ug_m3",
        "approximate_midpoint_ug_m3",
        "source_frame"
      ],
      "properties": {
        "valid_time_utc": { "type": "string", "format": "date-time" },
        "valid_time_local": { "type": "string" },
        "forecast_hour": {
          "type": "integer",
          "minimum": 0,
          "maximum": 48,
          "multipleOf": 3
        },
        "category": {
          "enum": ["low", "light", "smoky", "heavy", "very-heavy"]
        },
        "concentration_band_ug_m3": { "type": "string" },
        "approximate_midpoint_ug_m3": { "type": "number" },
        "source_frame": { "type": "string", "format": "uri" }
      },
      "additionalProperties": false
    },
    "clearWindow": {
      "type": "object",
      "required": ["status", "startHour", "endHour", "startTime", "endTime"],
      "properties": {
        "status": {
          "enum": ["clear_now", "clears_at", "no_clear_window"]
        },
        "startHour": {
          "type": ["integer", "null"],
          "minimum": 0,
          "maximum": 48,
          "multipleOf": 3
        },
        "endHour": {
          "type": ["integer", "null"],
          "minimum": 0,
          "maximum": 48,
          "multipleOf": 3
        },
        "startTime": {
          "type": ["string", "null"],
          "format": "date-time"
        },
        "endTime": {
          "type": ["string", "null"],
          "format": "date-time"
        }
      },
      "additionalProperties": false
    },
    "airQualityObservation": {
      "type": "object",
      "required": [
        "reportingArea",
        "state",
        "latitude",
        "longitude",
        "distanceMiles",
        "aqi",
        "category",
        "primaryPollutant",
        "validTime",
        "agency",
        "sourceUpdatedAt",
        "preliminary",
        "pollutants"
      ],
      "properties": {
        "reportingArea": { "type": "string" },
        "state": { "type": "string" },
        "latitude": { "type": "number" },
        "longitude": { "type": "number" },
        "distanceMiles": { "type": "number", "minimum": 0 },
        "aqi": { "type": "integer", "minimum": 0 },
        "category": { "type": "string" },
        "primaryPollutant": { "type": "string" },
        "validTime": { "type": "string", "format": "date-time" },
        "agency": { "type": "string" },
        "sourceUpdatedAt": {
          "type": ["string", "null"]
        },
        "preliminary": { "const": true },
        "pollutants": {
          "type": "array",
          "items": {
            "type": "object",
            "required": ["code", "aqi", "category", "isPrimary"],
            "properties": {
              "code": { "type": "string" },
              "aqi": { "type": "integer", "minimum": 0 },
              "category": { "type": "string" },
              "isPrimary": { "type": "boolean" }
            },
            "additionalProperties": false
          }
        }
      },
      "additionalProperties": false
    },
    "fireIncident": {
      "type": "object",
      "required": [
        "id",
        "name",
        "latitude",
        "longitude",
        "distanceMiles",
        "acres",
        "containment",
        "discoveredAt",
        "updatedAt",
        "description",
        "type"
      ],
      "properties": {
        "id": { "type": "string" },
        "name": { "type": "string" },
        "latitude": { "type": "number" },
        "longitude": { "type": "number" },
        "distanceMiles": { "type": "number", "minimum": 0 },
        "acres": { "type": ["number", "null"], "minimum": 0 },
        "containment": {
          "type": ["number", "null"],
          "minimum": 0,
          "maximum": 100
        },
        "discoveredAt": {
          "type": ["string", "null"],
          "format": "date-time"
        },
        "updatedAt": {
          "type": ["string", "null"],
          "format": "date-time"
        },
        "description": { "type": ["string", "null"] },
        "type": { "enum": ["WF", "CX"] }
      },
      "additionalProperties": false
    },
    "airQualityResult": {
      "oneOf": [
        {
          "type": "object",
          "required": ["status", "data"],
          "properties": {
            "status": { "const": "available" },
            "data": {
              "type": "object",
              "required": [
                "checked_at",
                "source_updated_at",
                "observation",
                "note"
              ],
              "properties": {
                "checked_at": { "type": "string", "format": "date-time" },
                "source_updated_at": { "type": ["string", "null"] },
                "observation": {
                  "oneOf": [
                    { "$ref": "#/$defs/airQualityObservation" },
                    { "type": "null" }
                  ]
                },
                "note": { "type": "string" }
              },
              "additionalProperties": false
            }
          },
          "additionalProperties": false
        },
        {
          "type": "object",
          "required": ["status", "data", "error"],
          "properties": {
            "status": { "const": "unavailable" },
            "data": { "type": "null" },
            "error": { "type": "string" }
          },
          "additionalProperties": false
        }
      ]
    },
    "fireResult": {
      "oneOf": [
        {
          "type": "object",
          "required": ["status", "data"],
          "properties": {
            "status": { "const": "available" },
            "data": {
              "type": "object",
              "required": [
                "checked_at",
                "source_updated_at",
                "radius_miles",
                "total_count",
                "returned_count",
                "truncated",
                "incidents",
                "note"
              ],
              "properties": {
                "checked_at": { "type": "string", "format": "date-time" },
                "source_updated_at": { "type": ["string", "null"] },
                "radius_miles": {
                  "type": "number",
                  "minimum": 1,
                  "maximum": 200
                },
                "total_count": { "type": "integer", "minimum": 0 },
                "returned_count": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 25
                },
                "truncated": { "type": "boolean" },
                "incidents": {
                  "type": "array",
                  "maxItems": 25,
                  "items": { "$ref": "#/$defs/fireIncident" }
                },
                "note": { "type": "string" }
              },
              "additionalProperties": false
            }
          },
          "additionalProperties": false
        },
        {
          "type": "object",
          "required": ["status", "data", "error"],
          "properties": {
            "status": { "const": "unavailable" },
            "data": { "type": "null" },
            "error": { "type": "string" }
          },
          "additionalProperties": false
        }
      ]
    },
    "response": {
      "type": "object",
      "required": [
        "schema_version",
        "provider",
        "provider_url",
        "source_url",
        "suggested_citation",
        "generated_at",
        "location",
        "modeled_smoke",
        "observed_air_quality",
        "nearby_fires",
        "sources",
        "limitations"
      ],
      "properties": {
        "schema_version": { "const": "1.0" },
        "provider": { "const": "Smoke Window" },
        "provider_url": {
          "const": "https://www.smokewindow.com"
        },
        "source_url": { "type": "string", "format": "uri" },
        "suggested_citation": { "type": "string" },
        "generated_at": { "type": "string", "format": "date-time" },
        "location": {
          "type": "object",
          "required": [
            "name",
            "state",
            "latitude",
            "longitude",
            "timezone"
          ],
          "properties": {
            "name": { "type": "string" },
            "state": { "type": "string" },
            "latitude": { "type": "number" },
            "longitude": { "type": "number" },
            "timezone": { "type": "string" }
          },
          "additionalProperties": false
        },
        "modeled_smoke": {
          "type": "object",
          "required": [
            "status",
            "model",
            "model_run_time",
            "checked_at",
            "horizon_hours",
            "interval_hours",
            "current_forecast_hour",
            "current_point",
            "clear_window",
            "summary",
            "threshold",
            "points"
          ],
          "properties": {
            "status": { "const": "available" },
            "model": { "const": "NOAA HRRR-Smoke" },
            "model_run_time": { "type": "string", "format": "date-time" },
            "checked_at": { "type": "string", "format": "date-time" },
            "horizon_hours": { "const": 48 },
            "interval_hours": { "const": 3 },
            "current_forecast_hour": {
              "type": "integer",
              "minimum": 0,
              "maximum": 48,
              "multipleOf": 3
            },
            "current_point": { "$ref": "#/$defs/forecastPoint" },
            "clear_window": { "$ref": "#/$defs/clearWindow" },
            "summary": {
              "type": "object",
              "required": ["label", "headline", "detail"],
              "properties": {
                "label": { "type": "string" },
                "headline": { "type": "string" },
                "detail": { "type": "string" }
              },
              "additionalProperties": false
            },
            "threshold": {
              "type": "object",
              "required": [
                "definition",
                "below_ug_m3",
                "consecutive_samples",
                "sample_interval_hours"
              ],
              "properties": {
                "definition": { "type": "string" },
                "below_ug_m3": { "const": 4 },
                "consecutive_samples": { "const": 2 },
                "sample_interval_hours": { "const": 3 }
              },
              "additionalProperties": false
            },
            "points": {
              "type": "array",
              "minItems": 17,
              "maxItems": 17,
              "items": { "$ref": "#/$defs/forecastPoint" }
            }
          }
        },
        "observed_air_quality": { "$ref": "#/$defs/airQualityResult" },
        "nearby_fires": { "$ref": "#/$defs/fireResult" },
        "sources": {
          "type": "array",
          "minItems": 4,
          "items": {
            "type": "object",
            "required": ["name", "url", "role"],
            "properties": {
              "name": { "type": "string" },
              "url": { "type": "string", "format": "uri" },
              "role": { "type": "string" }
            },
            "additionalProperties": false
          }
        },
        "limitations": {
          "type": "array",
          "minItems": 1,
          "items": { "type": "string" }
        }
      },
      "additionalProperties": false
    }
  }
}