Edited Olga's latest updates

Linda-Editor · Linda-Editor · commit 5936a33ce1a4 · 2022-06-30T14:48:39.000-07:00
diff --git a/graph/GuidelinesGraph.md b/graph/GuidelinesGraph.md
@@ -216,7 +216,7 @@ The three most often used patterns in Microsoft Graph today are type hierarchy,
 
 - **[Facets](./patterns/facets.md)** are represented by a single entity type with common properties and one facet property (of complex type) per variant. The facet properties only have a value when the object represents that variant.
 
-- **[Flat bag of properties]/(./patterns/flat-bag.md)** is represented by one entity type with all the potential properties plus an additional property to distinguish the variants, often called type. The type property describes the variant and also defines properties that are required or meaningful for the variant given by the type property.
+- **[Flat bag of properties](./patterns/flat-bag.md)** is represented by one entity type with all the potential properties plus an additional property to distinguish the variants, often called type. The type property describes the variant and also defines properties that are required or meaningful for the variant given by the type property.
 
 The following table shows a summary of the main qualities for each pattern and can help you select a pattern fit for your use case.
 
@@ -234,7 +234,7 @@ Following are a few pros and cons to decide which pattern to use:
 
 - Introducing new cases in **hierarchy** is relatively isolated (which is why it is so familiar to OOP) and is considered backwards compatible (at least syntactically).
 
-- Introducing new cases/variants in **[facets](./patterns/facets.md)** is straightforward. You need to be careful because it can introduce situations where previously only one of the facets was non-null and now all the old ones are null. This is not unlike adding new subtypes in the **hierarchy** pattern or adding a new type value in the **flat** pattern.
+- Introducing new cases/variants in **[facets](./patterns/facets.md)** is straightforward. You need to be careful because it can introduce situations where previously only one of the facets was non-null and now all the old ones are null. This is not unlike adding new subtypes in the **hierarchy** pattern or adding a new type value in the **[flat bag](./patterns/flat-bag.md)** pattern.
 
 - **hierarchy** and **facets** (to a slightly lesser degree) are well-suited for strongly typed client programming languages, whereas **flat bag** is more familiar to developers of less strongly typed languages.
 
@@ -380,8 +380,8 @@ The guidelines in previous sections are intentionally brief and provide a jump s
 | [Dictionary](./patterns/dictionary.md)           | Clients can provide an unknown quantity of data elements of the same type. |
 | [Evolvable enums](./patterns/evolvable-enums.md) | Extend enumerated types without breaking changes.                          |
 | [Facets](./patterns/facets.md)                   | Model parent-child relationships.                                          |
-| [Flat bag](./patterns/flat-bag.md)                | Model variants of the same type.                                          |
-| [Long running operations](./patterns/longRunningOperations.md)| Model operations where processing a client request takes a long time.    |
+| [Flat bag](./patterns/flat-bag.md)               | Model variants of the same type.                                           |
+| [Long running operations](./patterns/longRunningOperations.md)| Model operations where processing a client request takes a long time. |
 | [Modeling subsets](./patterns/subsets.md)        | Model collection subsets for All, None, Included, or Excluded criteria.    |
 | [Namespace](./patterns/namespace.md)             | Organize resource definitions into a logical set.                          |
 | [Type hierarchy](./patterns/subtypes.md)         | Model `is-a` relationships using subtypes.                                 |
diff --git a/graph/patterns/alternate-key.md b/graph/patterns/alternate-key.md
@@ -153,7 +153,7 @@ Declare `mail` and `ssn` as alternate keys on an entity:
     }
     ```
 
-4. Request a resource where the alternate key property does not exist on any resource in the colleciton:
+4. Request a resource where the alternate key property does not exist on any resource in the collection:
 
     ```http
     GET https://graph.microsoft.com/v1.0/users(email='unknown@contoso.com')
diff --git a/graph/patterns/evolvable-enums.md b/graph/patterns/evolvable-enums.md
@@ -2,7 +2,7 @@
 
 Microsoft Graph API Design Pattern
 
-*The evolvable enum pattern allows API producers to extend enumerated types with new members without breaking API consumers.*
+*The evolvable enums pattern allows API producers to extend enumerated types with new members without breaking API consumers.*
 
 ## Problem
 
diff --git a/graph/patterns/facets.md b/graph/patterns/facets.md
@@ -19,7 +19,7 @@ In this solution, a child variant is identified by the presence of one or more f
 
 The facet pattern is useful when there is a number of variants and they are not mutually exclusive. It also makes it syntactically easier to query resources by using OData $filter expression because it doesn't require casting.
 
