Merge pull request #369 from microsoft/op-lc-graph-guidelines

Edit patterns and guidelines

Author: Linda-Editor

graph/GuidelinesGraph.md

@@ -1,20 +1,19 @@
-### Deprecation Guidelines
+# Deprecation guidelines
 
-If your API requires the introduction of breaking changes you must add Revisions annotations to the API definition with the following terms:
+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.
+- **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 can 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
+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:**
+## Example of property annotation
 
 ```xml
 <EntityType Name="outlookTask" BaseType="Microsoft.OutlookServices.outlookItem" ags:IsMaster="true" ags:WorkloadName="Task" ags:EnabledForPassthrough="true">
@@ -32,15 +31,13 @@ to annotate any usages of that type.
 </EntityType>
 ```
 
-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.
+When the request URL contains a reference to a deprecated model element, the gateway adds 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 two years beyond the deprecation date) to the response.
 
-**Deprecation header example:**
+## 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"
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+```
+ 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"
+
+```

graph/deprecation.md

@@ -24,8 +24,8 @@ Before using a dictionary type in your API definition, make sure that your scena
 
 ### 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.
-- [Complex types](https://docs.microsoft.com/en-us/odata/webapi/complextypewithnavigationproperty) when the set of data values are known.
+- [Open extensions](https://docs.microsoft.com/graph/extensibility-open-users) when you want to provide clients the ability to extend Microsoft Graph.
+- [Complex types](https://docs.microsoft.com/odata/webapi/complextypewithnavigationproperty) when the set of data values are known.
 
 ## Issues and considerations
 

graph/patterns/dictionary.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](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](./subtypes.md) and Flat bag of properties.
 
 ## Issues and considerations
 

graph/patterns/facets.md

@@ -38,7 +38,7 @@ We recommend that a new namespace be aligned with a top-level API category.
 
 - Microsoft Graph consistency requirements discourage using the same type names for different concepts even within different namespaces. Microsoft Graph type names must be descriptive and unique within the API surface without requiring  full qualification.
 
-- A namespace must be consistent with an API category in the navigation path according to [Microsoft Graph REST API Guidelines](GuidelinesGraph.md#uniform-resource-locators-urls).
+- A namespace must be consistent with an API category in the navigation path according to [Microsoft Graph REST API Guidelines](../GuidelinesGraph.md#uniform-resource-locators-urls).
 
 - When type name is ambiguous and requires a namespace qualifier, changing a namespace is a breaking change.
 

graph/patterns/namespace.md

@@ -20,12 +20,9 @@ subtype for each variant of the resource. In the hierarchy, the interdependencie
 ## When to use this pattern
 
 Use this pattern where each variant of a common concept has its own unique properties and behaviors,
-no combination of variants is anticipated,
-and it is acceptable that callers who need to query resources by variant are adequately served by filtering or partitioning using type casting.
+no combination of variants is anticipated, and it is acceptable that callers who need to query resources by variant are adequately served by filtering or partitioning using type casting.
 
-Related patterns are
-[Facets](facets.md) and
-[Flat bag of properties](flatbag.md).
+Related patterns are [Facets](./facets.md) and Flat bag of properties.
 
 ## Issues and considerations