Merge pull request #101837 from JimacoMS3/fix-gh-45003-device-twin-object-limitations

clarify tags and reported/desired properties size limits per gh 45003

Author: PRMerger17

articles/iot-hub/iot-hub-devguide-device-twins.md

@@ -7,7 +7,7 @@ ms.author: wesmc
 ms.service: iot-hub
 services: iot-hub
 ms.topic: conceptual
-ms.date: 06/10/2019
+ms.date: 02/01/2020
 ---
 
 # Understand and use device twins in IoT Hub
@@ -240,11 +240,15 @@ The [Azure IoT device SDKs](iot-hub-devguide-sdks.md) make it easy to use the pr
 
 Tags, desired properties, and reported properties are JSON objects with the following restrictions:
 
-* All keys in JSON objects are UTF-8 encoded, case-sensitive, and up-to 1 KB in length. Allowed characters exclude UNICODE control characters (segments C0 and C1), and `.`, `$`, and SP.
+* **Keys**: All keys in JSON objects are UTF-8 encoded, case-sensitive, and up-to 1 KB in length. Allowed characters exclude UNICODE control characters (segments C0 and C1), and `.`, `$`, and SP.
 
-* All values in JSON objects can be of the following JSON types: boolean, number, string, object. Arrays are not allowed. The maximum value for integers is 4503599627370495 and the minimum value for integers is -4503599627370496.
+* **Values**: All values in JSON objects can be of the following JSON types: boolean, number, string, object. Arrays are not allowed.
 
-* All JSON objects in tags, desired, and reported properties can have a maximum depth of 10. For instance, the following object is valid:
+    * Integers can have a minimum value of -4503599627370496 and a maximum value of 4503599627370495.
+
+    * String values are UTF-8 encoded and can have a maximum length of 4 KB.
+
+* **Depth**: The maximum depth of JSON objects in tags, desired properties, and reported properties is 10. For example, the following object is valid:
 
    ```json
    {
@@ -276,15 +280,23 @@ Tags, desired properties, and reported properties are JSON objects with the foll
    }
    ```
 
-* All string values can be at most 4 KB in length.
-
 ## Device twin size
 
-IoT Hub enforces an 8 KB size limit on the value of `tags`, and a 32 KB size limit each on the value of `properties/desired` and `properties/reported`. These totals are exclusive of read-only elements.
+IoT Hub enforces an 8 KB size limit on the value of `tags`, and a 32 KB size limit each on the value of `properties/desired` and `properties/reported`. These totals are exclusive of read-only elements like `$etag`, `$version`, and `$metadata/$lastUpdated`.
+
+Twin size is computed as follows:
+
+* For each property in the JSON document, IoT Hub cumulatively computes and adds the length of the property's key and value.
+
+* Property keys are considered as UTF8-encoded strings.
+
+* Simple property values are considered as UTF8-encoded strings, numeric values (8 Bytes), or Boolean values (4 Bytes).
+
+* The size of UTF8-encoded strings is computed by counting all characters, excluding UNICODE control characters (segments C0 and C1).
 
-The size is computed by counting all characters, excluding UNICODE control characters (segments C0 and C1) and spaces that are outside of string constants.
+* Complex property values (nested objects) are computed based on the aggregate size of the property keys and property values that they contain.
 
-IoT Hub rejects with an error all operations that would increase the size of those documents above the limit.
+IoT Hub rejects with an error all operations that would increase the size of the `tags`, `properties/desired`, or `properties/reported` documents above the limit.
 
 ## Device twin metadata
 

articles/iot-hub/iot-hub-devguide-module-twins.md

@@ -5,7 +5,7 @@ author: chrissie926
 ms.service: iot-hub
 services: iot-hub
 ms.topic: conceptual
-ms.date: 04/26/2018
+ms.date: 02/01/2020
 ms.author: menchi
 ---
 
@@ -231,11 +231,15 @@ The [Azure IoT device SDKs](iot-hub-devguide-sdks.md) make it easy to use the pr
 
 Tags, desired properties, and reported properties are JSON objects with the following restrictions:
 
-* All keys in JSON objects are case-sensitive 64 bytes UTF-8 UNICODE strings. Allowed characters exclude UNICODE control characters (segments C0 and C1), and `.`, SP, and `$`.
+* **Keys**: All keys in JSON objects are case-sensitive 64 bytes UTF-8 UNICODE strings. Allowed characters exclude UNICODE control characters (segments C0 and C1), and `.`, SP, and `$`.
 
-* All values in JSON objects can be of the following JSON types: boolean, number, string, object. Arrays are not allowed. The maximum value for integers is 4503599627370495 and the minimum value for integers is -4503599627370496.
+* **Values**: All values in JSON objects can be of the following JSON types: boolean, number, string, object. Arrays are not allowed.
 
-* All JSON objects in tags, desired, and reported properties can have a maximum depth of 5. For instance, the following object is valid:
+    * Integers can have a minimum value of -4503599627370496 and a maximum value of 4503599627370495.
+
+    * String values are UTF-8 encoded and can have a maximum length of 512 bytes.
+
+* **Depth**: All JSON objects in tags, desired, and reported properties can have a maximum depth of 5. For instance, the following object is valid:
 
     ```json
     {
@@ -257,13 +261,21 @@ Tags, desired properties, and reported properties are JSON objects with the foll
     }
     ```
 
-* All string values can be at most 512 bytes in length.
-
 ## Module twin size
 
-IoT Hub enforces an 8 KB size limit on the value of `tags`, and a 32 KB size limit each on the value of `properties/desired` and `properties/reported`. These totals are exclusive of read-only elements.
+IoT Hub enforces an 8 KB size limit on the value of `tags`, and a 32 KB size limit each on the value of `properties/desired` and `properties/reported`. These totals are exclusive of read-only elements like `$etag`, `$version`, and `$metadata/$lastUpdated`.
+
+Twin size is computed as follows:
+
+* For each property in the JSON document, IoT Hub cumulatively computes and adds the length of the property's key and value.
+
+* Property keys are considered as UTF8-encoded strings.
+
+* Simple property values are considered as UTF8-encoded strings, numeric values (8 Bytes), or Boolean values (4 Bytes).
+
+* The size of UTF8-encoded strings is computed by counting all characters, excluding UNICODE control characters (segments C0 and C1).
 
-The size is computed by counting all characters, excluding UNICODE control characters (segments C0 and C1) and spaces that are outside of string constants.
+* Complex property values (nested objects) are computed based on the aggregate size of the property keys and property values that they contain.
 
 IoT Hub rejects with an error all operations that would increase the size of those documents above the limit.