The whole schema, in one place.

01The two messages.

oat-ods has exactly two message types, and a receiver tells them apart by msg_type. The first carries a reading. It holds one measurement — value, what it measured, when, the place, and the gadget:

{
  "schema": "oat-ods/0.3",
  "msg_type": "observation",              // default; may be omitted
  "observed_at": "2026-06-25T14:30:00Z",
  "stream": {
    "id": "gh2-north-air",                // the place — the primary key
    "name": "GH2 North Bench Air",
    "location": "Greenhouse 2 / North Bench"
  },
  "measurement": "temperature",
  "value": 24.31,
  "unit": "Cel",
  "agg": { "window_s": 60, "samples": 28, "method": "mean" },
  "source": {
    "tier": "oat-ble-listener",
    "gateway_id": "oat-greenhouse-2",     // assignable node id, not the MAC
    "physical_id": "AA:BB:CC:DD:EE:01",   // the gadget, swap it any time
    "brand": "Govee", "model": "H5075",
    "battery_pct": 88, "rssi": -78
  }
}

The second is a status message: how a node says it is alive without any reading riding along (§04). Same envelope, no stream/measurement/value:

{
  "schema": "oat-ods/0.3",
  "msg_type": "status",
  "state": "online",                      // "online" | "offline"
  "observed_at": "2026-06-25T14:30:00Z",
  "source": { "tier": "oat-ble-listener", "gateway_id": "oat-greenhouse-2",
              "device_id": "oat-3c8a1fa77d14" },  // the physical board (efuse MAC)
  "health": { "uptime_s": 86400, "boot_count": 3, "reset": "poweron",
              "free_heap": 142000, "rssi": -71, "push_ok": 1440, "push_fail": 2,
              "transport": "https", "tls_ok": true, "chip": "ESP32-C6" }
}

02Every field.

The complete field set. A consumer must ignore fields it doesn't recognize — that rule is what lets the format grow without breaking anything downstream.

“obs.” = required on an observation; “status” = required on a status message; “one of” = source needs at least one of gateway_id / physical_id.

03The full vocabulary.

This is the part a single sketch never shows you: every measurement the schema knows, 28 of them, each bound to the open standards it profiles — the SenML unit, the Home Assistant device class, the QUDT quantity kind, and the UCUM code. We chose these names; we did not invent them. The table is generated from measurands.json, so it is always exactly what the devices emit.

Open by construction. measurement is not a closed list. A device may send a measurement that isn't here yet; the schema asks only for a non-empty string, and a key the dictionary hasn't mapped is forwarded raw (its own name, no unit) rather than dropped — so nothing is ever lost, and new keys surface for adding to the table. source: derived rows (dewpoint, VPD) are computed by the endpoint, never sent by a node.

04Knowing a node is alive.

A node reports liveness with a status message, borrowing the idea from Eclipse Sparkplug. Over a webhook it POSTs state:"online" on boot and on a heartbeat; over MQTT it sets a Last Will of state:"offline" so the broker announces a drop automatically.

The heartbeat interval is a fixed constant of the format: 60 seconds, written here and not carried in the payload — because a packet that never arrives can't declare its own cadence. For an endpoint to detect absence it must know the expected beat in advance. Treat > 3× the cadence (180 s) with no heartbeat as a liveness alarm, not a single missed beat. Monitoring is always the endpoint's job; the node just reports.

A status message may carry a health object — the node's honest self-report:

05The shared device library.

Every Open Agriculture Technology sketch — the BLE listener, the SDI-12 reader, the analog and Modbus readers — links one shared library, oat_ods, to build these messages. It is header-only (ArduinoJson 7), carries no transport of its own (your sketch owns the HTTP or MQTT send), and holds the native / SenML / flat / status encoders plus the Home Assistant discovery helpers. Write a new device and it pours into the same envelope: only the transducer differs. That is one envelope, every sketch.

You get the library two ways, so a sketch always compiles as-is:

• Inside every sketch. Each download from the Software Library bundles lib/oat_ods/ alongside the project, and its platformio.ini already points at it (lib_extra_dirs = ../lib). Unzip, build, flash — nothing else to fetch.
• On its own, here. Grab the library by itself to drop into your own project's lib/ folder, or just to read the source.

06How it travels.

The identical message reaches an endpoint two ways, and a device offers whichever suits your setup — the receiver can’t tell them apart. Pick by what you already run:

The MQTT binding is worth spelling out. The topic is keyed on the place, not the hardware, so it survives a sensor swap; each value is published retained, so a new subscriber always gets the latest reading immediately; and node liveness rides its own topic with a Last Will the broker publishes on a dropped connection:

# one retained message per stream + measurement
oat/{gateway_id}/{stream.id}/{measurement}

# example
oat/oat-greenhouse-2/gh2-north-air/temperature   → 24.31

# node liveness — Last Will publishes "offline" automatically on a dropped connection
oat/{gateway_id}/status                            → {"state":"online"}

Running Home Assistant? A node can announce itself with MQTT discovery instead, so its readings show up as entities with no hand-configuration — the oat_ods library builds those discovery configs for you. Either way the payload is the same oat-ods message, and there’s a runnable subscriber for it in the next section.

07A receiver you can run.

The other end is just as simple, and there’s a runnable reference for both transports (§06). Copy one, set a couple of environment variables, and start it.

Webhook. Drop-in HTTP endpoints that accept oat-ods over a POST: set one secret and run. Both handle single messages and batches, verify an optional oat1 HMAC signature over the raw body (so the key is never sent, safe even over plain HTTP), and reject replays by sequence number.

MQTT. Subscribers that connect to your broker and print every reading as it lands. Retained messages arrive the moment they subscribe, so a fresh start immediately shows the latest value for every stream, and the status topic is read as liveness. Auth is the broker’s job (username / password + TLS), not a per-message signature.

Want to watch messages land without writing anything? Point a device (or curl) at the live test endpoint and see each reading arrive, judged against the schema.

08Conformance & versioning.

A message is oat-ods/0.3 conformant when an observation carries schema, observed_at, stream.id, measurement, value, and a source with at least one of gateway_id / physical_id; any unit is a SenML symbol; and each message holds exactly one measurement. Validate against the JSON Schema with any standard validator.

The version lives in the schema tag, oat-ods/{major}.{minor}. New optional fields or new measurements bump the minor; a breaking change bumps the major. Because consumers ignore unknown fields, minor growth never breaks a receiver already in the field. The highest-leverage promise is that the format is trivially consumable: fetch the schema, validate, generate a receiver in minutes — the bet is on the source being clean, not on any one destination persisting.

09Every artifact.

Everything we publish for oat-ods, in one place: