Shadow document syntax - AWS IoT

Shadow document syntax

The Device Shadow service uses the following documents in UPDATE, GET, and DELETE operations using the RESTful API or MQTT Pub/Sub Messages. For more information, see Device shadow service documents.

Request state documents

Request state documents have the following format:

{ "state": { "desired": { "attribute1": integer2, "attribute2": "string2", ... "attributeN": boolean2 }, "reported": { "attribute1": integer1, "attribute2": "string1", ... "attributeN": boolean1 } }, "clientToken": "token", "version": version }
  • state — Updates affect only the fields specified. Typically, you'll use either the desired or the reported property, but not both in the same request.

    • desired — The state properties and values requested to be updated in the device.

    • reported — The state properties and values reported by the device.

  • clientToken — If used, you can match the request and corresponding response by the client token.

  • version — If used, the Device Shadow service processes the update only if the specified version matches the latest version it has.

Response state documents

Response state documents have the following format depending on the response type.

/accepted response state document

{ "state": { "desired": { "attribute1": integer2, "attribute2": "string2", ... "attributeN": boolean2 } }, "metadata": { "desired": { "attribute1": { "timestamp": timestamp }, "attribute2": { "timestamp": timestamp }, ... "attributeN": { "timestamp": timestamp } } }, "timestamp": timestamp, "clientToken": "token", "version": version }

/delta response state document

{ "state": { "attribute1": integer2, "attribute2": "string2", ... "attributeN": boolean2 } }, "metadata": { "attribute1": { "timestamp": timestamp }, "attribute2": { "timestamp": timestamp }, ... "attributeN": { "timestamp": timestamp } }, "timestamp": timestamp, "clientToken": "token", "version": version }

/documents response state document

{ "previous" : { "state": { "desired": { "attribute1": integer2, "attribute2": "string2", ... "attributeN": boolean2 }, "reported": { "attribute1": integer1, "attribute2": "string1", ... "attributeN": boolean1 } }, "metadata": { "desired": { "attribute1": { "timestamp": timestamp }, "attribute2": { "timestamp": timestamp }, ... "attributeN": { "timestamp": timestamp } }, "reported": { "attribute1": { "timestamp": timestamp }, "attribute2": { "timestamp": timestamp }, ... "attributeN": { "timestamp": timestamp } } }, "version": version-1 }, "current": { "state": { "desired": { "attribute1": integer2, "attribute2": "string2", ... "attributeN": boolean2 }, "reported": { "attribute1": integer2, "attribute2": "string2", ... "attributeN": boolean2 } }, "metadata": { "desired": { "attribute1": { "timestamp": timestamp }, "attribute2": { "timestamp": timestamp }, ... "attributeN": { "timestamp": timestamp } }, "reported": { "attribute1": { "timestamp": timestamp }, "attribute2": { "timestamp": timestamp }, ... "attributeN": { "timestamp": timestamp } } }, "version": version }, "timestamp": timestamp, "clientToken": "token" }

Response state document properties

  • previous — After a successful update, contains the state of the object before the update.

  • current — After a successful update, contains the state of the object after the update.

  • state

    • reported — Only present if a thing reported any data in the reported section and contains only fields that were in the request state document.

    • desired — Only present if a thing reported any data in the desired section and contains only fields that were in the request state document.

    • delta — Only present if the desired data differs from the shadow's current reported data.

  • metadata — Contains the timestamps for each attribute in the desired and reported sections so that you can determine when the state was updated.

  • timestamp — The Epoch date and time the response was generated by AWS IoT.

  • clientToken — Present only if a client token was used when publishing valid JSON to the /update topic.

  • version — The current version of the document for the device's shadow shared in AWS IoT. It is increased by one over the previous version of the document.

Error response documents

Error response documents have the following format:

{ "code": error-code, "message": "error-message", "timestamp": timestamp, "clientToken": "token" }
  • code — An HTTP response code that indicates the type of error.

  • message — A text message that provides additional information.

  • timestamp — The date and time the response was generated by AWS IoT. This property is not present in all error response documents.

  • clientToken — Present only if a client token was used when publishing valid JSON to the /update topic.

For more information, see Shadow error messages.