{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/fluvigil-de/json-schema/fluvigil-de-station-list-item-schema.json",
  "title": "StationListItem",
  "x-generated": "2026-11-08",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/fluvigil-de-openapi.yaml#/components/schemas/StationListItem",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "source": {
      "$ref": "#/$defs/GaugeSource"
    },
    "measurementType": {
      "type": "string",
      "enum": [
        "river",
        "groundwater",
        "sea_level",
        "reservoir"
      ]
    },
    "waterClass": {
      "$ref": "#/$defs/WaterClass"
    },
    "levelDatum": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "swiss_sea_level",
        "adriatic_sea_level",
        "normal_null",
        "dvr90",
        null
      ],
      "description": "Height datum of a gauge that reports an absolute elevation instead of a level over its gauge zero; null for a level over gauge zero. Such a gauge stores the elevation times the detail's `valueDivisor` in `latestValueCentimeters` and carries no flood classification.\n"
    },
    "name": {
      "type": "string"
    },
    "water": {
      "type": [
        "string",
        "null"
      ]
    },
    "latitude": {
      "type": "number"
    },
    "longitude": {
      "type": "number"
    },
    "federalState": {
      "type": [
        "string",
        "null"
      ]
    },
    "infoLink": {
      "type": [
        "string",
        "null"
      ]
    },
    "sourceNotice": {
      "oneOf": [
        {
          "$ref": "#/$defs/SourceNotice"
        },
        {
          "type": "null"
        }
      ],
      "description": "The notice the gauge's provider demands wherever its values are shown; null where none can be built, and the gauge then delivers no value. Pass it on with the values.\n"
    },
    "latestValueCentimeters": {
      "type": [
        "number",
        "null"
      ]
    },
    "latestMeasuredAt": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "refreshCadenceHours": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 1,
      "description": "How often the gauge's source publishes new values, in hours, when that is slower than the gauge type's own freshness window (24 for a daily export). A value counts as outdated only after twice this interval; null when the type's window applies.\n"
    },
    "levelState": {
      "type": [
        "string",
        "null"
      ],
      "description": "PEGELONLINE MNW/MHW classification"
    },
    "lhpClass": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": -1,
      "maximum": 4
    },
    "lhpClassName": {
      "type": [
        "string",
        "null"
      ]
    },
    "isActive": {
      "type": "boolean"
    },
    "floodWarning": {
      "oneOf": [
        {
          "$ref": "#/$defs/FloodWarning"
        },
        {
          "type": "null"
        }
      ],
      "description": "The warning of the river section this gauge stands on, for countries that publish their flood warning per section instead of per gauge (France, Vigicrues). Null for every other gauge and for a French gauge on no monitored section.\n"
    },
    "levelClassification": {
      "allOf": [
        {
          "$ref": "#/$defs/LevelClassification"
        }
      ],
      "description": "Coarse plain-language summary for map/list use, derived without a threshold join (from lhpClass / levelState). The station detail carries the precise, threshold-based classification inside `levelContext`.\n"
    }
  },
  "$defs": {
    "FloodWarning": {
      "type": "object",
      "description": "A flood warning published for a whole river section. It describes the reach the gauge stands in, never the gauge's own level, and the official warning stays with the named service.\n",
      "properties": {
        "provider": {
          "type": "string",
          "enum": [
            "vigicrues"
          ]
        },
        "providerLabel": {
          "type": "string",
          "description": "Credit line of the warning service."
        },
        "sectionCode": {
          "type": "string",
          "description": "The provider's section code, e.g. SA13."
        },
        "sectionName": {
          "type": "string"
        },
        "level": {
          "type": "integer",
          "minimum": 1,
          "maximum": 4,
          "description": "1 no particular vigilance, 2 vigilance, 3 strong flood, 4 exceptional flood."
        },
        "levelLabel": {
          "type": "string"
        },
        "severity": {
          "type": "string",
          "enum": [
            "low",
            "normal",
            "elevated",
            "high",
            "veryHigh",
            "unknown"
          ]
        },
        "publishedAt": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "infoUrl": {
          "type": "string"
        },
        "assignmentSource": {
          "type": "string",
          "enum": [
            "list",
            "geometry"
          ],
          "description": "Whether the provider's own station list named this gauge on this section ('list'), or it was matched to the nearest section by geographic distance because the list did not ('geometry') — a weaker match, worth treating with more caution.\n"
        }
      }
    },
    "GaugeSource": {
      "type": "string",
      "description": "Key of the data source a station comes from.",
      "enum": [
        "pegelonline",
        "lhp",
        "gld",
        "ltv",
        "nlwkn",
        "ch",
        "at",
        "cz",
        "lu",
        "it-bz",
        "fr",
        "dk-dmi",
        "dk",
        "nl",
        "pl",
        "be"
      ]
    },
    "LevelClassification": {
      "type": "object",
      "description": "Deterministic plain-language interpretation of the current level, anchored on what the threshold means (reporting level / statistical reference). Never asserts location-specific effects, which are Land-dependent and not verifiable per station.\n",
      "properties": {
        "severity": {
          "type": "string",
          "enum": [
            "low",
            "normal",
            "elevated",
            "high",
            "veryHigh",
            "unknown"
          ]
        },
        "headline": {
          "type": "string"
        },
        "description": {
          "type": "string"
        }
      }
    },
    "SourceNotice": {
      "description": "Conditions a data provider attaches to its gauges, set wherever a gauge's values are delivered. The fields of `SourceNoticePart` describe the source of the values; `parts` lists every source involved (the value source first, the station source after it where they differ), and `form` is `full-only` as soon as one part is. `sourceLine`, `rawData`, `disclaimer`, `noOfficialWarning` and `termsPath` are the older plain-text fields and stay for existing clients; the three that a provider does not demand are null.\n",
      "allOf": [
        {
          "$ref": "#/$defs/SourceNoticePart"
        },
        {
          "type": "object",
          "properties": {
            "parts": {
              "type": "array",
              "description": "The notice of every source involved, each with the fields from `id` to `textShort`.",
              "items": {
                "$ref": "#/$defs/SourceNoticePart"
              }
            },
            "sourceLine": {
              "type": "string",
              "description": "Credit line of the provider"
            },
            "rawData": {
              "type": [
                "string",
                "null"
              ],
              "description": "Notice that the values are preliminary or unchecked raw data"
            },
            "disclaimer": {
              "type": [
                "string",
                "null"
              ],
              "description": "Liability disclaimer with the pointer to the terms"
            },
            "noOfficialWarning": {
              "type": [
                "string",
                "null"
              ],
              "description": "Statement that the presentation is no official warning"
            },
            "termsPath": {
              "type": "string",
              "description": "Path of the terms page holding the full liability disclaimer"
            }
          }
        }
      ]
    },
    "SourceNoticePart": {
      "type": "object",
      "description": "The conditions of one source involved in the values a gauge shows.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Key of the source record the notice part comes from: a station source (`pegelonline`, `ch`, `lhp`, ...), a state value source (`ni-nlwkn`, `th-hnz`, ...), or `salzburg` / `niederoesterreich` for those two Austrian variants.\n"
        },
        "form": {
          "type": "string",
          "enum": [
            "short-allowed",
            "full-only"
          ],
          "description": "`full-only` when the provider approved paragraphs that must never be shortened"
        },
        "permissionBasis": {
          "type": "string",
          "enum": [
            "licence",
            "statutory-access",
            "written-consent",
            "licence-and-consent"
          ]
        },
        "licence": {
          "type": [
            "object",
            "null"
          ],
          "description": "The licence the permission rests on; null for statutory access and written consent alone.",
          "properties": {
            "name": {
              "type": "string"
            },
            "url": {
              "type": "string"
            }
          }
        },
        "sourceName": {
          "type": "string"
        },
        "sourceUrl": {
          "type": "string"
        },
        "rightsHolder": {
          "type": "string"
        },
        "fetchedAt": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time",
          "description": "When Fluvigil fetched the values (UTC); null where not known"
        },
        "stampedAt": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time",
          "description": "The provider's own time stamp (\"Stand\") where its licence keeps it visible"
        },
        "stationLink": {
          "type": [
            "string",
            "null"
          ],
          "description": "Origin page of this gauge where the provider demands it"
        },
        "text": {
          "type": "string",
          "description": "The full notice as plain text"
        },
        "textShort": {
          "type": [
            "string",
            "null"
          ],
          "description": "The shortened notice; null for `full-only`"
        }
      }
    },
    "WaterClass": {
      "type": "string",
      "enum": [
        "river",
        "lake",
        "coast",
        "groundwater"
      ],
      "description": "The group a gauge belongs to on the map and in filters: rivers, lakes and reservoirs, coast and tide, groundwater. Stored per gauge; a tidal river section is `river` by `measurementType` and `coast` by class.\n"
    }
  }
}