Address PR review feedback

Author: mikekistler

azure/ConsiderationsForServiceDesign.md

@@ -6,8 +6,9 @@
 
 | Date        | Notes                                                          |
 | ----------- | -------------------------------------------------------------- |
+| 2024-Jan-17 | Added guidelines on returning string offsets & lengths         |
 | 2022-Jul-15 | Update guidance on long-running operations                     |
-| 2022-Feb-01 | Updated error guidance                                        |
+| 2022-Feb-01 | Updated error guidance                                         |
 | 2021-Sep-11 | Add long-running operations guidance                           |
 | 2021-Aug-06 | Updated Azure REST Guidelines per Azure API Stewardship Board. |
 
@@ -517,7 +518,7 @@ By computing and returning ETags for your resources, you enable clients to avoid
 
 ## Returning String Offsets & Lengths (Substrings)
 
-Some Azure services return substring offset & length values within a string. For example, the offset & length within a string to a name, email address, or phone #.
+Some Azure services return substring offset & length values within a string. For example, the offset & length within a string to a name, email address, or phone number.
 When a service response includes a string, the client's programming language deserializes that string into that language's internal string encoding. Below are the possible encodings and examples of languages that use each encoding:
 
 | Encoding    | Example languages |
@@ -526,44 +527,44 @@ When a service response includes a string, the client's programming language des
 | UTF-16 | JavaScript, Java, C# |
 | CodePoint (UTF-32) | Python |
 
-Because the service doesn't know what language a client is written in and what string encoding that language uses, the service can't return UTF-agnostic offset and length values that the client can use to index within the string. To address this, the service response must include offset & length values for all 3 possible encodings and then the client code must select the encoding it required by its language's internal string encoding.
+Because the service doesn't know in what language a client is written and what string encoding that language uses, the service can't return UTF-agnostic offset and length values that the client can use to index within the string. To address this, the service response must include offset & length values for all 3 possible encodings and then the client code must select the encoding required by its language's internal string encoding.
 
 For example, if a service response needed to identify offset & length values for "name" and "email" substrings, the JSON response would look like this:
 
-```
+```json
 {
   (... other properties not shown...)
   "fullString": "(...some string containing a name and an email address...)",
   "name": {
     "offset": {
       "utf8": 12,
       "utf16": 10,
-      "codePoint":  4
+      "codePoint": 4
     },
     "length": {
       "uft8": 10,
       "utf16": 8,
-      "codePoint":  2
+      "codePoint": 2
     }
   },
   "email": {
     "offset": {
       "utf8": 12,
       "utf16": 10,
-      "codePoint":  4
+      "codePoint": 4
     },
     "length": {
       "uft8": 10,
       "utf16": 8,
-      "codePoint":  4
+      "codePoint": 4
     }
   }
 }
 ```
 
 Then, the Go developer, for example, would get the substring containing the name using code like this:
 
-```
+```go
    var response := client.SomeMethodReturningJSONShownAbove(...)
    name := response.fullString[ response.name.offset.utf8 : response.name.offset.utf8 + response.name.length.utf8]
 ```

azure/Guidelines.md

@@ -1107,6 +1107,14 @@ When a service response includes a string offset or length value, it should spec
 
 <a href="#substrings-return-value-for-each-encoding" name="substrings-return-value-for-each-encoding">:white_check_mark:</a> **DO** include all 3 encodings (UTF-8, UTF-16, and CodePoint) for every string offset or length value in a service response.
 
+<a href="#substrings-return-value-structure" name="substrings-return-value-structure">:white_check_mark:</a> **DO** define every string offset or length value in a service response as an object with the following structure:
+
+| Property    | Type    | Required | Description |
+| ----------- | ------- | :------: | ----------- |
+| `utf8`      | integer | true     | The offset or length of the substring in UTF-8 encoding |
+| `utf16`     | integer | true     | The offset or length of the substring in UTF-16 encoding |
+| `codePoint` | integer | true     | The offset or length of the substring in CodePoint encoding |
+
 <a href="#telemetry" name="telemetry"></a>
 ### Distributed Tracing & Telemetry
 Azure SDK client guidelines specify that client libraries must send telemetry data through the `User-Agent` header, `X-MS-UserAgent` header, and Open Telemetry.