Moar updates

Author: darrelmiller

graph/patterns/navigation-property.md

@@ -7,7 +7,7 @@ Microsoft Graph API Design Pattern
 ## Problem
 --------
 
-It is often valuable to represent a relationship between resources in an API. This may be a many-to-one or a one-to-many relationship. 
+It is often valuable to represent a relationship between resources in an API. 
 
 Relationships between resources are often implicitly represented by a property contained in one of the resources that provides a key to a related resource. Usually that information is returned in a representation as an id value and the property is named using a convention that identifies the target type of related resource. e.g. userId 
 
@@ -23,35 +23,70 @@ e.g. /user/{userId}/manager  # many-to-one relationship
 
 Additionally, using the OData Expand query parameter, related entities can be transcluded into the primary entity so both can be retrieved in a single round trip.
 
+These relationships can be described in CSDL as follows:
+
+```xml
+<EntityType Name="user">
+  <NavigationProperty Name="manager" Type="user" ContainsTarget="false" >
+  <NavigationProperty Name="messages" Type="user" ContainsTarget="true" >
+</EntityType>
+```
+
 ## Issues and Considerations
 -------------------------
 
 In the current Microsoft Graph implementation, there are some limitations on the use of navigation properties that cross between backend services. These limitations are being eliminated over time, but it will be necessary to ensure support for any particular scenario.  [Limitations of the current implementation](https://dev.azure.com/msazure/One/_wiki/wikis/Microsoft%20Graph%20Partners/354352/Cross-workload-navigations?anchor=supported-scenarios) are documented internally.
 
-Navigation properties defined within an entity are not returned by default when retreiving the representation of an entity unless explicity desired by a service.  
+Navigation properties defined within an entity are not returned by default when retreiving the representation of an entity unless explicity desired by a service.  The API can consumer can use the `expand` query parameterm, where supported, to retreive both the source and the target entity of the relationship in a single request.
 
 Implementing support for accessing the "$ref" of a navigation property allows a caller to return just the URL of related resource. e.g. `/user/23/manager/$ref`. This is useful when a client wishes to identify the related resource but doesn't need all of its properties.
 
 ## When to Use this Pattern
 ------------------------
 
-### "has a" relationships
+### "Many-to-one" relationships  
 
 The use of navigation properties is preferred over including an Id field to reference the related entity in a many-to-one relationship.  Id values require a client to make two round trips to retrieve the details of a related entity.  With a navigation property a client can retrieve a related entity in a single round trip. 
+ 
+Many-to-one relationships are always non-contained relationships as the lifetime of the target cannot depend on the source.
+
+```xml
+<EntityType Name="order">
+  <NavigationProperty Name="customer" Type="customer" ContainsTarget="false" >
+</EntityType>
+```
+
 
-Navigation properties are also useful when clients sometimes want to retrieve both the primary entity and the related entity in a single round trip.  The `expand` query parameter makes this possible.
+### "Zero-or-one-to-one" relationships  
 
-### "parent-child" relationships
+These navigation properties can be used as a structural organization mechanism to separate properties of an entity in a way that is similar to how complex types are often used. The primary difference being that the target of the navigation property are not returned by default when the source entity is retreived.  The use of the navigation properties over complex properties is preferred when the source and target information comes from different backend APIs.
+
+These relationships must be contained.  
+
+```xml
+<EntityType Name="invoice">
+  <NavigationProperty Name="paymentDetails" Type="paymentInfo" ContainsTarget="true" >
+</EntityType>
+```
+
+### "One-to-many" relationships
 
 Resources that contain a parent Id property in a child resource can utilize a navigation property in the parent resource that is declared as a collection of child resources. If desirable, a parent navigation property can also be created in the child resource to the parent resource. This is usually not necessary as the parent URL is a subset of child resource URL. The main use of this would be when retrieving child resources and choosing to expand properties of the parent resource so that both can be retrieved in a single request.  
 
 `/invoice/{invoiceId}/items/{itemId}?expand=parentInvoice(select=invoiceDate,Customer)`
 
-### "child-parent" relationships
+```xml
+<EntityType Name="invoice">
+  <NavigationProperty Name="items" Type="invoiceItem" ContainsTarget="true" >
+</EntityType>
+
+<EntityType Name="invoiceItem">
+  <NavigationProperty Name="parentInvoice" Type="invoice" ContainsTarget="false" >
+</EntityType>
+```
 
-One other use case is when child resources appear in a non-contained collection and there is a desire to access the canonical parent:
+One-to-many relationships may be contained or non-contained relations.
 
-`/me/pinnedChannels/{channelId}/team`
 
 ## Example
 -------