Files follow the naming convention dataset_yyyy-MM-dd'T'HHmmssSSSSSS'Z'.json, where dataset is replaced by public_warnings for the KNMI-public-weather-warnings dataset and replaced by professional_warnings for the KNMI-public-weather-warnings-extended dataset.

A dataset is published whenever the status of a warning changes. Publications are ad-hoc, except for an automatically generated daily heartbeat at 05:30 UTC (publication_type = heartbeat), which repeats the previous warning state to confirm that the publication chain is operational.

Each file is a complete snapshot containing all warnings and early indications of potentially dangerous weather known at the file's generation time.

Treat each successively published file as a full replacement for the preceding snapshot, not as a list of incremental changes. A snapshot with an empty warnings array is a valid representation of a state with no warning sets.

The top-level JSON object contains publication metadata, two counters and an array of warning sets. A warning set represents one or multiple warnings for a dangerous weather event. Its parts array contains the individual warning areas, time periods, severity levels and probability ranges.

Process each snapshot as a complete state:

1. Parse the file as JSON and validate it against the JSON schema.
2. Check metadata.schema_version before applying version-specific processing rules.
3. Inspect metadata.publication_type and warnings[].operational_status so test or exercise information is not presented as an actual warning.
4. Confirm that num_warning_sets equals the number of objects in warnings.
5. Confirm that num_warnings equals the sum of the lengths of all parts arrays.
6. Build the replacement state completely before replacing the preceding successfully processed snapshot.
7. Use warning_set_uuid and part_uuid as stable identities to relate objects across successive snapshots; use version_id and version_dt to detect updates.
8. Use warning_type to distinguish warnings from early indications of potentially dangerous weather.
9. Use phenomenon to group or filter warning sets by weather hazard.
10. Use warning-part severity, color, probability and geometry to present the affected situation.
11. Use publication_type and operational_status to separate operational warning information from heartbeats (automatically generated publication (daily at 05:30 UTC) that repeats the previous warning state to demonstrate that the publication chain is alive) and publications for test purposes.

metadata.publication_type has the following meanings:

On WarningSet level, operational_status determines how an individual warning set must be handled:

Refer to the JSON schema for more details.

Top-level snapshot

Metadata

WarningSet

For more details, such as a full list of all possible phenomena, refer to the JSON schema.

Two warning sets with the same phenomenon must not overlap in time. This is a business rule and is not enforced by the JSON Schema.

WarningPart

Note there is a one-to-one relationship between severity and color:

For more details, such as a full list of values for certain string fields, refer to the JSON schema.

List of phenomena and probability thresholds

The KNMI-public-weather-warnings-extended dataset contains all issued warnings ("warning_type": "warning") and it contains Potentially Dangerous Weather objects ("warning_type": "potentially-dangerous-weather") at lower probability than the KNMI-public-weather-warnings dataset (see table below). This dataset is intended for professional users, and some of the warnings it contains are not relevant to the general public. Some "potentially dangerous weather" objects have such a low probability of occurrence that the general public is not expected to take them into account when making decisions. However, these low-probability events may still be relevant to professional users, who may need to prepare for the possibility of severe weather even when it is unlikely to occur.

The dataset KNMI-public-weather-warnings, on the other hand, is filtered for use by the general public. Only relevant warnings for this audience are present and their content matches the other communication outlets of KNMI visible to the public e.g. website and app. Filtering is based on probability of occurance and is only applicable to early warnings (warning_type equals potentially-dangerous-weather). Potentially dangerous weather warnings are defined as having an onset later than >48h ahead, or when onset of an event is within 48 hours, with small likelihood of occurance. When warning_type equals warning, the warning is published to both the general and the extended dataset.

The following table lists the phenomena in English, Dutch, the corresponding phenomena in MeteoAlarm and the probability thresholds used for this filtering.

A WarningSet groups one or more WarningPart objects for the same weather phenomenon for a specific weather event. Information that applies to the entire event is stored on the warning set (e.g. guidance); area-specific and time-specific information is stored on its warning parts.

The ordering of the parts array may change. Consumers must use part_uuid, not array position, to relate a warning part across snapshots.

The warning-set onset is equal to or earlier than the first onset of its warning parts, and its expiration is equal to or later than the last expiration timestamp of its parts.

incident.incident_uuid can link warning sets for different phenomena to one incident, such as a named storm.

The lifecycle status values for warning sets and warning parts are:

A cancelled or expired warning set or warning part appears in a snapshot one more time.

Use the stable UUID to identify the logical object and version_id to distinguish revisions. Do not assume that array order represents recency.

The schema does not enforce that version IDs increase by one, that version dates are monotonic, or that warning-set and warning-part version changes occur together.

texts contains meteorologist-authored information in Dutch and English.

guidance is enriched information. A language-specific guidance object can contain optional impact and instruction strings, each of which may also be null.

Each warning part contains an area described as a GeoJSON RFC 7946 Polygon or MultiPolygon in WGS 84. Coordinate positions are ordered as [longitude, latitude].

The Coordinates definition requires exactly two numeric items. The schema uses ge and le for intended coordinate bounds.

Any rings in the geometry are closed, polygons do not have holes and are counterclockwise.

The geometry type property has a default ("Polygon" or "MultiPolygon").

Example shape:

{
  "type": "Polygon",
  "coordinates": [[
    [3.2, 51.3],
    [6.1, 51.3],
    [6.1, 53.6],
    [3.2, 53.6],
    [3.2, 51.3]
  ]]
}