ADR-0003 — Parameter identification and granule naming¶

Date: 2026-09-01 · Status: accepted (validated by prototype 5; amendments: one view per mosaic instead of a table, source_unit per granule, no replica notification — see ADR-0010)

Context¶

The platform serves physical quantities (temperature, pressure, wind, humidity, wave height…) that arrive through several vectors, each with its own code system and its own units:

Vector	Format	Code registry	Temperature, for example
Weather models (grids)	GRIB2	WMO GRIB2 code table 4.2 — discipline‑category‑number triplet; ECMWF Parameter DB / ecCodes — `paramId` + `shortName`	`0-0-0` · `130` / `t` · K
SYNOP surface observations	BUFR (FM 94)	WMO BUFR Table B — F‑X‑Y descriptor	`0 12 101` · K
METAR / SPECI / TAF aeronautical observations and forecasts	Traditional alphanumeric code (FM 15, FM 51, WMO‑306 Manual on Codes) and IWXXM (XML, the ICAO Annex 3 standard)	Code groups; IWXXM elements; in BUFR, the same descriptors as SYNOP	`M03/M05` group · integer °C
WAFS aeronautical grids (wind, temperature, icing, turbulence, CB)	GRIB2	WMO table 4.2 codes — ICAO defines no table of its own	same as models
Satellite imagery	GeoTIFF / NetCDF	WMO OSCAR/Space (satellite, instrument); WMO common tables C‑5 / C‑8	radiance, brightness temperature (K), reflectance (%)
All	—	CF standard names — name + canonical unit; WIGOS/WMDR observed variables	`air_temperature` · K

Two observations:

No single domain registry (GRIB2, BUFR, METAR) covers all vectors. Only the CF standard names vocabulary is common to grids and observations.
The same quantity arrives in different units depending on the vector (K in GRIB2 and BUFR, °C in METAR, hPa for QNH, knots for aeronautical wind). The unit is part of the data.

In addition, the names of raster files and GeoServer layers must remain readable for operations (debugging on S3, layer listings), without being the source of truth.

Decision¶

1. One physical quantity = one registry entry, several codes¶

Reference table parameter: one row per physical quantity, readable key (param_key, e.g. air_temperature), cf_standard_name, canonical unit (UCUM notation: K, Pa, m/s, %), label.
Table parameter_code: one row per known code of that quantity, with the scheme (grib2, eccodes, bufr, metar, iwxxm, cf), the code and the unit in that scheme. Adding a vector = adding rows, no migration.
Ingestion resolves the source code → parameter, converts to the canonical unit and keeps the source unit alongside the value.

2. Vertical dimension coded with WMO table 4.5¶

Table level_type: GRIB2 table 4.5 code (1 surface, 100 isobaric surface in Pa, 103 height above ground in m, 101 mean sea level…), name, unit.
Aeronautical flight levels (FL) have no native 4.5 code: they are stored as an isobaric surface (standard atmosphere) with a label FL300 kept in a dedicated column.
Two different level types never share the same ELEVATION dimension: they are separate layers.

3. One GeoServer layer = one quantity, one unit, one style¶

Models: one ImageMosaic per (model, quantity) pair, filtered by a SQL view over the granule table; exposed dimensions TIME = forecast validity time, DIM_REFERENCE_TIME = model run, ELEVATION = level.
Satellites: one ImageMosaic per (satellite, instrument, product) triple; TIME dimension.
The layer's unit is published in its metadata and its legend (exact mechanism to be validated in prototype 5).

4. File naming (redundant with the table, never the source of truth)¶

Nature	Pattern	Example
Satellite	`{satellite}_{instrument}_{product}_{YYYYMMDDThhmmZ}.tif`	`meteosat-12_fci_ir105_20260901T1200Z.tif`
Model	`{model}_{param}_{levelType}{level}_{runYYYYMMDDThhZ}_{validYYYYMMDDThhZ}.tif`	`arpege_t_isobaric85000_20260901T00Z_20260901T12Z.tif`

param = ecCodes shortName (readable and unambiguous for grids); satellite/instrument identifiers follow OSCAR/Space in lowercase.

5. Observations in a time-series database¶

SYNOP / METAR / SPECI / TAF messages are decoded into an observation hypertable (station, time, quantity, canonical value, source unit, message type) published through SQL views. Details in sub-project 6.

Rejected alternatives¶

Alternative	Why rejected
Pivot = GRIB2 triplet alone	Does not cover SYNOP/METAR observations or satellite products
Pivot = ECMWF `paramId` alone	Specific to ecCodes; no mapping for BUFR/METAR; numbers are hard to read
A single ImageMosaic per model with the quantity as a custom dimension	One layer would carry several units and several styles; ambiguous legend and GetFeatureInfo
Unit inferred from the file name or the style	The unit must be data, not an implicit convention
Keeping the source unit without conversion	Clients would need to know the originating vector to interpret the value

Consequences¶

The parameter / parameter_code / level_type registry is a deliverable of sub-projects 1 (schema) and 5 (initial load from the WMO / ECMWF / CF registers).
The ingestion service (sub-project 5) owns the unit conversion; it rejects a file or a message whose code cannot be resolved.
The decision will be confirmed or amended after prototypes 5 (mosaics) and 6 (observations), in particular regarding unit publication on the GeoServer side.