A JSON payload schema for SCADA telemetry is the agreed shape of the little message that carries one field reading up to the cloud. It defines which fields a reading always includes, what they are called, and how they are typed, so that whatever produces the message and whatever consumes it agree without guesswork. Get the envelope right and the same messages flow cleanly into dashboards, warehouses, and alerting for years. Get it wrong and every downstream parser becomes brittle. This page covers the core value, quality, and timestamp fields, the flat versus nested trade-off, schema versioning, and how to attach units and other metadata.
JSON payload schema for telemetry in one line: A JSON payload schema for SCADA telemetry is the defined structure of a telemetry message, specifying fields such as the tag identifier, its value, a quality indicator, and a timestamp, along with their names and types. A good schema is stable, explicitly versioned, and carries units and metadata, so producers and consumers stay compatible as the system grows.
Every SCADA reading is really three things bundled together, and a good JSON envelope makes all three explicit. The value is the measurement itself, a level, a pressure, a run state. The timestamp says when that value was true at the source, which is not the same as when the message was sent or received, and it should be an unambiguous, time-zone-aware format such as an ISO 8601 UTC string so no consumer has to guess the offset. The quality flag records whether the source considered the reading trustworthy, good, bad, or uncertain, because a value with bad quality is worse than useless if a consumer treats it as real.
This value-quality-timestamp trio is the industrial equivalent of a complete fact. A dashboard that plots values but ignores quality will happily draw a flat line through a sensor that was actually disconnected, and an alert that trusts a stale timestamp may fire on hours-old data. Carrying all three in the envelope lets each consumer decide correctly: hold the last good value, gray out a bad one, or suppress an alert on uncertain data. Leaving any of the three out forces consumers to invent assumptions, and different consumers invent different ones.
Alongside these, the message needs a stable tag identifier so the reading can be tied to the right point in the right asset. This should be a durable key that does not change when a display name is edited, ideally a path or code that encodes site and asset. Timestamps should be sent at consistent precision, and values should keep their natural type, a number as a number and a boolean as a boolean, rather than being flattened to strings, so consumers do not have to parse and re-type every field.
The same information can be arranged as a flat object with all fields at the top level, or as a nested structure that groups related fields under sub-objects. A flat layout, where tag, value, quality, timestamp, and units all sit side by side as top-level keys, is the friendliest for loading straight into a warehouse or a columnar store, because each key maps cleanly to a column with no unpacking. Flat messages are also the easiest for a quick eyeball read and for simple stream processors that do not want to walk a tree.
Nested layouts earn their keep when a message carries more than one reading or a richer context. Putting an array of metric objects under a shared header, so one message reports several tags from the same device at the same instant with the site and device identified once, cuts repetition and keeps related readings together. Nesting also cleanly separates envelope metadata, schema version, source, and timestamp, from the payload of readings, which can make routing and validation simpler. The cost is that consumers must unpack the structure, and warehouse loading needs a flattening step.
A common middle path is a light two-level shape: a small header identifying the source and schema version, and a flat array of readings each carrying its own value, quality, timestamp, and units. This keeps per-reading fields flat enough to flatten easily while avoiding repeating the source on every single row. Whichever way you lean, the important thing is to pick one shape and hold it, because consumers write parsers against the structure they first see, and quietly switching between flat and nested layouts is exactly the kind of change that breaks them.
Schemas change, and the way to change them without breaking everyone downstream is to version the envelope explicitly. A version field in every message, or at least in the header, tells consumers which shape to expect and lets a parser handle old and new formats side by side during a transition. The safest changes are additive: adding a new optional field does not disturb a consumer that ignores it, so bumping the version and adding fields, rather than renaming or repurposing existing ones, keeps old readers working. Renaming or retyping a field is a breaking change and needs a coordinated version step.
Units are the metadata people most often forget and most regret forgetting. A value of 42 means nothing until you know whether it is feet, meters, PSI, or a percentage, and burying the unit in a tag name or a separate lookup that not every consumer has is a recipe for a unit-mismatch incident. Carrying the unit in the message, next to the value, makes each reading self-describing, so a consumer can convert, label an axis, or reject an unexpected unit without external context. The same logic applies to other descriptive metadata like a data type hint or an engineering range.
For a cloud SCADA platform such as Merobix ingesting telemetry from many different field devices and gateways, a well-designed, versioned JSON envelope is what keeps that variety manageable. When every reading arrives self-describing, with value, quality, timestamp, units, and a schema version, the platform can validate, route, and store it consistently, add new field types without a flag-day migration, and load it into analytics without a bespoke parser per source. The small discipline of designing the envelope up front pays off as the fleet of sources grows and evolves.
At minimum it needs a stable tag identifier, the value, a quality indicator, and a source timestamp in an unambiguous time-zone-aware format. Together these describe a complete reading: what point, what value, whether it can be trusted, and when it was true. Carrying units and a schema version alongside makes each message self-describing and future-proof.
A flat layout loads most easily into warehouses and columnar stores because each field maps to a column, while a nested layout is efficient when one message reports several readings from the same device. A common compromise is a small header plus a flat array of readings. The critical thing is to choose one shape and keep it stable, since consumers write parsers against the structure they first receive.
Include a version field in every message and prefer additive changes, since adding an optional field does not disturb consumers that ignore it. Renaming or retyping an existing field is a breaking change and requires bumping the version and coordinating consumers through a transition. Keeping old and new versions readable side by side lets producers and consumers migrate at their own pace.
Merobix reads your field devices into a cloud SCADA - the real thing behind these terms, live in days from any browser.