Added a SCHEMA.md with espress documentation of the JSON output schemas emitted by weatherfeeder.
All checks were successful
ci/woodpecker/push/build-image Pipeline was successful
All checks were successful
ci/woodpecker/push/build-image Pipeline was successful
This commit is contained in:
166
SCHEMA.md
Normal file
166
SCHEMA.md
Normal file
@@ -0,0 +1,166 @@
|
|||||||
|
# weatherfeeder Canonical Schemas
|
||||||
|
|
||||||
|
This document expressly defines the JSON payload schemas emitted by weatherfeeder for:
|
||||||
|
|
||||||
|
- `weather.observation.v1`
|
||||||
|
- `weather.forecast.v1`
|
||||||
|
- `weather.alert.v1`
|
||||||
|
|
||||||
|
These schemas are defined by the `internal/model` structs and their JSON tags.
|
||||||
|
|
||||||
|
## Shared Conventions
|
||||||
|
|
||||||
|
- Timestamps are JSON strings in RFC3339Nano format.
|
||||||
|
- Optional fields are omitted when unknown (`omitempty` behavior).
|
||||||
|
- Numeric measurements are normalized to metric units:
|
||||||
|
- `*C` = Celsius
|
||||||
|
- `*Kmh` = kilometers/hour
|
||||||
|
- `*Pa` = Pascals
|
||||||
|
- `*Meters` = meters
|
||||||
|
- `*Mm` = millimeters
|
||||||
|
- `*Percent` = percent (0-100)
|
||||||
|
- `conditionCode` is a WMO weather interpretation code (`int`).
|
||||||
|
- Unknown/unmappable is `-1`.
|
||||||
|
|
||||||
|
## `weather.observation.v1`
|
||||||
|
|
||||||
|
Payload type: `model.WeatherObservation`
|
||||||
|
|
||||||
|
| Field | Type | Required | Notes |
|
||||||
|
|---|---:|:---:|---|
|
||||||
|
| `stationId` | string | no | Provider station/location identifier |
|
||||||
|
| `stationName` | string | no | Human station name |
|
||||||
|
| `timestamp` | timestamp string | yes | Observation timestamp |
|
||||||
|
| `conditionCode` | int | yes | WMO code (`-1` unknown) |
|
||||||
|
| `conditionText` | string | no | Canonical short condition text |
|
||||||
|
| `isDay` | bool | no | Day/night hint |
|
||||||
|
| `providerRawDescription` | string | no | Provider-specific evidence text |
|
||||||
|
| `textDescription` | string | no | Legacy/transitional text description |
|
||||||
|
| `iconUrl` | string | no | Legacy/transitional icon URL |
|
||||||
|
| `temperatureC` | number | no | Celsius |
|
||||||
|
| `dewpointC` | number | no | Celsius |
|
||||||
|
| `windDirectionDegrees` | number | no | Degrees |
|
||||||
|
| `windSpeedKmh` | number | no | km/h |
|
||||||
|
| `windGustKmh` | number | no | km/h |
|
||||||
|
| `barometricPressurePa` | number | no | Pascals |
|
||||||
|
| `seaLevelPressurePa` | number | no | Pascals |
|
||||||
|
| `visibilityMeters` | number | no | Meters |
|
||||||
|
| `relativeHumidityPercent` | number | no | Percent |
|
||||||
|
| `apparentTemperatureC` | number | no | Celsius |
|
||||||
|
| `elevationMeters` | number | no | Meters |
|
||||||
|
| `rawMessage` | string | no | Provider raw message (for example METAR) |
|
||||||
|
| `presentWeather` | array | no | Provider-specific structured weather fragments |
|
||||||
|
| `cloudLayers` | array | no | Cloud layer details |
|
||||||
|
|
||||||
|
### `cloudLayers[]` (`model.CloudLayer`)
|
||||||
|
|
||||||
|
| Field | Type | Required | Notes |
|
||||||
|
|---|---:|:---:|---|
|
||||||
|
| `baseMeters` | number | no | Cloud base altitude in meters |
|
||||||
|
| `amount` | string | no | Provider amount code/text |
|
||||||
|
|
||||||
|
### `presentWeather[]` (`model.PresentWeather`)
|
||||||
|
|
||||||
|
| Field | Type | Required | Notes |
|
||||||
|
|---|---:|:---:|---|
|
||||||
|
| `raw` | object | no | Provider-specific object |
|
||||||
|
|
||||||
|
## `weather.forecast.v1`
|
||||||
|
|
||||||
|
Payload type: `model.WeatherForecastRun`
|
||||||
|
|
||||||
|
`product` values are:
|
||||||
|
|
||||||
|
- `"hourly"`
|
||||||
|
- `"narrative"`
|
||||||
|
- `"daily"`
|
||||||
|
|
||||||
|
| Field | Type | Required | Notes |
|
||||||
|
|---|---:|:---:|---|
|
||||||
|
| `locationId` | string | no | Provider location identifier |
|
||||||
|
| `locationName` | string | no | Human location name |
|
||||||
|
| `issuedAt` | timestamp string | yes | Forecast run issue/generated time |
|
||||||
|
| `updatedAt` | timestamp string | no | Optional later update time |
|
||||||
|
| `product` | string | yes | One of `hourly`, `narrative`, `daily` |
|
||||||
|
| `latitude` | number | no | Degrees |
|
||||||
|
| `longitude` | number | no | Degrees |
|
||||||
|
| `elevationMeters` | number | no | Meters |
|
||||||
|
| `periods` | array | yes | Forecast periods, intended chronological order |
|
||||||
|
|
||||||
|
### `periods[]` (`model.WeatherForecastPeriod`)
|
||||||
|
|
||||||
|
| Field | Type | Required | Notes |
|
||||||
|
|---|---:|:---:|---|
|
||||||
|
| `startTime` | timestamp string | yes | Start of validity window |
|
||||||
|
| `endTime` | timestamp string | yes | End of validity window |
|
||||||
|
| `name` | string | no | Human label (for example "Tonight") |
|
||||||
|
| `isDay` | bool | no | Day/night hint |
|
||||||
|
| `conditionCode` | int | yes | WMO code (`-1` unknown) |
|
||||||
|
| `conditionText` | string | no | Canonical short condition text |
|
||||||
|
| `providerRawDescription` | string | no | Provider-specific evidence text |
|
||||||
|
| `textDescription` | string | no | Short narrative text |
|
||||||
|
| `detailedText` | string | no | Longer narrative text |
|
||||||
|
| `iconUrl` | string | no | Legacy/transitional icon URL |
|
||||||
|
| `temperatureC` | number | no | Celsius |
|
||||||
|
| `temperatureCMin` | number | no | Celsius (aggregated periods) |
|
||||||
|
| `temperatureCMax` | number | no | Celsius (aggregated periods) |
|
||||||
|
| `dewpointC` | number | no | Celsius |
|
||||||
|
| `relativeHumidityPercent` | number | no | Percent |
|
||||||
|
| `windDirectionDegrees` | number | no | Degrees |
|
||||||
|
| `windSpeedKmh` | number | no | km/h |
|
||||||
|
| `windGustKmh` | number | no | km/h |
|
||||||
|
| `barometricPressurePa` | number | no | Pascals |
|
||||||
|
| `visibilityMeters` | number | no | Meters |
|
||||||
|
| `apparentTemperatureC` | number | no | Celsius |
|
||||||
|
| `cloudCoverPercent` | number | no | Percent |
|
||||||
|
| `probabilityOfPrecipitationPercent` | number | no | Percent |
|
||||||
|
| `precipitationAmountMm` | number | no | Liquid-equivalent millimeters |
|
||||||
|
| `snowfallDepthMm` | number | no | Millimeters |
|
||||||
|
| `uvIndex` | number | no | Unitless UV index |
|
||||||
|
|
||||||
|
## `weather.alert.v1`
|
||||||
|
|
||||||
|
Payload type: `model.WeatherAlertRun`
|
||||||
|
|
||||||
|
| Field | Type | Required | Notes |
|
||||||
|
|---|---:|:---:|---|
|
||||||
|
| `locationId` | string | no | Provider location identifier |
|
||||||
|
| `locationName` | string | no | Human location name |
|
||||||
|
| `asOf` | timestamp string | yes | Snapshot timestamp |
|
||||||
|
| `latitude` | number | no | Degrees |
|
||||||
|
| `longitude` | number | no | Degrees |
|
||||||
|
| `alerts` | array | yes | Active alerts in the snapshot |
|
||||||
|
|
||||||
|
### `alerts[]` (`model.WeatherAlert`)
|
||||||
|
|
||||||
|
| Field | Type | Required | Notes |
|
||||||
|
|---|---:|:---:|---|
|
||||||
|
| `id` | string | yes | Provider-stable ID, often URL/URI |
|
||||||
|
| `event` | string | no | Classification/event label |
|
||||||
|
| `headline` | string | no | Alert headline |
|
||||||
|
| `severity` | string | no | Example: Extreme/Severe/Moderate/Minor/Unknown |
|
||||||
|
| `urgency` | string | no | Example: Immediate/Expected/Future/Past/Unknown |
|
||||||
|
| `certainty` | string | no | Example: Observed/Likely/Possible/Unlikely/Unknown |
|
||||||
|
| `status` | string | no | Example: Actual/Exercise/Test/System/Unknown |
|
||||||
|
| `messageType` | string | no | Example: Alert/Update/Cancel |
|
||||||
|
| `category` | string | no | Example: Met/Geo/Safety/Rescue/Fire/Health/Env/Transport/Infra/CBRNE/Other |
|
||||||
|
| `response` | string | no | Example: Shelter/Evacuate/Prepare/Execute/Avoid/Monitor/Assess/AllClear/None |
|
||||||
|
| `description` | string | no | Narrative description |
|
||||||
|
| `instruction` | string | no | Recommended actions |
|
||||||
|
| `sent` | timestamp string | no | Provider-dependent |
|
||||||
|
| `effective` | timestamp string | no | Provider-dependent |
|
||||||
|
| `onset` | timestamp string | no | Provider-dependent |
|
||||||
|
| `expires` | timestamp string | no | Provider-dependent |
|
||||||
|
| `areaDescription` | string | no | Provider area text |
|
||||||
|
| `senderName` | string | no | Alert sender/source name |
|
||||||
|
| `references` | array | no | Related alerts |
|
||||||
|
|
||||||
|
### `references[]` (`model.AlertReference`)
|
||||||
|
|
||||||
|
| Field | Type | Required | Notes |
|
||||||
|
|---|---:|:---:|---|
|
||||||
|
| `id` | string | no | Related alert ID/URI |
|
||||||
|
| `identifier` | string | no | Provider identifier when distinct |
|
||||||
|
| `sender` | string | no | Sender |
|
||||||
|
| `sent` | timestamp string | no | Timestamp |
|
||||||
|
|
||||||
Reference in New Issue
Block a user