{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://www.snowsure.ai/.well-known/schemas/avalanche-list-v1.json",
  "title": "SnowSure Avalanche List Contract v1",
  "description": "Many resorts' official avalanche bulletins in one response, RELAYED by SnowSure. SnowSure does not issue avalanche forecasts. Each item names its issuer and links to the authoritative bulletin.\n\nCRITICAL: a resort's ABSENCE from `data` carries no safety meaning. `meta.counts` reports where every considered resort landed and `meta.coverageNote` states this in full — never present a resort missing from this list as free of avalanche danger.",
  "type": "object",
  "required": ["schemaVersion", "schema", "meta", "data"],
  "additionalProperties": false,
  "properties": {
    "schemaVersion": { "type": "string", "const": "1.1.0" },
    "schema": { "type": "string", "format": "uri" },
    "meta": {
      "type": "object",
      "required": [
        "source",
        "generatedAt",
        "filters",
        "counts",
        "truncated",
        "relayed",
        "coverageNote",
        "disclaimer"
      ],
      "additionalProperties": false,
      "properties": {
        "source": { "type": "string", "const": "SnowSure" },
        "generatedAt": { "type": "string", "format": "date-time" },
        "filters": {
          "type": "object",
          "description": "The filters actually applied, after validation and clamping — not the raw query string.",
          "required": ["slugs", "country", "warningService", "minDanger", "limit"],
          "additionalProperties": false,
          "properties": {
            "slugs": {
              "oneOf": [{ "type": "array", "items": { "type": "string" } }, { "type": "null" }],
              "description": "Requested slugs (batch mode), or null for feed mode."
            },
            "country": { "oneOf": [{ "type": "string" }, { "type": "null" }] },
            "warningService": {
              "oneOf": [{ "type": "string", "enum": ["US", "CA", "CH", "FR", "SE", "AT", "IT", "NO", "DE", "ES", "AD", "GB", "SK", "SI", "CZ"] }, { "type": "null" }]
            },
            "minDanger": {
              "oneOf": [{ "type": "integer", "minimum": 1, "maximum": 5 }, { "type": "null" }],
              "description": "Result filter. Excludes bulletins with no published rating — see counts.rated."
            },
            "limit": { "type": "integer", "minimum": 1, "maximum": 500 }
          }
        },
        "counts": {
          "type": "object",
          "description": "Where every CONSIDERED resort landed, before minDanger and limit. Read these before drawing any conclusion from the length of `data`.",
          "required": [
            "bulletin",
            "outside_forecast_zone",
            "no_current_bulletin",
            "country_not_covered",
            "location_unknown",
            "relay_not_permitted",
            "resort_not_found",
            "considered",
            "rated",
            "returned"
          ],
          "additionalProperties": false,
          "properties": {
            "bulletin": { "type": "integer", "minimum": 0 },
            "outside_forecast_zone": { "type": "integer", "minimum": 0 },
            "no_current_bulletin": { "type": "integer", "minimum": 0 },
            "country_not_covered": { "type": "integer", "minimum": 0 },
            "location_unknown": { "type": "integer", "minimum": 0 },
            "relay_not_permitted": { "type": "integer", "minimum": 0 },
            "resort_not_found": { "type": "integer", "minimum": 0 },
            "considered": { "type": "integer", "minimum": 0 },
            "rated": {
              "type": "integer",
              "minimum": 0,
              "description": "Considered bulletins carrying an actual 1–5 rating. The rest published none."
            },
            "returned": { "type": "integer", "minimum": 0 }
          }
        },
        "truncated": {
          "type": "boolean",
          "description": "True when `limit` clipped results that otherwise matched."
        },
        "relayed": { "type": "boolean", "const": true },
        "coverageNote": {
          "type": "string",
          "description": "Why absence from this list is not an all-clear. Surface this wherever the list is rendered."
        },
        "disclaimer": { "type": "string" }
      }
    },
    "data": {
      "type": "array",
      "description": "In batch mode (`slugs` given), one item per requested slug in the order asked. In feed mode, only resorts with a bulletin, ordered by danger rating descending.",
      "items": {
        "type": "object",
        "required": ["slug", "coverage", "coverageDetail", "issuer", "link", "bulletin"],
        "additionalProperties": false,
        "properties": {
          "slug": { "type": "string" },
          "coverage": {
            "type": "string",
            "enum": [
              "bulletin",
              "outside_forecast_zone",
              "no_current_bulletin",
              "country_not_covered",
              "location_unknown",
              "relay_not_permitted",
              "resort_not_found"
            ],
            "description": "Why this item does or doesn't carry a bulletin. `bulletin` is the only value with a non-null `bulletin` field. `relay_not_permitted` means the issuer does not allow SnowSure to republish its bulletin: read it at `link`."
          },
          "coverageDetail": { "type": "string", "description": "Human-readable expansion of `coverage`, safe to render verbatim." },
          "issuer": { "oneOf": [{ "type": "string" }, { "type": "null" }] },
          "link": { "oneOf": [{ "type": "string", "format": "uri" }, { "type": "null" }] },
          "bulletin": {
            "description": "Identical to the single-resort endpoint's `data`, so an item maps onto that contract without translation.",
            "oneOf": [
              { "type": "null" },
              {
                "type": "object",
                "required": [
                  "slug",
                  "source",
                  "zoneName",
                  "issuer",
                  "link",
                  "dangerRating",
                  "dangerLabel",
                  "travelAdvice",
                  "validUntil",
                  "offSeason"
                ],
                "additionalProperties": false,
                "properties": {
                  "slug": { "type": "string" },
                  "source": { "type": "string", "enum": ["US", "CA", "CH", "FR", "SE", "AT", "IT", "NO", "DE", "ES", "AD", "GB", "SK", "SI", "CZ"] },
                  "zoneName": { "type": "string" },
                  "issuer": { "type": "string" },
                  "link": { "type": "string", "format": "uri" },
                  "dangerRating": {
                    "oneOf": [{ "type": "integer", "minimum": 1, "maximum": 5 }, { "type": "null" }],
                    "description": "EAWS / North American 5-level scale. Null means the issuer published NO rating — never a substituted value."
                  },
                  "dangerLabel": { "oneOf": [{ "type": "string" }, { "type": "null" }] },
                  "travelAdvice": { "oneOf": [{ "type": "string" }, { "type": "null" }] },
                  "validUntil": { "oneOf": [{ "type": "string" }, { "type": "null" }] },
                  "offSeason": { "type": "boolean" }
                }
              }
            ]
          }
        }
      }
    }
  }
}