-You can consider related patterns such as [Type hierarchy](./subtypes.md) and Flat bag of properties.
+You can consider related patterns such as [type hierarchy](./subtypes.md) and [flat bag of properties](./flat-bag.md).
 
 ## Issues and considerations
 
diff --git a/graph/patterns/flat-bag.md b/graph/patterns/flat-bag.md
@@ -1,33 +1,31 @@
-# Flat Bag of properties Pattern
+# Flat bag of properties
 
 Microsoft Graph API Design Pattern
 
 *A known pattern in Microsoft Graph is to model multiple variants of a common concept as a single entity type with all potential properties plus an additional property to distinguish the variants.*
 
-
 ## Problem
 
-API designers need to model a small and limited number of variants of a common concept with a concise list of non-overlapping properties and consistent behavior across variant. The designer also wants to simplify query construction.
+API designers need to model a small and limited number of variants of a common concept with a concise list of non-overlapping properties and consistent behavior across variants. The designer also wants to simplify query construction.
 
 ## Solution
 
-The API designer creates one entity type with all the potential properties plus an additional property to distinguish the variants, often called `variantType`. For each value of `variantType`  some properties are meaningful and others are ignored. 
+The API designer creates one entity type with all the potential properties plus an additional property to distinguish the variants, often called `variantType`. For each value of `variantType`, some properties are meaningful and others are ignored.
 
 ## When to use this pattern
 
-The Flat bag pattern is useful when there is a small number of variants with similar behavior and variants are queried for  mostly read-only operations. 
-The pattern also makes it syntactically easier to query resources by using OData $filter expression because it doesn't require casting.
+The flat bag pattern is useful when there is a small number of variants with similar behavior, and variants are queried for mostly read-only operations. The pattern also makes it syntactically easier to query resources by using the OData `$filter` expression because it doesn't require casting.
 
 ## Issues and considerations
 
-In general the Flat bag pattern is the least recommended modeling choice because it is weakly typed and it is difficult to semantically verify targeted resource modifications. But there are circumstances when query simplicity and limited number of properties may overweight considerations of more strongly typed approach.
-The pattern is not recommended for large number of variants and properties because the payload becomes sparsely populated.
+In general, the flat bag pattern is the least recommended modeling choice because it is weakly typed, and it is difficult to semantically verify targeted resource modifications. However, there are circumstances when query simplicity and a limited number of properties might overweight considerations of a more strongly typed approach.
+The pattern is not recommended for a large number of variants and properties because the payload becomes sparsely populated.
 
-You can consider related patterns such as Type hierarchy and Flat bag of properties.
+You can consider related patterns such as [type hierarchy](./subtypes.md) and [facets](./facets.md).
 
 ## Example
 
