First go at converting dictionary guidance to Pattern template

Author: darrelmiller

graph/dictionary/client-guidance.md renamed to graph/patterns/dictionary/client-guidance.md

@@ -1,12 +1,40 @@
-# Dictionary types
+# Dictionary
+
+Microsoft Graph API Design Pattern
+
+*The Dictionary type provides the ability to create a set of primitives or objects, of the same type, where the API consumer can define a name for each value in the set.*
+
+## Problem
+--------
+
+The API design requires a resource to include an unknown quantity of similar data elements that need to be named using values provided by the API consumer.
+
+## Solution
+--------
+
+API designers use a JSON object to represent a dictionary in a `application/json`response payload. When describing the model in CSDL, a new complex type can be created that derives from `Org.OData.Core.V1.Dictionary` and then use the `Org.OData.Validation.V1.OpenPropertyTypeConstraint`to constrain the type that can be used for the values in the dictionary.
+
+Dictionary entries can be added via `POST`, updated via `PATCH`, and they can be removed by setting the entry value to `null`. Multiple dictionaries can be updated at once by using `PATCH` on the dictionary property.
+
+## Issues and Considerations
+-------------------------
 
 Dictionaries, sometimes called maps, are a collection of name-value pairs. They allow dynamic data sets to be accessed in a systematic manner and are a good compromise between a strictly defined ahead of time structure with all its named properties and between a loosely defined dynamic object (i.e. OData OpenTypes).
 
+As dictionary entries are removed via setting the value to null, this means that dictionaries can only support values that are non-nullable.
+
+  OpenQuestions:
+  -  Can/should PUT be supported on the dictionary property and/or the entry value 
+  - What does OData say about being able to POST to a structured property? Will OData Web API allow that?
+  - Must an implementer support PATCH at both the dictionary level and the entry level?
+
 More information:
 
 - [OData reference](https://github.com/oasis-tcs/odata-vocabularies/blob/master/vocabularies/Org.OData.Core.V1.md#dictionary)
 
-## When to use dictionary types
+ 
+## When to Use this Pattern
+------------------------
 
 Before using a dictionary type in your API definition make sure your scenario fits the following criteria:
 
@@ -20,7 +48,10 @@ Before using a dictionary type in your API definition make sure your scenario fi
 - [Open types](https://docs.microsoft.com/en-us/aspnet/web-api/overview/odata-support-in-aspnet-web-api/odata-v4/use-open-types-in-odata-v4) when your data is not a collection in nature.
 - [Complex types](https://docs.microsoft.com/en-us/odata/webapi/complextypewithnavigationproperty) when the set of data values are known.
 
-## JSON payload example
+## Examples
+-------
+
+### JSON payload example
 
 The following example illustrates the resulting JSON for a property of dictionary type. The parent object has been ommitted for brievety.
 
@@ -38,11 +69,11 @@ The following example illustrates the resulting JSON for a property of dictionar
 }
 ```
 
-## HTTP calls examples
+### HTTP calls examples
 
 In this set of examples we're modeling a **roles** property of dictionary type on the user entity which is exposed by the users entity set.
 
-### Getting an entry from the dictionary
+#### Getting an entry from the dictionary
 
 ```HTTP
 GET https://graph.microsoft.com/v1.0/users/10/roles/author
@@ -56,7 +87,7 @@ Reponse:
 }
 ```
 
-### Getting the dictionary
+#### Getting the dictionary
 
 ```HTTP
 GET https://graph.microsoft.com/v1.0/users/10/roles
@@ -78,7 +109,7 @@ Reponse:
 }
 ```
 
-### Getting the entity with the dictionary
+#### Getting the entity with the dictionary
 
 ```HTTP
 GET https://graph.microsoft.com/v1.0/users/10
@@ -104,7 +135,7 @@ Reponse:
 }
 ```
 
-### Creating an entry in the dictionary
+#### Creating an entry in the dictionary
 
 ```HTTP
 POST https://graph.microsoft.com/v1.0/users/10/roles/author
@@ -114,7 +145,7 @@ POST https://graph.microsoft.com/v1.0/users/10/roles/author
 }
 ```
 
-### Updating the dictionary
+#### Updating the dictionary
 
 ```HTTP
 PATCH https://graph.microsoft.com/v1.0/users/10/roles
@@ -137,7 +168,7 @@ PATCH https://graph.microsoft.com/v1.0/users/10/roles
 > Note: the domain values for the existing author and maintainer entries will get udpated.
 > Note: the reviewer entry will be inserted in the dictionary.
 
-### Updating an entry in the dictionary
+#### Updating an entry in the dictionary
 
 ```HTTP
 PATCH https://graph.microsoft.com/v1.0/users/10/roles/author
@@ -147,13 +178,13 @@ PATCH https://graph.microsoft.com/v1.0/users/10/roles/author
 }
 ```
 
-### Deleting an entry from the dictionary
+#### Deleting an entry from the dictionary
 
 ```HTTP
 DELETE https://graph.microsoft.com/v1.0/users/10/roles/author
 ```
 
-## CDSL example
+### CDSL example
 
 The following example defines a complex type **roleSettings** as well as a dictionary of which the key will be a string and the value a **roleSettings**.
 
@@ -182,6 +213,6 @@ The following example defines a complex type **roleSettings** as well as a dicti
 </ComplexType>
 ```
 
-## Additional information
+### Additional information
 
 [SDK implementation guidance](./client-guidance.md).