3.0 KiB
Weather Data Internals
internal/weatherdata owns the normalized, wire-independent weather bundle
that passes from collection through rendering. The Weather API
adapter translates provider responses into these types; its request, response,
and availability contract is documented in the
Weather API integration guide.
Bundle contract
Bundle has a collection timestamp (FetchedAt), source provenance
(Sources), and collection-level warnings (Warnings). Its product fields are
optional so an allowed missing source can be represented without manufacturing
weather data.
| Field | Normalized product |
|---|---|
Observation |
Station observation |
Current |
Current conditions |
Hourly |
Hourly forecast periods |
Narrative |
Narrative forecast |
Alerts |
Active-alert check, including an explicitly empty result |
Discussion |
Forecast discussion and its time-range sections |
Daily |
Daily forecast periods when supplied |
WeatherStory |
Latest weather story |
SPCConvectiveOutlooks |
Convective outlook run, discussions, and GeoJSON geometry |
The bundle carries values rather than provider request details. Consumers use it to construct report facts and data packages; they should not infer a provider endpoint or retry policy from the normalized types. See collection for assembly and report templates for the values exposed to authors.
Source provenance
Every checked source is represented by a Source entry. The record identifies
the source (Name), request location and query (Endpoint, Query), fetch
time, provider issue and update times when available, a SHA-256 digest of the
source data, and whether the source was unavailable (Missing). Its warnings
stay with that source in addition to the bundle-level warning list.
An empty product can be meaningful checked data. For example, an explicit empty alerts result is not missing and retains its source hash. A source is marked missing only when the adapter's missing-source policy treats the response or parsing failure as unavailable. The policy itself belongs to the configuration reference.
Warning semantics
SourceWarning has a source name, stable code, severity, explanatory message,
endpoint, and CompletenessImpact. When collection proceeds with a warning,
the same warning appears in Source.Warnings and Bundle.Warnings so both
local provenance and whole-run consumers see it. A policy that treats a missing
source as an error returns no partial bundle.
Warnings describe data completeness, not rendering or delivery failures. Those failures are reported by application orchestration.
Boundaries and verification
This package defines data shapes and has no HTTP client, configuration loader, filesystem access, or template behavior. Focused tests cover the normalized types and the Weather API adapter verifies translation into them:
go test ./internal/weatherdata
go test ./internal/adapters/weatherapi