add guidance for transitioning from a structural collection to a navigation collection

graph/articles/collections.md

@@ -316,3 +316,148 @@ Content-Type: application/json
    "value": []
 }
 ```
+
+## 11. Collections of structural types (complex types or primitive types)
+
+Collections of entity types are generally preferable to collections of structual types because collections of structural types must be updated as a single unit, meaning that they are overwritten entirely by new contents, rather than be updated relative to the existing contents. 
+Sometimes, structural collection properties are added to a type and then scenarios are discovered later that require a collection of entity types.
+Take the following model with an entity type `foo` that has a collection of `bar`s:
+
+```xml
+<EntityType Name="foo">
+  <Key>
+    <PropertyRef Name="id" />
+  </Key>
+  <Property Name="id" Type="Edm.String" Nullable="false" />
+  <Property Name="bars" Type="Collection(self.bar)" />
+</EntityType>
+
+<ComplexType Name="bar">
+  <Property Name="prop1" Type="Edm.String" />
+  <Property Name="prop2" Type="Edm.String" />
+</ComplexType>
+```
+and a scenario arises that requires, for example, to remove individual `bar`s from the collection. 
+There are two options forward: //// TODO do we want to offer both options, or just one?
+
+### 11.1 Side-by-side collection properties
+
+The model can be updated to have two collections side-by-side:
+```diff
+<EntityType Name="foo">
+  <Key>
+    <PropertyRef Name="id" />
+  </Key>
+  <Property Name="id" Type="Edm.String" Nullable="false" />
+  <Property Name="bars" Type="Collection(self.bar)" />
++ <NavigationProperty Name="barsAsEntities" Type="Collection(self.barAsEntity)" ContainsTarget="true" />
+</EntityType>
+
+<ComplexType Name="bar">
+  <Property Name="prop1" Type="Edm.String" />
+  <Property Name="prop2" Type="Edm.String" />
+</ComplexType>
+
++<EntityType Name="barAsEntity">
++ <Key>
++   <PropertyRef Name="prop1" />
++ </Key>
++ <Property Name="prop1" Type="Edm.String" />
++ <Property Name="prop2" Type="Edm.String" />
++</EntityType>
+```
+Clients will now be able to refer to individual `bar`s using `prop1` as a key, and they can now remove those `bar`s using `DELETE` requests:
+```http
+DELETE /foos/{fooId}/bars/{some_prop1}
+```
+```http
+HTTP/1.1 204 No Content
+```
+The expectation is that `bars` and `barsAsEntities` are treated as two "views" into the same data.
+To meet this expectation, workloads must:
+1. Keep the properties consistent between `bar` and `barAsEntity`.
+Any changes to one type must be reflected in the other type.
+2. Reject requests that update both collections at the same time.
+A request that adds an item to `barsAsEntities` while replacing the content of `bars` must rejected with a `400`, for example:
+```http
+PATCH /foos/{fooId}
+{
+  "bars": [
+    {
+      "prop1": "some value",
+      "prop2": "another value"
+    }
+  ],
+  "barsAsEntities@delta": [
+    {
+      "prop1": "a key value",
+      "prop2": "some new value"
+    }
+  ]
+}
+```
+```http
+HTTP/1.1 400 Bad Request
+{
+  "error": {
+    "code": "badRequest",
+    "message": "'bars' and 'barsAsEntities' cannot be updated in the same request.",
+}
+```
+
+TODO should this be a 409 conflict instead?
+TODO implement this in WebApi
+
+### 11.2 `$select` overloading
+
+The model can be updated to simply switch the complex type for an entity type:
+```diff
+<EntityType Name="foo">
+  <Key>
+    <PropertyRef Name="id" />
+  </Key>
+  <Property Name="id" Type="Edm.String" Nullable="false" />
+- <Property Name="bars" Type="Collection(self.bar)" />
++ <NavigationProperty Name="bars" Type="Collection(self.bar)" ContainsTarget="true" />
+</EntityType>
+
+- <ComplexType Name="bar">
++ <EntityType Name="bar">
++ <Key>
++   <PropertyRef Name="prop1" />
++ </Key>
+  <Property Name="prop1" Type="Edm.String" />
+  <Property Name="prop2" Type="Edm.String" />
+-</ComplexType>
++</EntityType>
+```
+To maintain backwards compatibility **and** compliance with the OData standard, there are several semantic changes that the workload must address:
+1. Existing clients would have been able to `$select` the `bars` property.
+Now that `bars` is a navigation property, the [OData standard](https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part2-url-conventions.html#_Toc31361040) specifies that its navigation link be returned when it is `$selected`:
+
+> If the select item is a navigation property, then the corresponding navigation link is represented in the response.
+
+Because the previous behavior for `$select=bars` was to include the collection in the response, and because the standard dictates that the navigation link be included in the response, the new behavior is to include both:
+
+```http
+GET /foos/{fooId}?$select=bars
+```
+```http
+200 OK
+{
+  "id": "{fooId}",
+  "bars": [
+    {
+      "prop1": "some value",
+      "prop2": "another value"
+    },
+    ...
+  ]
+  "bars@odata.navigationLink": "/foos('{fooId}')/bars"
+}
+```
+
+2. The default behavior for structural collections is to include them in the response payload for their containing entity. If this was the behavior of `foo` before, it must be preserved by **auto-expanding** the `bars` property now that it is a navigation property (because the default behavior for navigation properties is to **not** expand them).
+3. Structural collections are updated using `PATCH` requests to replace the entire contents of the collection. The new navigation property must preserve this behavior.
+
+TODO implement this in webapi