diff --git a/graph/GuidelinesGraph.md b/graph/GuidelinesGraph.md
new file mode 100644
index 00000000..bc4a7006
--- /dev/null
+++ b/graph/GuidelinesGraph.md
@@ -0,0 +1,434 @@
+# Microsoft Graph REST API Guidelines
+
+Table of Contents
+
+- [Microsoft Graph REST API Guidelines](#microsoft-graph-rest-api-guidelines)
+ - [](#)
+ - [History](#history)
+ - [Introduction](#introduction)
+ - [Legend](#legend)
+ - [Design Approach](#design-approach)
+ - [Naming](#naming)
+ - [Uniform Resource Locators (URLs)](#uniform-resource-locators-urls)
+ - [Query Support](#query-support)
+ - [Resource Modeling Patterns](#resource-modeling-patterns)
+ - [Behavior Modeling](#behavior-modeling)
+ - [Error Handling](#error-handling)
+ - [API contract and non-backward compatible changes](#api-contract-and-non-backward-compatible-changes)
+ - [Versioning and Deprecation](#versioning-and-deprecation)
+ - [Recommended API Patterns](#recommended-api-patterns)
+ - [References](#references)
+
+##
+
+#### History
+
+| Date | Notes |
+|-------------|-----------------------------|
+| 2021-Sep-28 | Using summary and patterns style. |
+| 2020-Oct-04 | Initial version in Wiki. |
+
+## Introduction
+
+When building a digital ecosystem API usability becomes a business priority. Success of your ecosystem depends on APIs that are easy to discover, simple to use, fit for purpose, and consistent across your products.
+
+This document offers guidance that Microsoft Graph API producer teams MUST follow to
+ensure that Microsoft Graph has a consistent and easy to use API surface. A new API design should meet the
+following goals:
+
+\- Developer friendly via consistent naming, patterns, and web standards (HTTP,
+REST, JSON)
+
+\- Work well with SDKs in many programming languages.
+
+\- Sustainable & evolvable via clear API contracts.
+
+The Microsoft Graph guidelines are an extension of the Microsoft REST API
+guidelines. Readers are assumed also be reading and following the Microsoft REST API
+guidelines except where this document outlines specific differences or exceptions to those guidelines.
+Together these guidelines and a library of API patterns serve as the means by
+which API teams discuss and come to consensus on API review requirements.
+
+Technology and software are constantly changing and evolving, and as such, this
+is intended to be a living document. API guidelines that change frequently lead to an uneven and inconsistent API surface. Consequently, this document will more frequently change to add guidance in areas previously uncovered, or to clarify existing guidance. It will less frequently change the directional guidance it has already provided. [Open an
+issue](https://github.com/microsoft/api-guidelines/issues/new/choose) to suggest
+a change or propose a new idea.
+
+### Legend
+
+This document offers prescriptive guidance labeled as follows:
+
+:heavy_check_mark: **MUST** satisfy this specification.
+
+:no_entry: **MUST NOT** use this pattern.
+
+:ballot_box_with_check: **SHOULD** fulfill this specification.
+
+:warning: **SHOULD NOT** adopt this pattern.
+
+If not following these advices, you MUST disclose your reasons during the Graph API review.
+
+## Design Approach
+
+The design of your API is arguably the most important investment you will make. API design is what creates the first impression for developers when they discover and learn how to use your APIs. We promote API-first design approach where you begin your product design by focusing on how information will be exchanged and represented and creating an interface contract for your API which is followed by design and implementation of the backing service. This approach ensures decoupling of the interface from your implementation and is essential for agility, predictability, and reuse of your APIs. Established interface contract allows developers to use your API while internal teams are still working on implementation; API specifications enable designing of user experience and test cases in parallel. Starting with user-facing contracts also promotes a good understanding of system interactions, your modeling domain, and understanding of how the service will evolve. Microsoft Graph supports resource and query-based API styles which follow HTTP, REST, and JSON standards, where API contract is described using ODATA conventions and schema definition (see Documentation · OData - the Best Way to REST).
+[Documentation · OData - the Best Way to REST](https://www.odata.org/documentation/)).
+
+In general API design includes the following steps:
+
+- Outline the key current and future scenarios for API consumers
+
+- Define your domain model
+
+- Derive and name your API resources
+
+- Describe relationships between resources
+
+- Determine required behavior
+
+- Determine user roles and application permissions
+
+- Specify errors
+
+When creating your API contract you will define resources based on the domain model supporting your service and identify interactions based on user scenarios. Good API design goes beyond modeling the current state of resources and it is important to plan ahead how API evolves. For this it is essential to understand and document your user scenarios as the foundation of the API design. There is no one-to-one correspondence between domain model elements and API resources because you should simplify your customer facing APIs for better usability and to obfuscate implementation details. We recommend creating a simple resource diagram, like below, to show resources and their relationships and make it easier to reason about modeling choices and the shape of your API.
+
+
+After resources are defined it’s time to think about the behavior of your API which can be expressed via HTTP methods and operational resources such as functions and actions. As you think about API behavior you identify a happy path and various exceptions and deviations which will be expressed as errors and represented using HTTP codes and error messages.
+
+At every step of your design you need to consider security, privacy and compliance as intrinsic components of your API implementation.
+
+
+### Naming
+
+API resources are typically described by nouns. Resource and property names appear in API URLs and payloads and must be descriptive and easy to understand for developers. Ease of understanding comes from familiarity and recognition therefore when thinking about naming you should favor consistency with other Graph APIs, names in the product user interface, and industry standards. Microsoft Graph naming conventions follow [Microsoft REST API Guidelines](https://github.com/microsoft/api-guidelines/).
+
+Below is a short summary of the most often used conventions.
+
+| Requirements | Example |
+|---------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| :no_entry: **MUST NOT** use redundant words in names. |- **Right:** /places/{id}/**displayName** and /phones/{id}/**number**
- **Wrong** /places/{id}/*placeName* and /phones/{id}/**phoneNumber** |
+| :warning: **SHOULD NOT** use brand names in type or property names. | - **Right:** chat
- **Wrong** teamsChat |
+| :warning: **SHOULD NOT** use acronyms or abbreviations unless they are broadly understood. | - **Right:** url or htmlSignature
- **Wrong** msodsUrl or dlp |
+| :heavy_check_mark: **MUST** use singular nouns for type names. | - **Right:** address
- **Wrong** addresses |
+| :heavy_check_mark: **MUST** use plural nouns for collections (for listing a type or collection properties). | - **Right:** addresses
- **Wrong** address |
+| :ballot_box_with_check: **SHOULD** pluralize the noun even when followed by an adjective (a "postpositive"). | - **Right:** passersby or mothersInLaw
- **Wrong** notaryPublics or motherInLaws |
+| **casing** | |
+| :heavy_check_mark: **MUST** use lower camel case for *all* names and namespaces | - **Right:** automaticRepliesStatus.
- **Wrong** kebab-case or snake_case. |
+| :ballot_box_with_check: **SHOULD** case two-letter acronyms with the same case. | - **Right:** ioLimit or totalIOAmount
- **Wrong** iOLimit or totalIoAmount |
+| :ballot_box_with_check: **SHOULD** case three+ letter acronyms the same as a normal word. | - **Right:** fidoKey or oauthUrl
- **Wrong** webHTML |
+| :no_entry: **MUST NOT** capitalize the word following a [prefix](https://www.thoughtco.com/common-prefixes-in-english-1692724) or words within a [compound word](http://www.learningdifferences.com/Main%20Page/Topics/Compound%20Word%20Lists/Compound_Word_%20Lists_complete.htm). | - **Right:** subcategory, geocoordinate or crosswalk
- **Wrong** metaData, semiCircle or airPlane |
+| :heavy_check_mark: **MUST** capitalize within hyphenated and open (spaced) compound words. | - **Right:** fiveYearOld, daughterInLaw or postOffice
- **Wrong** paperclip or fullmoon |
+| **prefixes and suffixes** | |
+| :heavy_check_mark: **MUST** suffix date and time properties with | - **Right:** dueDate — an Edm.Date
- **Right:** createdDateTime — an Edm.DateTimeOffset
- **Right:** recurringMeetingTime — an Edm.TimeOfDay
- **Wrong** dueOn or startTime -
- **Right:** instead both above are an Edm.DateTimeOffset |
+| :ballot_box_with_check: **SHOULD** use the Duration type for durations, but if using an int, append the units. | - **Right:** passwordValidityPeriod — an Edm.Duration
- **Right:** passwordValidityPeriodInDays — an Edm.Int32 (NOTE use of Edm.Duration type is preferable)
- **Wrong** passwordValidityPeriod — an Edm.Int32 |
+| :no_entry: **MUST NOT** use suffix property names with primitive type names unless the type is temporal. | - **Right:** isEnabled or amount
- **Wrong** enabledBool |
+| :ballot_box_with_check: **SHOULD** prefix property names for properties concerning a different entity. | - **Right:** siteWebUrl on driveItem, or userId on auditActor
- **Wrong** webUrl on contact when its the companyWebUrl |
+| :ballot_box_with_check: **SHOULD** prefix Boolean properties with is, unless this leads to awkward or unnatural sounding names for Boolean properties. | - **Right:** isEnabled or isResourceAccount
- **Wrong** enabled or allowResourceAccount
- **Right:** allowNewTimeProposals or allowInvitesFrom — subjectively more natural than the examples below
- **Wrong** isNewTimeProposalsAllowed or isInvitesFromAllowed — subjectively more awkward that the examples above |
+| :no_entry: **MUST NOT** use 'collection', 'response', 'request ' suffixes . |- **Right:** addresses
- **Wrong** addressCollection |
+
+### Uniform Resource Locators (URLs)
+
+A Uniform Resource Locator (URL) is how developers access the resources of your
+API.
+
+Navigation paths to Microsoft Graph resources are generally broken into multiple
+segments:
+
+**{scheme}://{host}/{version}/{category}/[{pathSegment}][?{query}]** where
+
+- **scheme and host segments** are always
+ [https://graph.microsoft.com](https://graph.microsoft.com/v1.0/users);
+
+- **version** can be V1.0 or beta;
+
+- **category** segment is a logical grouping of APIs into top-level
+ categories;
+
+- **pathSegment** is one or many navigation segments which can address an entity,
+ collection of entities, property or operation available for an entity
+
+- **query string** must follow the OData standard for query representations
+ and is covered in [Query](#query) section of OData specifications.
+
+While HTTP defines no constraints on how different resources are related
+together, it does encourage the use of URL path segment hierarchies to convey
+relationships. In Microsoft Graph relationships between resources are
+supported by the OData concepts of singletons, entitySets, entities, complex
+types and navigation properties.
+
+In Microsoft Graph a top-level API category may represent one of the following
+groupings:
+
+1. A core *user-centric concept* of the Graph, i.e. /users, /groups or /me.
+
+2. A Microsoft *product or service offerings* covering multiple use cases, i.e. /teamwork, /directory.
+
+3. A *feature offering* covering a single use case and *shared* across multiple
+ Microsoft products, i.e. /search, /notifications, /subscriptions.
+
+4. *Administrative configuration* functions for specific products. i.e. /admin/exchange.
+
+5. Internal Microsoft requirements for publishing Privileged and Hidden APIs,
+ routing, and load testing, i.e./loadTestEntities.
+
+Effectively top-level categories define a perimeter for the API surface thus a
+new category creation requires additional rigor and governance approval.
+
+### Query Support
+
+Microsoft Graph APIs should support basic query options in conformance with
+OData specifications and [Microsoft REST API
+Guidelines](https://github.com/microsoft/api-guidelines/blob/master/Guidelines.md#7102-error-condition-responses).
+|Requirements|
+|----------------------------------------------------------------------------------------------------|
+| :heavy_check_mark: **MUST** support \$select on resource to enable properties projection |
+| :ballot_box_with_check: **SHOULD** support \$filter with eq, ne operations on properties of entities for collections|
+| :heavy_check_mark: **MUST** support [server-side pagination](http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html#sec_ServerDrivenPaging) using a [nextLink](http://docs.oasis-open.org/odata/odata-json-format/v4.01/odata-json-format-v4.01.html#sec_ControlInformationnextLinkodatanextL) for collections |
+| :ballot_box_with_check: **SHOULD** support pagination $top, $skip and $count for collections |
+| :ballot_box_with_check: **SHOULD** sorting with \$orderby both ascending and descending on properties of the entities |
+
+The query options part of an OData URL can be quite long, potentially exceeding
+the maximum length of URLs supported by components involved in transmitting or
+processing the request. One way to avoid this is to use the POST verb instead of
+GET with $query segment, and pass the query options part of the URL in the request body as described
+in the chapter [OData Query
+Options](http://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part2-url-conventions.html#sec_PassingQueryOptionsintheRequestBody).
+
+Another way is to use JSON batch as described in the [Microsoft Graph Documentation] (https://docs.microsoft.com/en-us/graph/json-batching#bypassing-url-length-limitations-with-batching).
+
+### Resource Modeling Patterns
+
+You can model structured resources for your APIs using OData Entity Type or Complex Type. The main difference between these types is that Entity type declares a key property to uniquely identify its objects and Complex Type does not. In Microsoft Graph this key property is called "id" for server-created key values. If there is a natural name for the key property then the workload can use that.
+Since objects of complex types on Graph don’t have unique identifiers, they are not directly addressable via URIs and therefore you must not use Complex Type to model addressable resources, such as individually addressable items within a collection, for more information refer to [Microsoft REST API Guidelines](https://github.com/microsoft/api-guidelines/blob/graph/Guidelines.md#93-collection-url-patterns). Complex types are better suited to represent composite properties of API entities.
+
+```XML
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+```
+| Microsoft Graph rules for modeling complex resources |
+|----------------------------------------------------------------------------------------|
+| :heavy_check_mark: **MUST** use String type for id |
+| :heavy_check_mark: **MUST** use a primary key composed of a single property |
+| :heavy_check_mark: **MUST** use an object as the root of all JSON payloads |
+| :heavy_check_mark: **MUST** use a root object with a value property to return a collection |
+| :heavy_check_mark: **MUST** include @odata.type annotations when the type is ambiguous |
+| :warning: **SHOULD NOT** add the property id to a complex type |
+
+There are different approaches for designing an API resource model in situations
+with multiple variants of a common concept. Type Hierarchy, Facets, and Flat bag
+of properties are three most often used patterns in Microsoft Graph today:
+
+- Type hierarchy is represented by one abstract base type with a few common
+ properties and one sub-type for each variant [Modelling with Subtypes
+ Pattern](./Modelling%20with%20Subtypes%20Pattern.md)
+
+- Facets 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 [Modelling with Facets
+ Pattern](./Modelling%20with%20Facets%20Pattern.md)
+
+- Flat bag of properties 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/meaningful for the variant given
+ by the type property. [Modelling with Flat Bag
+ Pattern](./Modelling%20with%20Flat%20Bag%20Pattern.md)
+
+The following table shows summary of main qualities for each pattern and will
+help to select a pattern fit for your use case.
+
+| API qualities\
Patterns | Properties and behavior
described in metadata | Supports combinations
of properties and behaviors | Simple query construction |
+|---------------------------------------------------|-------------------------------------|-----------------------------------|---------------------------|
+| Type hierarchy | yes | no | no |
+| Facets | partially | yes | yes |
+|Flat bag | no | no | yes |
+
+
+
+
+### Behavior Modeling
+
+The HTTP operations dictate how your API behaves. The URL of an API, along with
+its request/response bodies, establishes the overall contract that developers
+have with your service. As an API provider, how you manage the overall request /
+response pattern should be one of the first implementation decisions you make.
+APIs SHOULD use resource-based designs with standard HTTP methods rather than operation resources if possible.
+ Operation resources are either functions or actions. According to [ODATA standards]( http://docs.oasis-open.org/odata/odata/v4.0/errata03/os/complete/part3-csdl/odata-v4.0-errata03-os-part3-csdl-complete.html#_The_edm:Function_Element_2) a function represents an operation which returns a single instance or collection of instances of any type and doesn’t have an observable side effect. An action may have side effects and may return a result represented as a single entity or collection of any type.
+
+| Microsoft Graph rules for modeling behavior |
+|-----------------------------------------------------------------------------------------------------------------|
+| :heavy_check_mark: **MUST** use POST to create new entities in insertable entity sets or collections. This approach requires the server to produce system generated identities. |
+| :heavy_check_mark: **MUST** use PATCH to edit updatable resources |
+| :heavy_check_mark: **MUST** use DELETE to delete deletable resources |
+| :heavy_check_mark: **MUST** use GET for listing and reading resources. |
+| :warning: **SHOULD NOT** use PUT for updating resources. |
+| :ballot_box_with_check: **SHOULD** avoid using multiple round trips to complete a single logical operation. |
+
+
+Operation resources must have a binding parameter matching the type of the bound resource.
+In addition both actions and functions support overloading, meaning an API definition may contain multiple actions or functions with the same name.
+
+For a complete list of standard HTTP operations you can refer to the [Microsoft
+REST API Guidelines](https://github.com/microsoft/api-guidelines/blob/master/Guidelines.md#7102-error-condition-responses).
+
+### Error Handling
+
+Microsoft REST API Guidelines provide guidelines that Microsoft Graph APIs should
+follow when returning error condition responses. You can improve API traceability
+and consistency by using recommended Graph error model and the Graph Utilities library to provide a standard implementation for your service :
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+{
+"error": {
+ "code": "BadRequest",
+ "message": "Cannot process the request because a required field is missing.",
+ "target": "query",
+ "innererror": {
+ "code": "RequiredFieldMissing",
+
+ }
+ }
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The top-level error code must be aligned with HTTP response status codes according to [rfc7231 (ietf.org)](https://datatracker.ietf.org/doc/html/rfc7231#section-6).
+The following examples demonstrate error modeling for common use cases:
+
+- **Simple error**: An API wants to report an error with top-level details
+ only. Then the error object contains the top-level error code, message and
+ target (optional).
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+{
+ "error": {
+ "code": "BadRequest",
+ "message": "Cannot process the request because it is malformed or incorrect.",
+ "target": "Resource X (Optional)"
+ }
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- **Detailed error**: An API needs to provide service-specific details of the
+ error via the innererror property of the error object. It is intended to allow
+ services to supply a specific error code to help differentiate errors that
+ share the same top-level error code but reported for different reasons.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+{
+ "error": {
+ "code": "BadRequest",
+ "message": "Cannot process the request because it is malformed or incorrect.",
+ "innererror": {
+ "code": "requiredFieldOrParameterMissing",
+
+ }
+ }
+}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+| Microsoft Graph enforces the following error rules |
+|-----------------------------------------------------------------------------------------------------------------------|
+| :heavy_check_mark: **MUST** return an error property with a child code property in all error responses. |
+| :heavy_check_mark: **MUST** return a 403 Forbidden error when the application or signed-in user have insufficient permissions are present in the auth token. |
+| :heavy_check_mark: **MUST** return a 429 Too Many Requests error when client exceeded throttling limits and 503 Service Unavailable when service overloaded but client is within throttling limits.|
+| :ballot_box_with_check: **SHOULD** return a 404 Not Found error if a 403 would result in information disclosure. |
+
+For a complete mapping of error codes to HTTP statuses you can refer to the
+[rfc7231 (ietf.org)](https://datatracker.ietf.org/doc/html/rfc7231#section-6).
+
+## API contract and non-backward compatible changes
+
+Microsoft Graph definition of breaking changes is based on the [Microsoft REST
+API
+Guidelines](https://github.com/microsoft/api-guidelines/blob/graph/Guidelines.md#123-definition-of-a-breaking-change).
+In general, making all but additive changes to the API contract for existing elements is
+considered breaking. Adding new elements is allowed and not considered a
+breaking change.
+
+\*\* Non-breaking changes:\*\*
+
+
+- Addition of properties that are nullable or have a default value
+- Addition of a member, after the sentinel member, to an evolvable enumeration
+- Removal, rename, or change to the type of an annotation
+- Changes to the order of properties
+- Changes to the length or format of opaque strings, such as resource IDs
+- Addition or removal of an annotation OpenType="true"
+
+\*\* Breaking changes:\*\*
+
+- Changes to the URL or fundamental request/response associated with a
+ resource
+- Removal, rename, or change to an incompatible type of a declared property
+- Removal or rename of APIs or API parameters
+- Addition of a required request header
+- Addition of a EnumType members for non-evolvable enumerations
+- Addition of a Nullable="false" properties to existing types
+- Addition of a parameter not marked as [Nullable](http://docs.oasis-open.org/odata/odata-csdl-xml/v4.01/odata-csdl-xml-v4.01.html#sec_Nullable) to existing actions
+- Addition of a parameter not marked as [Optional](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#OptionalParameter) to an existing function
+- Changes to top-level error codes
+- Introduction of server-side pagination to existing collections
+- Significant changes to the performance of APIs such as increased latency, rate limits or concurrency.
+
+
+
+### Versioning and Deprecation
+As the market and technology evolves your APIs will require modifications in this case you must avoid breaking changes and add new resources and features incrementally. If that is not possible then you must version elements of your APIs.
+Microsoft Graph allows versioning of elements including entities and properties. Versioning involves adding a new, uniquely named version of the element and marking the old version as deprecated.
+
+In some cases, there will be a natural new name for the element. In other cases, where the original name is still the most descriptive, the suffix _v2 can be added to the original name to make it unique.
+The original element is then marked as deprecated using annotations.
+
+Microsoft Graph provides two public endpoints to support API lifecycle:
+1. API sets on the v1.0 endpoint (https://graph.microsoft.com/v1.0) are in general availability (GA) status.
+2. API sets on the beta endpoint (https://graph.microsoft.com/beta) are in beta or private preview status.
+
+Microsoft Graph APIs in the GA version guarantee API stability and consistency for its clients. If your API requires a breaking change in GA, then you MUST create new element versions and support deprecated elements for a minimum of 36 months or 24 months with demonstrated non-usage.
+On the beta endpoint breaking changes and deprecation of APIs are allowed with consideration of dependencies and customer impact. It is best practice to test new element versions on the beta endpoint at first then promote API changes to the GA endpoint.
+Detailed requirements for versioning and deprecation are described in the [Deprecation guidelines](./deprecation.md).
+
+
+## Recommended API Patterns
+
+The guidelines in previous sections are intentionally brief and provide a jump
+start for Graph API developers. More detailed design guidance on REST APIs is
+published at the [Microsoft REST API
+Guidelines](https://github.com/microsoft/api-guidelines/) and Graph specific
+patterns are outlined in the table below.
+
+Recommended API Design patterns:
+
+| Pattern | Description | Reference |
+|-------------------------|------------------------------------------------------------------------------------------------|----------------------------------------------------------------------|
+| Type Hierarchy | The ability to model is-a relationships using subtypes. | [Subtypes](./patterns/Modelling%20with%20Subtypes%20Pattern.md) |
+| Facets | The ability to model parent-child relationships using Facet pattern. | [Facets](./patterns/Modelling%20with%20Subtypes%20Pattern.md) |
+| Dictionary | The ability for clients to provide an unknown quantity of data elements of the same type. | [Dictionary](./patterns/dictionary.md) |
+
+ |
+
+
+## References
+
+- [Microsoft REST API
+ Guidelines](https://github.com/microsoft/api-guidelines/)
+
+- [OData Guidelines](http://www.odata.org/documentation/)
+
+- [RESTful web API
+ design](https://docs.microsoft.com/en-us/azure/architecture/best-practices/api-design)
+
+- [Microsoft Graph
+ Documentation](https://developer.microsoft.com/en-us/graph/docs/concepts/overview)
+
+- [Microsoft Graph Explorer](https://aka.ms/ge)
diff --git a/graph/ModelExample.png b/graph/ModelExample.png
new file mode 100644
index 00000000..450f4f87
Binary files /dev/null and b/graph/ModelExample.png differ
diff --git a/graph/SummaryOfGraphDeltas.md b/graph/SummaryOfGraphDeltas.md
new file mode 100644
index 00000000..32c27230
--- /dev/null
+++ b/graph/SummaryOfGraphDeltas.md
@@ -0,0 +1,216 @@
+# Graph API Design API Patterns
+
+## Introduction
+
+The Graph REST API guidelines are an extension of the [Microsoft REST API guidelines](../guidelines). Readers of this document are assumed to be also reading the [Microsoft REST API guidelines](../guidelines) and be familiar with them. Graph guidance is a superset of the Microsoft API guidelines and services should follow them *except* where this document outlines specific differences or exceptions to those guidelines. This document does contain additional Graph-specific guidance and additional details.
+
+The following table of contents links back to the primary guidelines where there are no differences in Graph guidelines. Where differences exist, the section heading is **bold**.
+
+## 2. Table of contents
+
+
+- [Microsoft REST API Guidelines Working Group](../Guidelines.md#microsoft-rest-api-guidelines-working-group)
+- [1. Abstract](../Guidelines.md#1-abstract)
+- [2. Table of contents](../Guidelines.md#2-table-of-contents)
+- [3. Introduction](../Guidelines.md#3-introduction)
+ - [3.1. Recommended reading](../Guidelines.md#31-recommended-reading)
+- [4. Interpreting the guidelines](../Guidelines.md#4-interpreting-the-guidelines)
+ - [4.1. Application of the guidelines](../Guidelines.md#41-application-of-the-guidelines)
+ - [4.2. Guidelines for existing services and versioning of services](../Guidelines.md#42-guidelines-for-existing-services-and-versioning-of-services)
+ - [4.3. Requirements language](../Guidelines.md#43-requirements-language)
+ - [4.4. License](../Guidelines.md#44-license)
+- [5. Taxonomy](../Guidelines.md#5-taxonomy)
+ - [5.1. Errors](../Guidelines.md#51-errors)
+ - [5.2. Faults](../Guidelines.md#52-faults)
+ - [5.3. Latency](../Guidelines.md#53-latency)
+ - [5.4. Time to complete](../Guidelines.md#54-time-to-complete)
+ - [5.5. Long running API faults](../Guidelines.md#55-long-running-api-faults)
+- [6. Client guidance](../Guidelines.md#6-client-guidance)
+ - [6.1. Ignore rule](../Guidelines.md#61-ignore-rule)
+ - [6.2. Variable order rule](../Guidelines.md#62-variable-order-rule)
+ - [6.3. Silent fail rule](../Guidelines.md#63-silent-fail-rule)
+- [7. Consistency fundamentals](../Guidelines.md#7-consistency-fundamentals)
+ - [7.1. URL structure](../Guidelines.md#71-url-structure)
+ - [7.2. URL length](../Guidelines.md#72-url-length)
+ - [7.3. Canonical identifier](../Guidelines.md#73-canonical-identifier)
+ - [7.4. Supported methods](../Guidelines.md#74-supported-methods)
+ - [7.4.1. POST](../Guidelines.md#741-post)
+ - [7.4.2. PATCH](../Guidelines.md#742-patch)
+ - [7.4.3. Creating resources via PATCH (UPSERT semantics)](../Guidelines.md#743-creating-resources-via-patch-upsert-semantics)
+ - [7.4.4. Options and link headers](../Guidelines.md#744-options-and-link-headers)
+ - [7.5. Standard request headers](../Guidelines.md#75-standard-request-headers)
+ - [7.6. Standard response headers](../Guidelines.md#76-standard-response-headers)
+ - [7.7. Custom headers](../Guidelines.md#77-custom-headers)
+ - [7.8. Specifying headers as query parameters](../Guidelines.md#78-specifying-headers-as-query-parameters)
+ - [7.9. PII parameters](../Guidelines.md#79-pii-parameters)
+ - [7.10. Response formats](../Guidelines.md#710-response-formats)
+ - [7.10.1. Clients-specified response format](../Guidelines.md#7101-clients-specified-response-format)
+ - [7.10.2. Error condition responses](../Guidelines.md#7102-error-condition-responses)
+ - [7.11. HTTP Status Codes](../Guidelines.md#711-http-status-codes)
+ - [7.12. Client library optional](../Guidelines.md#712-client-library-optional)
+- [8. CORS](../Guidelines.md#8-cors)
+ - [8.1. Client guidance](../Guidelines.md#81-client-guidance)
+ - [8.1.1. Avoiding preflight](../Guidelines.md#811-avoiding-preflight)
+ - [8.2. Service guidance](../Guidelines.md#82-service-guidance)
+- [9. Collections](../Guidelines.md#9-collections)
+ - [9.1. Item keys](../Guidelines.md#91-item-keys)
+ - [9.2. Serialization](../Guidelines.md#92-serialization)
+ - [9.3. Collection URL patterns](../Guidelines.md#93-collection-url-patterns)
+ - [9.3.1. Nested collections and properties](../Guidelines.md#931-nested-collections-and-properties)
+ - [9.4. Big collections](../Guidelines.md#94-big-collections)
+ - [9.5. Changing collections](../Guidelines.md#95-changing-collections)
+ - [9.6. Sorting collections](../Guidelines.md#96-sorting-collections)
+ - [9.6.1. Interpreting a sorting expression](../Guidelines.md#961-interpreting-a-sorting-expression)
+ - [9.7. Filtering](../Guidelines.md#97-filtering)
+ - [9.7.1. Filter operations](../Guidelines.md#971-filter-operations)
+ - [9.7.2. Operator examples](../Guidelines.md#972-operator-examples)
+ - [9.7.3. Operator precedence](../Guidelines.md#973-operator-precedence)
+ - [9.8. Pagination](../Guidelines.md#98-pagination)
+ - [9.8.1. Server-driven paging](../Guidelines.md#981-server-driven-paging)
+ - [9.8.2. Client-driven paging](../Guidelines.md#982-client-driven-paging)
+ - [9.8.3. Additional considerations](../Guidelines.md#983-additional-considerations)
+ - [9.9. Compound collection operations](../Guidelines.md#99-compound-collection-operations)
+- [**9a. Resource Design**](#9a-resource-design)
+ - [**9a.1. Noun Resources**](#9a1-noun-resources)
+ - [**9a.2. Verb Resources**](#9a2-verb-resources)
+ - [**9a.3. Resource Modeling**](#9a3-resource-modeling)
+- [10. Delta queries](#10-delta-queries)
+ - [10.1. Delta links](../Guidelines.md#101-delta-links)
+ - [10.2. Entity representation](../Guidelines.md#102-entity-representation)
+ - [10.3. Obtaining a delta link](../Guidelines.md#103-obtaining-a-delta-link)
+ - [10.4. Contents of a delta link response](../Guidelines.md#104-contents-of-a-delta-link-response)
+ - [10.5. Using a delta link](../Guidelines.md#105-using-a-delta-link)
+- [11. JSON standardizations](../Guidelines.md#11-json-standardizations)
+ - [11.1. JSON formatting standardization for primitive types](../Guidelines.md#111-json-formatting-standardization-for-primitive-types)
+ - [11.2. Guidelines for dates and times](../Guidelines.md#112-guidelines-for-dates-and-times)
+ - [11.2.1. Producing dates](../Guidelines.md#1121-producing-dates)
+ - [11.2.2. Consuming dates](../Guidelines.md#1122-consuming-dates)
+ - [11.2.3. Compatibility](../Guidelines.md#1123-compatibility)
+ - [11.3. JSON serialization of dates and times](../Guidelines.md#113-json-serialization-of-dates-and-times)
+ - [11.3.1. The `DateLiteral` format](../Guidelines.md#1131-the-dateliteral-format)
+ - [11.3.2. Commentary on date formatting](../Guidelines.md#1132-commentary-on-date-formatting)
+ - [11.4. Durations](../Guidelines.md#114-durations)
+ - [11.5. Intervals](../Guidelines.md#115-intervals)
+ - [11.6. Repeating intervals](../Guidelines.md#116-repeating-intervals)
+ - [**11.7. Evolvable Enums**](#117-evolvable-enums)
+ - [**11.8. Dictionary Types**](#118-dictionary-types)
+ - [**11.9. Ommitted Properties**](#119-ommitted-properties)
+- [12. Versioning](../Guidelines.md#12-versioning)
+ - [12.1. Versioning formats](../Guidelines.md#121-versioning-formats)
+ - [12.1.1. Group versioning](../Guidelines.md#1211-group-versioning)
+ - [12.2. When to version](../Guidelines.md#122-when-to-version)
+ - [12.3. Definition of a breaking change](../Guidelines.md#123-definition-of-a-breaking-change)
+- [**13. Long running operations**](#13-long-running-operations)
+ - [**13.1. Resource based long running operations (RELO)**](../long-running-operations.md#131-resource-based-long-running-operations-relo)
+ - [**13.2. Stepwise long running operations**](../long-running-operations.md#132-stepwise-long-running-operations)
+ - [13.2.1. PUT](../Guidelines.md#1321-put)
+ - [13.2.2. POST](../Guidelines.md#1322-post)
+ - [13.2.3. POST, hybrid model](../Guidelines.md#1323-post-hybrid-model)
+ - [13.2.4. Operations resource](../Guidelines.md#1324-operations-resource)
+ - [13.2.5. Operation resource](../Guidelines.md#1325-operation-resource)
+ - [13.2.6. Operation tombstones](../Guidelines.md#1326-operation-tombstones)
+ - [13.2.7. The typical flow, polling](../Guidelines.md#1327-the-typical-flow-polling)
+ - [13.2.8. The typical flow, push notifications](../Guidelines.md#1328-the-typical-flow-push-notifications)
+ - [13.2.9. Retry-After](../Guidelines.md#1329-retry-after)
+ - [13.3. Retention policy for operation results](../Guidelines.md#133-retention-policy-for-operation-results)
+- [14. Throttling, Quotas, and Limits](../Guidelines.md#14-throttling-quotas-and-limits)
+ - [14.1. Principles](../Guidelines.md#141-principles)
+ - [14.2. Return Codes (429 vs 503)](../Guidelines.md#142-return-codes-429-vs-503)
+ - [14.3. Retry-After and RateLimit Headers](../Guidelines.md#143-retry-after-and-ratelimit-headers)
+ - [14.4. Service Guidance](../Guidelines.md#144-service-guidance)
+ - [14.4.1. Responsiveness](../Guidelines.md#1441-responsiveness)
+ - [14.4.2. Rate Limits and Quotas](../Guidelines.md#1442-rate-limits-and-quotas)
+ - [14.4.3. Overloaded services](../Guidelines.md#1443-overloaded-services)
+ - [14.4.4. Example Response](../Guidelines.md#1444-example-response)
+ - [14.5. Caller Guidance](../Guidelines.md#145-caller-guidance)
+ - [14.6. Handling callers that ignore Retry-After headers](../Guidelines.md#146-handling-callers-that-ignore-retry-after-headers)
+- [**15. Push notifications via webhooks**](#15-push-notifications-via-webhooks)
+ - [15.1. Scope](../Guidelines.md#151-scope)
+ - [15.2. Principles](../Guidelines.md#152-principles)
+ - [15.3. Types of subscriptions](../Guidelines.md#153-types-of-subscriptions)
+ - [15.4. Call sequences](../Guidelines.md#154-call-sequences)
+ - [15.5. Verifying subscriptions](../Guidelines.md#155-verifying-subscriptions)
+ - [15.6. Receiving notifications](../Guidelines.md#156-receiving-notifications)
+ - [15.6.1. Notification payload](../Guidelines.md#1561-notification-payload)
+ - [15.7. Managing subscriptions programmatically](../Guidelines.md#157-managing-subscriptions-programmatically)
+ - [15.7.1. Creating subscriptions](../Guidelines.md#1571-creating-subscriptions)
+ - [15.7.2. Updating subscriptions](../Guidelines.md#1572-updating-subscriptions)
+ - [15.7.3. Deleting subscriptions](../Guidelines.md#1573-deleting-subscriptions)
+ - [15.7.4. Enumerating subscriptions](../Guidelines.md#1574-enumerating-subscriptions)
+ - [15.8. Security](../Guidelines.md#158-security)
+- [16. Unsupported requests](../Guidelines.md#16-unsupported-requests)
+ - [16.1. Essential guidance](../Guidelines.md#161-essential-guidance)
+ - [16.2. Feature allow list](../Guidelines.md#162-feature-allow-list)
+ - [16.2.1. Error response](../Guidelines.md#1621-error-response)
+- [17. Naming guidelines](../Guidelines.md#17-naming-guidelines)
+ - [17.1. Approach](../Guidelines.md#171-approach)
+ - [17.2. Casing](../Guidelines.md#172-casing)
+ - [17.3. Names to avoid](../Guidelines.md#173-names-to-avoid)
+ - [17.4. Forming compound names](../Guidelines.md#174-forming-compound-names)
+ - [17.5. Identity properties](../Guidelines.md#175-identity-properties)
+ - [17.6. Date and time properties](../Guidelines.md#176-date-and-time-properties)
+ - [17.7. Name properties](../Guidelines.md#177-name-properties)
+ - [17.8. Collections and counts](../Guidelines.md#178-collections-and-counts)
+ - [17.9. Common property names](../Guidelines.md#179-common-property-names)
+ - [**17.10. Type namespaces**](#1710-type-namespaces)
+- [18. Appendix](../Guidelines.md#18-appendix)
+ - [18.1. Sequence diagram notes](../Guidelines.md#181-sequence-diagram-notes)
+ - [18.1.1. Push notifications, per user flow](../Guidelines.md#1811-push-notifications-per-user-flow)
+ - [18.1.2. Push notifications, firehose flow](../Guidelines.md#1812-push-notifications-firehose-flow)
+ - [**18.2. Additional resources**](#182-additional-resources)
+
+
+
+## Summaries of the deltas in the Microsoft Graph Design Guidelines
+
+### 9a. Resource Design
+
+#### 9a.1. Noun Resources
+
+While HTTP defines no constraints on how different resources are related together, it does encourage the use of URL path segment hierarchies to convey a relationship. In addition to the hierarchy of resources, there are also lifetime relationships between resources, the notions of [singletons, entitySets, entities, complex types and navigation properties](entity-complex) make it possible to define a set of lifetime relationships between resources.
+
+#### 9a.2. Verb Resources
+
+Noun-based resources are not always the best fit for meeting the requirements of a client. There are read-only and write scenarios where a resource can be used to represent some kind of data processing operation. The terms [function and action](Functions-and-actions) are used to identify read and write operation style resources, respectively.
+
+#### 9a.3. Resource Modeling
+
+There are a number of principles to be aware of when modeling resources for Microsoft Graph. [Modeling variants](modeling-variants) is important when resources have have a subset of common properties and behavior.
+
+### 10. Deltas
+
+The ability to track changes (pull) occuring in the data exposed by Microsoft Graph. This is addressed implementing [change tracking (aka delta query)](deltas).
+
+### 11.7. Evolvable Enums
+
+[Evolvable enums](evolvable-enums) enable the use of enumerations that can add new values over time without breaking clients applications.
+
+### 11.8. Dictionary Types
+
+For scenarios where there is a need to persist a variable number of properties, a [dictionary type](./dictionary/index.md) may be useful.
+
+### 11.9. Omitting Properties
+
+For scenarios where the server contains business logic that determines if a property value should be returned, or not, to the client, a returned representation can be annotated to indicate where properties are [omitted](ommitting-properties).
+
+### 13. Long running operations
+
+Long running operations are mostly unchanged. The most significant difference is that instead of using `Operation-Location` as the header to point to the Operation, the use of the standard `Location` header is recommended. In hybrid scenarios, a `Content-Location` header can be used to indicate the URL of the created resource and the 202 response can contain a payload. Details of the diffences are described in detail in the [Long Running Operations](long-running-operations) document.
+
+### 15. Push notifications via webHooks
+
+To determine how the Graph docs differ than the Microsoft REST API Guidelines.
+The ability to get notified (push) when a change occurs in the data exposed by Microsoft Graph. This is addressed implementing [change notifications (aka webhooks)](webhooks).
+
+### 17.10. Type Namespaces
+
+Microsoft Graph model types can be declared within a [type namespaces](type-namespaces) to reduce the need to prefix types with a qualifier to ensure uniqueness.
+
+### 18.2. Additional resources
+
+The links below provide a set of rules to think through as you design your API.
+
+- [Microsoft REST API Guidelines](https://github.com/microsoft/api-guidelines/)
+- [OData Guidelines](http://www.odata.org/documentation/)
+- [Microsoft Graph Documentation](https://developer.microsoft.com/en-us/graph/docs/concepts/overview)
+- [Microsoft Graph Explorer](https://aka.ms/ge)
diff --git a/graph/deprecation.md b/graph/deprecation.md
new file mode 100644
index 00000000..cc818b9b
--- /dev/null
+++ b/graph/deprecation.md
@@ -0,0 +1,47 @@
+### Deprecation Guidelines
+
+If your API requires the introduction of breaking changes you must add Revisions annotations to the API definition with the following terms:
+
+
+ - Date: Date when the element was marked as deprecated.
+ - Version: Used to organize the ChangeLog. Use the format "YYYY-MM/Category" where "YYYY-MM" is the month the deprecation is announced, and "Category" is the category under which the change is described.
+ - Kind: Deprecated -
+ - Description: Human readable description of the change: Used in changelog, documentation etc.
+ - RemovalDate: Earliest date when the element may be removed.
+
+The annotation can be applied to a type, an entity set, a singleton,a property, a
+navigation property, a function or an action. If a type is marked as deprecated, it
+is not necessary to mark the members of that type as deprecated, nor is it necessary
+to annotate any usages of that type.
+
+**Example of property annotation:**
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+
+
+
+
+
+
+
+
+
+
+ ...
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When the request URL contains a reference to a deprecated model element, the gateway will add a [Deprecation
+header](https://tools.ietf.org/html/draft-dalal-deprecation-header-02) (with the
+date the element was marked as deprecated) and a Sunset header (with the date of 2
+years beyond the Deprecation date) to the response.
+
+**Deprecation header example:**
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Deprecation: Wed, 30 Mar 2022 11:59:59 GMT
+Sunset: Thursday, 30 June 2024 23:59:59 GMT
+Link: https://docs.microsoft.com/en-us/graph/changelog#2022-03-30_name ; rel="deprecation"; type="text/html"; title="name",https://docs.microsoft.com/en-us/graph/changelog#2022-03-30_state ; rel="deprecation"; type="text/html"; title="state"
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/graph/patterns/PatternDescriptionTemplate.md b/graph/patterns/PatternDescriptionTemplate.md
new file mode 100644
index 00000000..236aa2ff
--- /dev/null
+++ b/graph/patterns/PatternDescriptionTemplate.md
@@ -0,0 +1,50 @@
+# Pattern Name
+
+Microsoft Graph API Design Pattern
+
+
+
+### *Provide a short description of the pattern.*
+
+
+
+## Problem
+--------
+*Describe business context relevant for the pattern.*
+*Provide a short description of the problem.*
+
+* *
+
+## Solution
+--------
+
+*Describe how to implement the solution to solve the problem.*
+*Describe related patterns.*
+
+* *
+
+## When to Use this Pattern
+------------------------
+
+*Describe when and why the solution is applicable and when it may not.*
+
+* *
+
+## Issues and Considerations
+-------------------------
+
+*Describe tradeoffs of the solution.*
+
+
+* *
+
+## Example
+-------
+
+*Provide a short example from real life*
+
+* *
+
+
+
+
diff --git a/graph/dictionary/client-guidance.md b/graph/patterns/dictionary-client-guidance.md
similarity index 96%
rename from graph/dictionary/client-guidance.md
rename to graph/patterns/dictionary-client-guidance.md
index 58829e47..648f1385 100644
--- a/graph/dictionary/client-guidance.md
+++ b/graph/patterns/dictionary-client-guidance.md
@@ -1,5 +1,7 @@
# Dictionary types
+Note: this document is to be moved into a central client guidance document in the future.
+
The client guidance is a collection of additional information provided to SDK implementers and client applications. This information is meant to help understand how various guidelines and concept translate in their world and clarify a few unknowns. You should always read the corresponding guideline first to get a context understanding.
[Read the guideline](./index.md).
diff --git a/graph/dictionary/index.md b/graph/patterns/dictionary.md
similarity index 66%
rename from graph/dictionary/index.md
rename to graph/patterns/dictionary.md
index dd3dfa24..0a797d5d 100644
--- a/graph/dictionary/index.md
+++ b/graph/patterns/dictionary.md
@@ -1,26 +1,56 @@
-# 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 data elements of the same type that must 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 entries 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:
- The data values MUST be related to one another semantically as a collection.
- The value types MUST be a primitive type or is a **ComplexType**. Mixed primitive types are not allowed.
-- The client MUST define the keys of this type. As opposed to the service defining it in advance.
+- The client MUST define the keys of this type. As opposed to the service defining them in advance.
-### Alternatives to consider
+### Alternatives
- [Open extensions](https://docs.microsoft.com/en-us/graph/extensibility-open-users) when you want to provide clients the ability to extend Microsoft Graph.
-- [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 omitted for brevity.
@@ -38,11 +68,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 +86,7 @@ Response:
}
```
-### Getting the dictionary
+#### Getting the dictionary
```HTTP
GET https://graph.microsoft.com/v1.0/users/10/roles
@@ -78,7 +108,7 @@ Response:
}
```
-### Getting the entity with the dictionary
+#### Getting the entity with the dictionary
```HTTP
GET https://graph.microsoft.com/v1.0/users/10
@@ -104,7 +134,7 @@ Response:
}
```
-### 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 +144,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 +167,7 @@ PATCH https://graph.microsoft.com/v1.0/users/10/roles
> Note: the domain values for the existing author and maintainer entries will get updated.
> 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 +177,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 +212,6 @@ The following example defines a complex type **roleSettings** as well as a dicti
```
-## Additional information
+### Additional information
[SDK implementation guidance](./client-guidance.md).
diff --git a/graph/patterns/facets.md b/graph/patterns/facets.md
new file mode 100644
index 00000000..2ed85ccd
--- /dev/null
+++ b/graph/patterns/facets.md
@@ -0,0 +1,111 @@
+# Facets Pattern
+
+Microsoft Graph API Design Pattern
+
+### *A frequent pattern in Microsoft Graph is to model multiple variants of a common concept as a single entity type with common properties and facets for variants.*
+
+
+## Problem
+API designer needs to model a set of heterogeneous resources that have common properties and behaviors, and may express features of multiple variants at a time because variants are not mutually exclusive.
+For example a movie clip stored on OneDrive is both a file and a video. There are properties associated to each variant.
+
+## Solution
+
+API designers create multiple complex types to bundle properties for each variant then define an entity type with a property for each complex type to hold the properties of the variant.
+In this solution a child variant is identified by a presence of one or more facets in the parent object.
+
+## Issues and Considerations
+
+When introducing a new facet, you need to ensure that the new facet doesn't change the semantic of the model with it's implicit constraints.
+
+
+## When to Use this Pattern
+
+The facet pattern is useful when there is a number of variants and they are not mutually exclusive. It also makes syntactically easier to query resources using OData $filter expression since it doesn't require casting.
+
+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).
+
+## Example
+The driveItem resource represents a file, folder,image or other item stored in a drive and is modeled using entity type with multiple facets.
+
+```XML
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ...
+
+```
+
+API request to get all items from a personal OneDrive will return a heterogenous collection with different facets populated. In the example below 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
+
+Response shortened for readability:
+
+ "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('93816c1c-1b19-41de-a322-a1643d7f4d39')/drive/root/children",
+ "value": [
+ {
+ "createdDateTime": "2021-07-07T13:59:47Z",
+ "name": "Microsoft Teams Chat Files",
+ ...,
+ "folder": {
+ "childCount": 15
+ }
+ },
+ ...
+ {
+ "createdDateTime": "2021-12-15T00:07:36Z",
+ "name": "Versioning and Deprecation.docx",
+ ...,
+ "file": {
+ "mimeType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+ "hashes": {
+ "quickXorHash": "r2d9uZilW0zEIXwycymsUQzhV+U="
+ }
+ },
+ ...
+ },
+ {
+ "createdDateTime": "2021-12-21T16:32:51Z",
+ "name": "WhaleShark.jpg",
+ ...
+ "file": {
+ "mimeType": "image/jpeg",
+ "hashes": {
+ "quickXorHash": "2vHpAA7RDZJteIwl1pXR980xuh4="
+ }
+ },
+ ...,
+ "image": {}
+ }
+ ]
+```
diff --git a/graph/patterns/subtypes.md b/graph/patterns/subtypes.md
new file mode 100644
index 00000000..73dea0a2
--- /dev/null
+++ b/graph/patterns/subtypes.md
@@ -0,0 +1,138 @@
+# Type Hierarchy
+
+Microsoft Graph API Design Pattern
+
+
+### *A frequent pattern in Microsoft Graph is to have a small type hierarchy, a base type with a few subtypes. This allows us to model collections of objects that have slightly different metadata and behavior.*
+
+## Problem
+
+The API design requires to model a set of entities based on a common concept
+that can be further grouped into **mutually exclusive variants** with specific
+properties and behaviors. The API design should be evolvable and allow addition
+of new variants without breaking changes.
+
+## Solution
+
+API designers can use OData **type hierarchy**, where there is one abstract base
+type with a few shared properties representing the common concept and one
+sub-type for each variant of the entity. In hierarchy, the interdependencies of properties, i.e. which properties are relevant for which variants, is fully captured in metadata and client code can potentially leverage that to construct and/or validate requests.
+
+## Issues and Considerations
+
+When introducing a new subtype to the hierarchy, developers need to ensure that
+the new subtype doesn't change the semantic of the type hierarchy with its
+implicit constraints.
+To retrieve properties specific for a derived type an API request URL may need to include casting to the derived type. If type hierarchy is very deep then resulting URL may become very long and not easily readable.
+
+There are a few consideration to take into account when new sub-types
+are introduced:
+
+- TODO add something about SDK dependencies and required actions
+- TODO Client libraries for strongly typed language might ignore some of the values
+ in the @odata.type property without further configuration and need to be
+ updated to be able to pick the right (client) type to deserialize into.
+- In the case of public APIs in GA versions clients may develop their applications to support exclusively the current set of subtypes and don’t expect new variations. To mitigate the risk of clients disruption, when introducing a new subtype, allow ample time for communication and rollout.
+
+
+
+## When to Use this Pattern
+
+The Type hierarchy pattern is well suited to use case where each variant of a
+common concept has unique properties and behaviors, no combinations of variants
+is anticipated, API queries are managed programmatically with type casting.
+
+There are related patterns to consider such as
+[Facets](https://github.com/microsoft/api-guidelines/tree/graph/graph) and [Flat
+bag of
+properties](https://github.com/microsoft/api-guidelines/tree/graph/graph).
+
+## Example
+
+The directoryObject type is the main abstraction for many directory
+types such as users, organizational contacts, devices, service principals
+and groups stored in Azure Active Directory. Since any a directoryObject object is a unique entity, the directoryObject type itself is derived from the graph.entity base type.
+
+```XML
+
+
+
+
+
+
+
+
+
+```
+
+
+Groups and users are derived types and modeled as
+
+```XML
+
+
+
+
+…
+
+```
+
+API request to get members of a group returns a heterogeneous collection of
+users and groups where each element can be a user or a group, and has an
+additional property @odata.type for a variant subtype:
+
+```
+GET https://graph.microsoft.com/v1.0/groups/a94a666e-0367-412e-b96e-54d28b73b2db/members?$select=id,displayName
+
+Response payload shortened for readability:
+
+{
+ "@odata.context":
+"https://graph.microsoft.com/v1.0/\$metadata\#directoryObjects",
+ "value": [
+ {
+ "@odata.type": "#microsoft.graph.user",
+ "id": "37ca648a-a007-4eef-81d7-1127d9be34e8",
+ "displayName": "John Cob"
+ },
+ {
+ "@odata.type": "#microsoft.graph.group",
+ "id": "45f25951-d04f-4c44-b9b0-2a79e915658d",
+ "displayName": "Department 456"
+ },
+ ...
+ ]
+}
+```
+API request for a subtype specific property requires type casting to the subtype, i.e. to retrieve jobTitle property, enabled for the user type, you need to cast from the directoryObject collection items to the microsoft.graph.group derived type.
+
+```
+GET https://graph.microsoft.com/v1.0/groups/a94a666e-0367-412e-b96e-54d28b73b2db/members/microsoft.graph.user?$select=displayName,jobTitle
+
+Response payload shortened for readability:
+
+{
+ "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users(displayName,jobTitle)",
+ "value": [
+ {
+ "displayName": "John Cob",
+ "jobTitle": "RESEARCHER II"
+ },
+ ...
+ ]
+}
+```
+API request to create a subtype object in a polymorphic collection requires "@odata.type" specified in the request body.
+```
+POST https://graph.microsoft.com/v1.0/directoryObjects
+
+{
+ "@odata.type": "#microsoft.graph.group",
+ "displayName": "Library Assist",
+ "mailEnabled": false,
+ "mailNickname": "library",
+ "securityEnabled": true
+}
+```
\ No newline at end of file