fix namespace guidance

graph/patterns/namespace.md

@@ -16,31 +16,39 @@ API designers can use the namespace attribute of the CSDL schema to declare a
 namespace and logically organize related API entities in the Microsoft Graph metadata.
 
 ```XML
-<Schema Namespace="microsoft.graph.{namespace}">
+<Schema Namespace="microsoft.graph.{namespace}" Alias="{namespace}">
 ...
 </Schema>
 ```
 
 A public namespace must contain the `microsoft.graph.` prefix and be presented in camel
-case; that is, `microsoft.graph.myNamespace`.
+case; that is, `microsoft.graph.myNamespace`. Elements defined in namespaces not prefixed
+with `microsoft.graph` will be mapped to the public `microsoft.graph` namespace.
+
+Namespaces should not include more than two segments following the `microsoft.graph` prefix;
+that is, `microsoft.graph.myNamespace.mySubNamespace`. 
+
+Public namespaces must define an alias, and that alias must be the concatenation of 
+the segments following the `microsoft.graph` prefix with proper camel casing rules applied;
+that is, `myNamespaceMySubNamespace`.
 
 When type casting is required in the API query, request, or response, a fully
-qualified type name is represented as concatenation of a namespace and a type
-name. For a consistent user experience, namespaces MUST be aligned with the corresponding API category path segment.
+qualified type name is represented as concatenation of the namespace or alias, 
+followed by a dot (`.`) and the type name. 
 
 ## When to use this pattern
 
 API resource grouping creates a user-friendly experience, keeping all resources for a specific feature close together and limiting the length of IDE prompts such as auto-complete in some programming languages.
 
-We recommend that a new namespace be aligned with a top-level API category.
+For a consistent user experience, new namespace should be aligned with a top-level API category.
 
 ## Issues and considerations
 
-- 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.
+- 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 should represent a single concept across the API Surface.
 
 - 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.
+- Changing a namespace prefixed with `microsoft.graph`, or moving types between, into, or out of a namespace prefixed with `microsoft.graph`, is a breaking change.
 
 - To extend a type in a different schema, a service must declare that schema and the type in it. This is conceptually similar to .NET partial types.
 
@@ -51,17 +59,19 @@ We recommend that a new namespace be aligned with a top-level API category.
 - Microsoft Graph has some predefined constraints for declared namespaces:
 
   - All public namespaces must have the prefix `microsoft.graph`.
+
+  - Public namespaces must declare an alias that is the concatenation of the segments following the `microsoft.graph` prefix.
+
+  - At most, two levels of nesting below `microsoft.graph` is recommended.
 
-  - Only one level of nesting deeper than `microsoft.graph` is supported.
-
-  - If a namespace does not begin with the `microsoft.graph` prefix, all types in the schema are coerced into the main `microsoft.graph` namespace.
+  - If a namespace does not begin with the `microsoft.graph` prefix, all types in the schema are mapped into the public `microsoft.graph` namespace.
 
 ## Examples
 
 ### Namespace and type declarations
 
 ```XML
-<Schema Namespace="microsoft.graph.search" xmlns=”<http://docs.oasis-open.org/odata/ns/edm>”\>
+<Schema Namespace="microsoft.graph.search" Alias="search" xmlns=”<http://docs.oasis-open.org/odata/ns/edm>”\>
 …
     <EntityType Name="bookmark" …
     </EntityType>
@@ -88,7 +98,7 @@ declarations) to match this example.
 <?xml version="1.0" encoding="utf-8"?>
 <edmx:Edmx Version="4.0" xmlns:edmx="http://docs.oasis-open.org/odata/ns/edmx" xmlns:odata="http://schemas.microsoft.com/oDataCapabilities">
   <edmx:DataServices>
-    <Schema Namespace="microsoft.graph.callRecords" xmlns="http://docs.oasis-open.org/odata/ns/edm" xmlns:odata="http://schemas.microsoft.com/oDataCapabilities">
+    <Schema Namespace="microsoft.graph.callRecords" Alias="callRecords" xmlns="http://docs.oasis-open.org/odata/ns/edm" xmlns:odata="http://schemas.microsoft.com/oDataCapabilities">
       <EntityType Name="callRecord">
         <Key>
           <PropertyRef Name="id" />
@@ -111,4 +121,4 @@ declarations) to match this example.
     </Schema>
   </edmx:DataServices>
 </edmx:Edmx>
-```
+```