This article describes the JSON format of device shadows.

The following code snippet shows the sample JSON file of a device shadow:

{
    "state": {
        "desired": {
            "color": "RED", 
            "sequence": [
                "RED", 
                "GREEN", 
                "BLUE"
            ]
        }, 
        "reported": {
            "color": "GREEN"
        }
    }, 
    "metadata": {
        "desired": {
            "color": {
                "timestamp": 1469564492
            }, 
            "sequence": {
                "timestamp": 1469564492
            }
        }, 
        "reported": {
            "color": {
                "timestamp": 1469564492
            }
        }
    }, 
    "timestamp": 1469564492, 
    "version": 1
}

The Table 1 table describes the properties in the sample JSON file.

Table 1. JSON file properties
Property Description
desired The desired status of the device. The JSON file of a device shadow contains the desired property only when you have specified the desired status.

An application can directly write the desired property of the device without the need to connect to the device.

reported The status that is reported by the device. The device can write the reported property to report its latest status.

An application can obtain the status of the device by reading this property.

The JSON file of a device shadow may not contain the reported property and is still valid.

metadata The metadata information about the device status, which is automatically updated based on updates in the JSON file.

The metadata information contains the timestamp of each property to provide accurate update time. Each timestamp is the number of seconds that have elapsed since January 1, 1970, 00:00:00 UTC.

timestamp The latest time when the JSON file is updated.
version The version number of the JSON file. When you request a version update of the device shadow, the device shadow checks whether the requested version is later than the current version.

If the requested version is later than the current version, the device shadow is updated and the version property is also updated. Otherwise, the device shadow rejects the request.

During updates, the value of the version property increments, which ensures that the file being updated is always the latest version.

The version property is of the LONG type. To prevent a parameter overflow, you can enter -1 to reset the version number to 0.

Note

Arrays are supported in the JSON files of device shadows. When you update an array, you must update the whole array instead of only a part of the array.

The following example shows how to update an array:

  • Initial status: 
    
{
"reported" : { "colors" : ["RED", "GREEN", "BLUE" ] }
}
  • Update: 
    
{
"reported" : { "colors" : ["RED"] }
}
  • Final status: 
    
{
"reported" : { "colors" : ["RED"] }
}