Menu
AWS IoT
Developer Guide

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.

  • clientToken — If used, you can verify that the request and response contain the same 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:

{ "state": { "desired": { "attribute1": integer2, "attribute2": "string2", ... "attributeN": boolean2 }, "reported": { "attribute1": integer1, "attribute2": "string1", ... "attributeN": boolean1 }, "delta": { "attribute3": integerX, "attribute5": "stringY" } }, "metadata": { "desired": { "attribute1": { "timestamp": timestamp }, "attribute2": { "timestamp": timestamp }, ... "attributeN": { "timestamp": timestamp } }, "reported": { "attribute1": { "timestamp": timestamp }, "attribute2": { "timestamp": timestamp }, ... "attributeN": { "timestamp": timestamp } } }, "timestamp": timestamp, "clientToken": "token", "version": version }
  • 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.

  • 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.

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

For more information, see Shadow Error Messages.