Acrolinx

Author: baanders

articles/digital-twins/how-to-manage-twin.md

@@ -44,9 +44,9 @@ To create a digital twin, you need to provide:
 * An ID value you want to assign to the digital twin (you're defining that ID when the twin is created)
 * The [model](concepts-models.md) you want to use
 * Any desired initialization of twin data, including...
-    - Properties (optional to initialize): You can set initial values for properties of the digital twin if you want. Properties are treated as optional and can be set later, but note that **they won't show up as part of a twin until they've been set**.
-    - Telemetry (recommended to initialize): You can also set initial values for telemetry fields on the twin. Although initializing telemetry isn't required, telemetry fields also won't show up as part of a twin until they've been set. This means that **you'll be unable to edit telemetry values for a twin unless they've been initialized first**.
-    - Components (required to initialize if present on twin): If your twin contains any [components](concepts-models.md#model-attributes), these must be initialized when the twin is created. They can be empty objects, but the components themselves have to exist.
+    - Properties (initialization optional): You can set initial values for properties of the digital twin if you want. Properties are treated as optional and can be set later, but note that **they won't show up as part of a twin until they've been set**.
+    - Telemetry (initialization recommended): You can also set initial values for telemetry fields on the twin. Although initializing telemetry isn't required, telemetry fields also won't show up as part of a twin until they've been set. This means that **you'll be unable to edit telemetry values for a twin unless they've been initialized first**.
+    - Components (initialization required if they're present on a twin): If your twin contains any [components](concepts-models.md#model-attributes), these must be initialized when the twin is created. They can be empty objects, but the components themselves have to exist.
 
 The model and any initial property values are provided through the `initData` parameter, which is a JSON string containing the relevant data. For more information on structuring this object, continue to the next section.
 
@@ -86,7 +86,7 @@ You can access the details of any digital twin by calling the `GetDigitalTwin()`
 
 :::code language="csharp" source="~/digital-twins-docs-samples/sdks/csharp/twin_operations_sample.cs" id="GetTwinCall":::
 
-This call returns twin data as a strongly-typed object type such as `BasicDigitalTwin`. `BasicDigitalTwin` is a serialization helper class included with the SDK, which will return the core twin metadata and properties in pre-parsed form. You can always deserialize twin data using the JSON library of your choice, like `System.Text.Json` or `Newtonsoft.Json`. For basic access to a twin, however, the helper classes can make this more convenient.
+This call returns twin data as a strongly typed object type such as `BasicDigitalTwin`. `BasicDigitalTwin` is a serialization helper class included with the SDK, which will return the core twin metadata and properties in pre-parsed form. You can always deserialize twin data using the JSON library of your choice, like `System.Text.Json` or `Newtonsoft.Json`. For basic access to a twin, however, the helper classes can make this more convenient.
 
 > [!NOTE]
 > `BasicDigitalTwin` uses `System.Text.Json` attributes. In order to use `BasicDigitalTwin` with your [DigitalTwinsClient](/dotnet/api/azure.digitaltwins.core.digitaltwinsclient?view=azure-dotnet&preserve-view=true), you must either initialize the client with the default constructor, or, if you want to customize the serializer option, use the [JsonObjectSerializer](/dotnet/api/azure.core.serialization.jsonobjectserializer?view=azure-dotnet&preserve-view=true).
@@ -134,12 +134,12 @@ The result of calling `object result = await client.GetDigitalTwinAsync("my-moon
 }
 ```
 
-The defined properties of the digital twin are returned as top-level properties on the digital twin. Metadata or system information that is not part of the DTDL definition is returned with a `$` prefix. Metadata properties include the following values:
+The defined properties of the digital twin are returned as top-level properties on the digital twin. Metadata or system information that isn't part of the DTDL definition is returned with a `$` prefix. Metadata properties include the following values:
 * `$dtId`: The ID of the digital twin in this Azure Digital Twins instance
 * `$etag`: A standard HTTP field assigned by the web server. This is updated to a new value every time the twin is updated, which can be useful to determine whether the twin's data has been updated on the server since a previous check. You can use `If-Match` to perform updates and deletes that only complete if the entity's etag matches the etag provided. For more information on these operations, see the documentation for [DigitalTwins Update](/rest/api/digital-twins/dataplane/twins/digitaltwins_update) and [DigitalTwins Delete](/rest/api/digital-twins/dataplane/twins/digitaltwins_delete).
 * `$metadata`: A set of other properties, including:
   - The DTMI of the model of the digital twin.
-  - Synchronization status for each writable property. This is most useful for devices, where it's possible that the service and the device have diverging statuses (for example, when a device is offline). Currently, this property only applies to physical devices connected to IoT Hub. With the data in the metadata section, it is possible to understand the full status of a property, as well as the last modified timestamps. For more information about sync status, see this [IoT Hub tutorial](../iot-hub/tutorial-device-twins.md) on synchronizing device state.
+  - Synchronization status for each writable property. This is most useful for devices, where it's possible that the service and the device have diverging statuses (for example, when a device is offline). Currently, this property only applies to physical devices connected to IoT Hub. With the data in the metadata section, it's possible to understand the full status of a property, as well as the last modified timestamps. For more information about sync status, see this [IoT Hub tutorial](../iot-hub/tutorial-device-twins.md) on synchronizing device state.
   - Service-specific metadata, like from IoT Hub or Azure Digital Twins. 
 
 You can read more about the serialization helper classes like `BasicDigitalTwin` in [Azure Digital Twins APIs and SDKs](concepts-apis-sdks.md#serialization-helpers).
@@ -148,7 +148,7 @@ You can read more about the serialization helper classes like `BasicDigitalTwin`
 
 To view all of the digital twins in your instance, use a [query](how-to-query-graph.md). You can run a query with the [Query APIs](/rest/api/digital-twins/dataplane/query) or the [CLI commands](/cli/azure/dt/twin#az-dt-twin-query).
 
-Here is the body of the basic query that will return a list of all digital twins in the instance:
+Here's the body of the basic query that will return a list of all digital twins in the instance:
 
 :::code language="sql" source="~/digital-twins-docs-samples/queries/examples.sql" id="GetAllTwins":::
 
@@ -165,11 +165,11 @@ A single patch call can update as many properties on a single twin as you want (
 > [!TIP]
 > After creating or updating a twin, there may be a latency of up to 10 seconds before the changes will be reflected in [queries](how-to-query-graph.md). The `GetDigitalTwin` API (described [earlier in this article](#get-data-for-a-digital-twin)) does not experience this delay, so use the API call instead of querying to see your newly-updated twins if you need an instant response. 
 
-Here is an example of JSON Patch code. This document replaces the *mass* and *radius* property values of the digital twin it is applied to. This example shows the JSON Patch `replace` operation, which replaces the value of an existing property.
+Here's an example of JSON Patch code. This document replaces the *mass* and *radius* property values of the digital twin it's applied to. This example shows the JSON Patch `replace` operation, which replaces the value of an existing property.
 
 :::code language="json" source="~/digital-twins-docs-samples/models/patch.json":::
 
-When updating a twin from a code project using the .NET SDK, you can create JSON patches using the Azure .NET SDK's [JsonPatchDocument](/dotnet/api/azure.jsonpatchdocument?view=azure-dotnet&preserve-view=true). Here is an example of creating a JSON Patch document and using `UpdateDigitalTwin()` in project code.
+When updating a twin from a code project using the .NET SDK, you can create JSON patches using the Azure .NET SDK's [JsonPatchDocument](/dotnet/api/azure.jsonpatchdocument?view=azure-dotnet&preserve-view=true). Here's an example of creating a JSON Patch document and using `UpdateDigitalTwin()` in project code.
 
 :::code language="csharp" source="~/digital-twins-docs-samples/sdks/csharp/twin_operations_other.cs" id="UpdateTwin":::
 
@@ -190,7 +190,7 @@ Models may contain properties that are of an object type. Those objects may have
 
 Consider a model with an object-type property, `ObjectProperty`. `ObjectProperty` has a string property named `StringSubProperty`.
 
-When a twin is created using this model, it's not necessary to instantiate the `ObjectProperty` at that time. If the object property is not instantiated during twin creation, there is no default path created to access `ObjectProperty` and its `StringSubProperty` for a patch operation. You will need to add the path to `ObjectProperty` yourself before you can update its properties.
+When a twin is created using this model, it's not necessary to instantiate the `ObjectProperty` at that time. If the object property isn't instantiated during twin creation, there's no default path created to access `ObjectProperty` and its `StringSubProperty` for a patch operation. You'll need to add the path to `ObjectProperty` yourself before you can update its properties.
 
 This can be done with a JSON Patch `add` operation, like this:
 
@@ -207,7 +207,7 @@ After this has been done once, a path to `StringSubProperty` exists, and it can
 
 :::code language="json" source="~/digital-twins-docs-samples/models/patch-object-sub-property-2.json":::
 
-Although the first step isn't necessary in cases where `ObjectProperty` was instantiated when the twin was created, it's recommended to use it every time you update a sub-property for the first time, since you may not always know for sure whether the object property was initially instantiated or not.
+Although the first step isn't necessary in cases where `ObjectProperty` was instantiated when the twin was created, it's recommended to use it every time you update a sub-property for the first time, since you may not always know with certainty whether the object property was initially instantiated or not.
 
 ### Update a digital twin's model
 
@@ -230,15 +230,15 @@ The patch for this situation needs to update both the model and the twin's tempe
 
 ### Update a property's sourceTime
 
-You may optionally decide to use the `sourceTime` field on twin properties to record timestamps for when property updates are observed in the real world. Azure Digital Twins natively supports `sourceTime` in the metadata for each twin property. The `sourceTime` value must comply to ISO 8601 date and time format. For more information about this field and other fields on digital twins, see [Digital twin JSON format](concepts-twins-graph.md#digital-twin-json-format).
+You may optionally decide to use the `sourceTime` field on twin properties to record timestamps for when property updates are observed in the real world. Azure Digital Twins natively supports `sourceTime` in the metadata for each twin property. The `sourceTime` value must comply with ISO 8601 date and time format. For more information about this field and other fields on digital twins, see [Digital twin JSON format](concepts-twins-graph.md#digital-twin-json-format).
 
 The minimum stable REST API version to support this field is the [2022-05-31](https://github.com/Azure/azure-rest-api-specs/tree/main/specification/digitaltwins/data-plane/Microsoft.DigitalTwins/stable/2022-05-31) version. To work with this field using the [Azure Digital Twins SDKs](concepts-apis-sdks.md), we recommend using the latest version of the SDK to make sure this field is included.
 
 Here's an example of a JSON Patch document that updates both the value and the `sourceTime` field of a `Temperature` property:
 
 :::code language="json" source="~/digital-twins-docs-samples/models/patch-sourcetime.json":::
 
-To update the `sourceTime` field on a property that's part of a component, include the component at the start of the path. In the example above, this would mean changing the path value from `/$metadata/Temperature/sourceTime` to `myComponent/$metadata/Temperature/sourceTime`.
+To update the `sourceTime` field on a property that's part of a component, include the component at the start of the path. In the example above, you would do this by changing the path value from `/$metadata/Temperature/sourceTime` to `myComponent/$metadata/Temperature/sourceTime`.
 
 >[!NOTE]
 > If you update both the `sourceTime` and value on a property, and then later update only the property's value, the `sourceTime` timestamp from the first update will remain.