Data schemas & provenance
Category-specific canonical schemas, unit normalization and integrity validation.
On this page 3 sections
#Canonical envelope
{
"data": { "schema_version": "weather.v1", "...": "product fields" },
"meta": {
"request_id": "req_01J...",
"timestamp": "2026-11-18T04:30:00Z",
"provider": "openweather",
"cached": false,
"fallback": false,
"attribution": [
{ "provider": "openweather", "text": "Weather data provided by OpenWeather" }
]
}
}Each data category has its own versioned schema package under schemas/ and is cataloged in internal/normalization/catalog.go.
#Integrity and scientific honesty
Current weather (weather.v1) represents station/realtime observations using observed_at (enforcing ≤2h age and ≤15m future skew, Kelvin/Fahrenheit converted to Celsius). Forecasts (forecast.v1, forecast.daily.v1) and marine (marine.v1) use valid_at model predictions. Air quality (air_quality.v1) uses modeled CAMS concentrations. History (history.v1) is ERA5 reanalysis. Astronomy (astronomy.v1) is calculated solar/lunar events with validated portable IANA timezones. Alerts (alerts.v1) are official US NWS active warnings.
#Missing values and condition codes
Required fields (such as temperature, coordinates, or observation timestamp) missing from an upstream response fail normalization and trigger fallback. Optional fields remain absent rather than defaulting to fake zeros (while preserving genuine 0°C or 0% readings). Unmapped mixed hazards (such as sleet) preserve original source condition codes rather than guessing a benign label.
docs/openapi.yaml (lean_v1) and docs/openapi.experimental.yaml · Verify against your build before production use.