flat-bag updates

Author: OlgaPodo

graph/patterns/facets.md

@@ -65,7 +65,7 @@ The driveItem resource represents a file, folder, image, or other item stored in
 An API request to get all items from a personal OneDrive returns a heterogenous collection with different facets populated. In the following example, there is a folder, a file, and an image in the collection. The image entity has two facets populated: file and image.
 
 ```
-https://graph.microsoft.com/v1.0/me/drive/root/children
+GET https://graph.microsoft.com/v1.0/me/drive/root/children
 
 Response shortened for readability:
  

graph/patterns/flat-bag.md

@@ -2,32 +2,52 @@
 
 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 the potential properties plus an additional property to distinguish the variants.*
+*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 designer needs 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 variant. 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`.
+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. 
 
-## Issues and Considerations
+## 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.
 
+## Issues and considerations
 
-## When to Use this Pattern
+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.
 
-The flat-bag pattern is useful when there is a small number of variants 
-
-????
-
-There are related patterns to consider such as
-[Type Hierarchy](https://github.com/microsoft/api-guidelines/tree/graph/graph) and [Flat
-bag of
-properties](https://github.com/microsoft/api-guidelines/tree/graph/graph).
+You can consider related patterns such as Type hierarchy and Flat bag of properties.
 
 ## Example
-?????
+
+A good example for flat-bag implementation is the recurrencePattern and recurrenceRange types on [patternedRecurrence](https://docs.microsoft.com/graph/api/resources/patternedrecurrence).
+
+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`).
+
+```
+<EnumType Name="recurrencePatternType">
+        <Member Name="daily" Value="0" />
+        <Member Name="weekly" Value="1" />
+        <Member Name="absoluteMonthly" Value="2" />
+        <Member Name="relativeMonthly" Value="3" />
+        <Member Name="absoluteYearly" Value="4" />
+        <Member Name="relativeYearly" Value="5" />
+</EnumType>
+
+<ComplexType Name="recurrencePattern" ags:WorkloadIds="Microsoft.Exchange,Microsoft.IdentityGovernance.AccessReviews,Microsoft.IGAELM,Microsoft.PIM.AzureRBAC,Microsoft.Tasks,Microsoft.Teams.Shifts,Microsoft.Todo" ags:PassthroughWorkloadIds="Microsoft.Exchange">
+        <Property Name="dayOfMonth" Type="Edm.Int32" Nullable="false" />
+        <Property Name="daysOfWeek" Type="Collection(graph.dayOfWeek)" />
+        <Property Name="firstDayOfWeek" Type="graph.dayOfWeek" />
+        <Property Name="index" Type="graph.weekIndex" />
+        <Property Name="interval" Type="Edm.Int32" Nullable="false" />
+        <Property Name="month" Type="Edm.Int32" Nullable="false" />
+        <Property Name="type" Type="graph.recurrencePatternType" />
+</ComplexType>
+```