Common Objects

Reference·Audience: API consumer·Use: look up the structure and constraints of an envelope or a primitive type

These definitions are shared by many messages. Field meanings in context are on the operation pages; how to use the envelopes is on Message Envelopes and Correlation and Correlation and Request/Response Pairing.

Envelopes

Each command, response, and event message combines one of these member sets with its own members. The contract repeats them in every message rather than referencing a shared definition.

commandEnvelopeBase

The members every command carries.

Field	Type	Required	Default	Limits	Meaning
command	commandName	Yes			The command to run
requestId	string	Yes			Your correlation identifier, echoed in the reply

responseEnvelopeBase

The members every command response carries. The delete_wifi_profile response does not declare apiVersion.

Field	Type	Required	Default	Limits	Meaning
command	commandName	Yes			The command being answered
requestId	string	Yes			The requestId of the request being answered
apiVersion	apiVersion	Yes			Version reported by the command handler
response	object (responseStatus)	Yes			The outcome of the command. The set_os response does not require it.

responseStatus

The response object in every command response.

Field	Type	Required	Default	Limits	Meaning
code	integer (statusCode)	Yes		0–101	Numeric outcome
description	string	Yes			Human-readable text. Don't parse it.

The contract requires code. Readers have been reported to omit it on a successful reply, sending { "description": "Success" }; treat that as success. See Success Without a Code.

eventEnvelopeBase

The member that heartBeatEVT, alerts, and dataEVT share. mqttConnEVT does not require it, because its DISCONNECTED form carries no timestamp.

Field	Type	Required	Default	Limits	Meaning
timestamp	string	Yes		format date-time	When the reader generated the event

Primitive Types

The contract declares these members as plain strings and integers. It has no named primitive types and no patterns; the only limits are the ones below.

Member	JSON type	Limits in the contract	Notes
requestId	string	None	Chosen by your application. Treat it as opaque.
timestamp	string	format: date-time, an annotation that Draft 07 does not enforce	Every value in the contract's examples is UTC with a Z suffix and millisecond precision.
tenantId	string	48 characters, stated in its description	An overlong value returns code 27.
url	string	None	Broker host name or IP address
port	integer	None	TCP port
keepAlive	integer	Maximum 65535	Seconds
topic	string	None	Don't use + or # in a publish topic.
clientId	string	None	See Client ID.
chargePercentage	integer	Maximum 100	Percentage

The serial number that the reader appends to every topic is not a payload member. It is the model-prefixed serial, for example RFD40-212735201D0053; see Serial Number Forms.

Related: 📕 Message Envelopes and Correlation · 📕 MQTT Endpoints · 📕 Enumerations