# Package `model`

## Import Path

```go
import "gitea.maximumdirect.net/ejr/weatherfeeder/model"
```

## Purpose

Package `model` defines `weatherfeeder`'s canonical weather payload structs.
These structs are emitted as the `payload` of canonical `weather.*` events and
are also the domain types consumed by downstream applications such as
`weatherapi`.

The JSON field tags on these structs are part of the wire contract. For the full
field-by-field JSON contract, use the [event wire contract](../integrations/events.md).

## Payload Types

Current canonical schema families map to these public types:

| Schema | Primary type |
|---|---|
| `weather.observation.v1` | `WeatherObservation` |
| `weather.forecast.v1` | `WeatherForecastRun` |
| `weather.forecast_discussion.v1` | `WeatherForecastDiscussion` |
| `weather.weather_story.v1` | `WeatherStoryRun` |
| `weather.alert.v1` | `WeatherAlertRun` |
| `weather.outlook.v2` | `WeatherOutlookRun` |

Related child types include:

- `WeatherObservationPresentWeather`
- `WeatherForecastPeriod`
- `WeatherForecastDiscussionSection`
- `WeatherStory`
- `WeatherAlert`
- `WeatherAlertReference`
- `WeatherOutlook`
- `WeatherOutlookDiscussion`
- `WMOCode`

`WeatherOutlookRun` includes `WeatherOutlookDiscussion` entries as run-level
SPC day discussions.

## Wire And Compatibility Rules

- JSON tags define canonical payload field names.
- Pointer fields and fields tagged `omitempty` are optional on the wire.
- Missing optional fields mean unknown or not applicable.
- Canonical measurements use metric units.
- Canonical timestamps are `time.Time` values encoded by Go's JSON encoder.
- Normalized canonical timestamps are UTC unless a field-specific contract says
  otherwise.
- Additive fields are compatible within a schema version.
- Removing, renaming, or changing the meaning of a field requires a new schema
  identifier.

## Boundaries

`model` should not depend on source adapters, sinks, SQL column names, provider
HTTP shapes, or runtime configuration.

Consumers should not rely on packages under `internal/...`. Use `model` with
schema constants from [`standards`](pkg-standards.md) and the JSON contract in
[`docs/integrations/events.md`](../integrations/events.md).