SAP-specific solution to oasis-tcs/odata-specs#2067

Author: HeikoTheissen

Diff for: vocabularies/Common.json

@@ -1358,6 +1358,14 @@
       "$AppliesTo": ["EntityContainer"],
       "@Core.Description": "Service prefers requests to use a resource path with navigation properties",
       "@Core.LongDescription": "Use this tag on services that do not restrict requests to certain resource paths\nvia [`Capabilities`](https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Capabilities.V1.html)\nor [`Core.RequiresExplicitBinding`](https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Core.V1.html#RequiresExplicitBinding)\nannotations, but that prefer requests with a resource path that\ncontains the navigation properties reflecting the UI structure.\n\nFor example, entering a cancellation fee into an order item field bound to `CancellationItem/Fee`\nleads to a\n`PATCH Orders(23)/Items(5)/CancellationItem` request with `{\"Fee\": ...}` payload."
+    },
+    "PartnerPath": {
+      "$Kind": "Term",
+      "$Type": "Edm.NavigationPropertyPath",
+      "$AppliesTo": ["NavigationProperty"],
+      "@Common.Experimental": true,
+      "@Core.Description": "A navigation property path that behaves like a [partner navigation property](https://oasis-tcs.github.io/odata-specs/odata-csdl-xml/odata-csdl-xml.html#PartnerNavigationProperty) but may traverse other navigation properties",
+      "@Core.LongDescription": "Let B be any entity in the collection addressed by evaluating the `PartnerPath` starting at an entity A.\nIf the annotated navigation property is single-valued, it MUST lead back from B to A.\nIf the annotated navigation property is collection-valued, A MUST be one of the\nentities related to B via it.\n\nExample: `Headers(1)/_Item(2)/_Subitem(3)/_Header` is the same entity as `Headers(1)`\nif the subitems entity type has a non-containment navigation property `_Header` annotated with\n`\"@Common.PartnerPath\": \"_Item/_Subitem\"`."
     }
   }
 }

Diff for: vocabularies/Common.md

@@ -114,6 +114,7 @@ Term|Type|Description
 [WebSocketBaseURL](Common.xml#L1506) *([Experimental](Common.md#Experimental))*|URL|<a name="WebSocketBaseURL"></a>Base URL for WebSocket connections<br>This annotation MUST be unqualified.
 [WebSocketChannel](Common.xml#L1514) *([Experimental](Common.md#Experimental))*|String?|<a name="WebSocketChannel"></a>Channel for WebSocket connections<br><p>Messages sent over the channel follow the <a href="https://community.sap.com/t5/application-development-blog-posts/specification-of-the-push-channel-protocol-pcp/ba-p/13137541">ABAP Push Channel Protocol</a>. To consume a channel, the client opens a web socket connection at the <a href="#WebSocketBaseURL"><code>WebSocketBaseURL</code></a> followed by URL parameters</p> <ul> <li>parameter name = annotation qualifier, parameter value = channel ID (see below)</li> <li>parameter name = <code>relatedService</code>, parameter value = base URL (relative to server root) of the OData service of the app</li> </ul> <p>Supported qualifiers and channel IDs:</p> <dl> <dt>`sideEffects` <dd>Notifications about side effects to be triggered by the client (channel ID = non-null annotation value) </dl> 
 [AddressViaNavigationPath](Common.xml#L1531)|[Tag](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#Tag)|<a name="AddressViaNavigationPath"></a>Service prefers requests to use a resource path with navigation properties<br>Use this tag on services that do not restrict requests to certain resource paths via [`Capabilities`](https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Capabilities.V1.html) or [`Core.RequiresExplicitBinding`](https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Core.V1.html#RequiresExplicitBinding) annotations, but that prefer requests with a resource path that contains the navigation properties reflecting the UI structure.<br>For example, entering a cancellation fee into an order item field bound to `CancellationItem/Fee` leads to a `PATCH Orders(23)/Items(5)/CancellationItem` request with `{"Fee": ...}` payload.
+[PartnerPath](Common.xml#L1546) *([Experimental](Common.md#Experimental))*|NavigationPropertyPath|<a name="PartnerPath"></a>A navigation property path that behaves like a [partner navigation property](https://oasis-tcs.github.io/odata-specs/odata-csdl-xml/odata-csdl-xml.html#PartnerNavigationProperty) but may traverse other navigation properties<br>Let B be any entity in the collection addressed by evaluating the `PartnerPath` starting at an entity A. If the annotated navigation property is single-valued, it MUST lead back from B to A. If the annotated navigation property is collection-valued, A MUST be one of the entities related to B via it.<br>Example: `Headers(1)/_Item(2)/_Subitem(3)/_Header` is the same entity as `Headers(1)` if the subitems entity type has a non-containment navigation property `_Header` annotated with `"@Common.PartnerPath": "_Item/_Subitem"`.
 
 <a name="TextFormatType"></a>
 ## [TextFormatType](Common.xml#L134)

Diff for: vocabularies/Common.xml

@@ -1543,6 +1543,21 @@ leads to a
         </Annotation>
       </Term>
 
+      <Term Name="PartnerPath" Type="Edm.NavigationPropertyPath" Nullable="false" AppliesTo="NavigationProperty">
+        <Annotation Term="Common.Experimental" />
+        <Annotation Term="Core.Description" String="A navigation property path that behaves like a [partner navigation property](https://oasis-tcs.github.io/odata-specs/odata-csdl-xml/odata-csdl-xml.html#PartnerNavigationProperty) but may traverse other navigation properties" />
+        <Annotation Term="Core.LongDescription">
+          <String>Let B be any entity in the collection addressed by evaluating the `PartnerPath` starting at an entity A.
+If the annotated navigation property is single-valued, it MUST lead back from B to A.
+If the annotated navigation property is collection-valued, A MUST be one of the
+entities related to B via it.
+
+Example: `Headers(1)/_Item(2)/_Subitem(3)/_Header` is the same entity as `Headers(1)`
+if the subitems entity type has a non-containment navigation property `_Header` annotated with
+`"@Common.PartnerPath": "_Item/_Subitem"`.</String>
+        </Annotation>
+      </Term>
+
     </Schema>
   </edmx:DataServices>
 </edmx:Edmx>