-A good example for Flat bag implementation is the recurrencePattern type on [recurrencePattern](https://docs.microsoft.com/en-us/graph/api/resources/recurrencepattern?view=graph-rest-1.0).
+A good example for flat bag implementation is the recurrencePattern type on [recurrencePattern](https://docs.microsoft.com/graph/api/resources/recurrencepattern).
 
 The recurrencePattern has six variants expressed as six different values of the `type` property (for example: daily, weekly, ...). The key here is that for each of these values, some properties are meaningful and others are ignored (for example: `daysOfWeek` is relevant when `type` is `weekly` but not when it is `daily`).
 
diff --git a/graph/patterns/long-running-operations.md b/graph/patterns/long-running-operations.md
@@ -2,15 +2,17 @@
 
 Microsoft Graph API Design Pattern
 
-__*The long running operations (LRO) pattern provides the ability to model operations where processing a client request takes a long time, but the client isn't blocked and can do some other work until operation completion.*__
+*The long running operations (LRO) pattern provides the ability to model operations where processing a client request takes a long time, but the client isn't blocked and can do some other work until operation completion.*
 
 ## Problem
 
 The API design requires modeling operations on resources, which takes a long time
 to complete so that API clients don't need to wait and can continue doing other
 work while waiting for the final operation results. The client should be able to
 monitor the progress of the operation and have an ability to cancel it if
-needed. The API needs to provide a mechanism to track the work
+needed.
+
+The API needs to provide a mechanism to track the work
 being done in the background. The mechanism needs to be expressed in the same
 web style as other interactive APIs. It also needs to support checking on the status and/or
 being notified asynchronously of the results.
@@ -24,18 +26,15 @@ operation.
 There are two flavors of this solution:
 
 - The returned resource is the targeted resource and includes the status of
-    the operation. This pattern is often called RELO (resource-based
-    long running operation).
+  the operation. This pattern is often called RELO (resource-based long running operation).
 
 <!-- markdownlint-disable MD033 -->
 <p align="center">
   <img src="RELO.gif" alt="The status monitor LRO flow"/>
 </p>
 <!-- markdownlint-enable MD033 -->
 
-- The returned resource is a new API resource called 'Stepwise Operation' and
-    is created to track the status. This LRO solution is similar to the concept
-    of Promises or Futures in other programming languages.
+- The returned resource is a new API resource called *stepwise operation* and is created to track the status. This LRO solution is similar to the concept of Promises or Futures in other programming languages.
 
 <!-- markdownlint-disable MD033 -->
 <p align="center">
@@ -47,32 +46,28 @@ The RELO pattern is the preferred pattern for long running operations and should
 used wherever possible. The pattern avoids complexity, and consistent resource
 presentation makes things simpler for our users and tooling chain.
 
-In general, Microsoft Graph API guidelines for LRO follow [Microsoft REST API
+In general, Microsoft Graph API guidelines for long running operations follow [Microsoft REST API
 Guidelines](https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md#13-long-running-operations).
 
 There are some deviations from the base guidelines where Microsoft Graph API standards require that you do one of the following:
 
-- For RELO pattern you should return the Location header that indicates the location of the resource.
+- For the RELO pattern, you should return the Location header that indicates the location of the resource.
   - The API response says the targeted resource is being created by returning a 201 status code and the resource URI is provided in the Location header, but the response indicates that the request is not completed by including "Provisioning" status.
 
-- For LRO pattern you should return the Location header that indicates the location of a new stepwise operation resource.
+- For the LRO pattern, you should return the Location header that indicates the location of a new stepwise operation resource.
   - The API response says the operation resource is being created at the URL provided in the Location header and indicates that the request is not completed by including a 202 status code.
-  - Microsoft Graph doesn’t allow tenant wide operation resources therefore stepwise operations is often modeled as a navigation property on the target resource.
+  - Microsoft Graph doesn’t allow tenant-wide operation resources; therefore, stepwise operations are often modeled as a navigation property on the target resource.
 
 ## When to use this pattern
 
-Any API call that is expected to take longer than 1 second in the 99th percentile should use the long running operations pattern.
+Any API call that is expected to take longer than one second in the 99th percentile should use the long running operations pattern.
 
-How do you select which flavor of LRO pattern to use? An API designer can follow these
-heuristics:
+How do you select which flavor of LRO pattern to use? An API designer can follow these heuristics:
 
-1.  If a service can create a resource with a minimal latency and continue
-    updating its status according to the well-defined and stable state
-    transition model until completion, then the RELO model is the best choice.
+1. If a service can create a resource with a minimal latency and continue updating its status according to the well-defined and stable state transition model until completion, then the RELO model is the best choice.
 
-2.  Otherwise, a service should follow the Stepwise Operation pattern. 
+2. Otherwise, a service should follow the stepwise operation pattern.
  
-
 ## Issues and considerations
 
 - One or more API consumers MUST be able to monitor and operate on the same resource at the same time.
@@ -82,32 +77,28 @@ heuristics:
     resource is no longer active. Clients MAY issue a GET on some resource to
     determine the state of a long running operation.
 
--  The long running operations pattern SHOULD work for clients looking to "fire and forget"
+- The long running operations pattern SHOULD work for clients looking to "fire and forget"
     and for clients looking to actively monitor and act upon results.
 
--  The long running operations pattern might be supplemented by the [change notification
-    pattern](change-notification.md).
+- The long running operations pattern might be supplemented by the [change notification pattern](./change-notification.md).
 
--  Cancellation of a long running operation does not explicitly mean a rollback. On a per API-defined case, it
-    might mean a rollback, or compensation, or completion, or partial completion,
+- Cancellation of a long running operation does not explicitly mean a rollback. On a per API-defined case, it
+    might mean a rollback or compensation or completion or partial completion,
     etc. Following a canceled operation, the API should return a consistent state that allows
     continued service.
 
--  A recommended minimum retention time for a stepwise operation is 24 hours.
+- A recommended minimum retention time for a stepwise operation is 24 hours.
     Operations SHOULD transition to "tombstone" for an additional period of time
     prior to being purged from the system.
     
--  Services that provides a new operation resource MUST support GET semantics on the operation.
--  Services that returns a new operation MUST always return an LRO (even if the LRO is created in the completed state) that way API consumers don't have to deal with two different shapes of response.
-
-
+- Services that provide a new operation resource MUST support GET semantics on the operation.
+- Services that return a new operation MUST always return an LRO (even if the LRO is created in the completed state); that way API consumers don't have to deal with two different shapes of response.
 
 ## Examples
 
+### Create a new resource using RELO
 
-###  Create a new resource using RELO
-
-A client wants to provision a new database
+A client wants to provision a new database:
 
 ```
 POST https://graph.microsoft.com/v1.0/storage/databases/
@@ -119,7 +110,7 @@ POST https://graph.microsoft.com/v1.0/storage/databases/
 
 The API responds synchronously that the database has been created and indicates
 that the provisioning operation is not fully completed by including the
-Content-Location header and status property in the response payload.
+Content-Location header and status property in the response payload:
 
 ```
 HTTP/1.1 201 Created
@@ -132,7 +123,8 @@ Location: https://graph.microsoft.com/v1.0/storage/databases/db1
 [ … other fields for "database" …]
 }
 ```
-The client waits for a period of time then invokes another request to try to get the database status.
+
+The client waits for a period of time, and then invokes another request to try to get the database status:
 
 ```
 GET https://graph.microsoft.com/v1.0/storage/databases/db1
@@ -146,10 +138,9 @@ HTTP/1.1 200 Ok
 }
 ```
 
+### Cancel RELO operation
 
-###  Cancel RELO operation
-
-A client wants to cancel provisioning of a new database
+A client wants to cancel provisioning of a new database:
 
 ```
 DELETE https://graph.microsoft.com/v1.0/storage/databases/db1
@@ -159,7 +150,7 @@ DELETE https://graph.microsoft.com/v1.0/storage/databases/db1
 The API responds synchronously that the database is being deleted and indicates
 that the operation is accepted and is not fully completed by including the
 status property in the response payload. The API might provide a
-recommendation to wait for 30 seconds.
+recommendation to wait for 30 seconds:
 
 ```
 HTTP/1.1 202 Accepted
@@ -172,14 +163,15 @@ Retry-After: 30
 [ … other fields for "database" …]
 }
 ```
-The client waits for a period of time then invokes another request to try to get the deletion status.
+
+The client waits for a period of time, and then invokes another request to try to get the deletion status:
 
 ```
 GET https://graph.microsoft.com/v1.0/storage/databases/db1
 
 HTTP/1.1 404 Not Found
 ```
-### Create a new resource using the Stepwise Operation
+### Create a new resource using the stepwise operation
 
 ```
 POST https://graph.microsoft.com/v1.0/storage/archives/
@@ -191,7 +183,7 @@ POST https://graph.microsoft.com/v1.0/storage/archives/
 ```
 
 The API responds synchronously that the request has been accepted and includes
-the Location header with an operation resource for further polling.
+the Location header with an operation resource for further polling:
 
 ```
 HTTP/1.1 202 Accepted
@@ -200,15 +192,15 @@ Location: https://graph.microsoft.com/v1.0/storage/operations/123
 
 ```
 
-### Poll on a Stepwise Operation
+### Poll on a stepwise operation
 
 ```
 
 GET https://graph.microsoft.com/v1.0/storage/operations/123
 ```
 
 The server responds that results are still not ready and optionally provides a
-recommendation to wait 30 seconds.
+recommendation to wait 30 seconds:
 
 ```
 HTTP/1.1 200 OK
@@ -220,6 +212,7 @@ Retry-After: 30
 "status": "running"
 }
 ```
+
 The client waits the recommended 30 seconds and then invokes another request to get
 the results of the operation.
 
@@ -241,7 +234,8 @@ HTTP/1.1 200 OK
 "resourceLocation": "https://graph.microsoft.com/v1.0/storage/archives/987"
 }
 ```
-### Trigger a long running action using the Stepwise Operation
+
+### Trigger a long running action using the stepwise operation
 
 ```
 POST https://graph.microsoft.com/v1.0/storage/copyArchive
@@ -254,7 +248,7 @@ POST https://graph.microsoft.com/v1.0/storage/copyArchive
 ```
 
 The API responds synchronously that the request has been accepted and includes
-the Location header with an operation resource for further polling.
+the Location header with an operation resource for further polling:
 
 ```
 HTTP/1.1 202 Accepted
diff --git a/graph/patterns/operations.md b/graph/patterns/operations.md
diff --git a/graph/patterns/subtypes.md b/graph/patterns/subtypes.md

Original file line number	Diff line number	Diff line change
@@ -153,7 +153,7 @@ Declare `mail` and `ssn` as alternate keys on an entity:
`153`	`153`	`}`
`154`	`154`	```
`155`	`155`
`156`		`-4. Request a resource where the alternate key property does not exist on any resource in the colleciton:`
	`156`	`+4. Request a resource where the alternate key property does not exist on any resource in the collection:`
`157`	`157`
`158`	`158`	```http
`159`	`159`	`GET https://graph.microsoft.com/v1.0/users(email='[email protected]')`