From 5ea47504b3a3071602b243137f701f115ecda627 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Heiko=20Thei=C3=9Fen?= <heiko.theissen@sap.com>
Date: Wed, 12 Feb 2025 08:23:10 +0100
Subject: [PATCH] Prefer change requests via navigation paths (#365)

---
 vocabularies/Common.json |  9 +++++++++
 vocabularies/Common.md   |  1 +
 vocabularies/Common.xml  | 10 ++++++++++
 3 files changed, 20 insertions(+)

diff --git a/vocabularies/Common.json b/vocabularies/Common.json
index d3e90131..a18f9c76 100644
--- a/vocabularies/Common.json
+++ b/vocabularies/Common.json
@@ -1351,6 +1351,15 @@
       "@Common.Experimental": true,
       "@Core.Description": "Channel for WebSocket connections",
       "@Core.LongDescription": "Messages sent over the channel follow the [ABAP Push Channel Protocol](https://community.sap.com/t5/application-development-blog-posts/specification-of-the-push-channel-protocol-pcp/ba-p/13137541).\nTo consume a channel, the client opens a web socket connection at the [`WebSocketBaseURL`](#WebSocketBaseURL)\nfollowed by URL parameters\n- parameter name = annotation qualifier, parameter value = channel ID (see below)\n- parameter name = `relatedService`, parameter value = base URL (relative to server root) of the OData service of the app\n\n<dl>Supported qualifiers and channel IDs:\n<dt>`sideEffects` <dd>Notifications about side effects to be triggered by the client (channel ID = non-null annotation value)\n</dl>"
+    },
+    "ChangeViaNavigationPath": {
+      "$Kind": "Term",
+      "$Type": "Core.Tag",
+      "$DefaultValue": true,
+      "$AppliesTo": ["EntityContainer"],
+      "@Common.Experimental": true,
+      "@Core.Description": "Service prefers change requests to use a resource path with navigation properties",
+      "@Core.LongDescription": "Use this tag on services that do not restrict update and delete operations to certain resource paths\n          via `Capabilities` annotations, but that prefer update and delete operations on a resource path that\n          contains the navigation properties reflecting the object composition."
     }
   }
 }
diff --git a/vocabularies/Common.md b/vocabularies/Common.md
index 3061ad56..6644e9d1 100644
--- a/vocabularies/Common.md
+++ b/vocabularies/Common.md
@@ -113,6 +113,7 @@ Term|Type|Description
 [PrimitivePropertyPath](Common.xml#L1497) *([Experimental](Common.md#Experimental))*|[Tag](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#Tag)|<a name="PrimitivePropertyPath"></a>A term or term property with this tag whose type is (a collection of) `Edm.PropertyPath` MUST resolve to a primitive structural property
 [WebSocketBaseURL](Common.xml#L1502) *([Experimental](Common.md#Experimental))*|URL|<a name="WebSocketBaseURL"></a>Base URL for WebSocket connections<br>This annotation MUST be unqualified.
 [WebSocketChannel](Common.xml#L1510) *([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> <dl>Supported qualifiers and channel IDs: <dt>`sideEffects` <dd>Notifications about side effects to be triggered by the client (channel ID = non-null annotation value) </dl> 
+[ChangeViaNavigationPath](Common.xml#L1526) *([Experimental](Common.md#Experimental))*|[Tag](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#Tag)|<a name="ChangeViaNavigationPath"></a>Service prefers change requests to use a resource path with navigation properties<br>Use this tag on services that do not restrict update and delete operations to certain resource paths via `Capabilities` annotations, but that prefer update and delete operations on a resource path that contains the navigation properties reflecting the object composition.
 
 <a name="TextFormatType"></a>
 ## [TextFormatType](Common.xml#L134)
diff --git a/vocabularies/Common.xml b/vocabularies/Common.xml
index f09af388..eb6ebbb4 100644
--- a/vocabularies/Common.xml
+++ b/vocabularies/Common.xml
@@ -1523,6 +1523,16 @@ followed by URL parameters
         </Annotation>
       </Term>
 
+      <Term Name="ChangeViaNavigationPath" Type="Core.Tag" Nullable="false" DefaultValue="true" AppliesTo="EntityContainer">
+        <Annotation Term="Common.Experimental" />
+        <Annotation Term="Core.Description" String="Service prefers change requests to use a resource path with navigation properties" />
+        <Annotation Term="Core.LongDescription">
+          <String>Use this tag on services that do not restrict update and delete operations to certain resource paths
+          via `Capabilities` annotations, but that prefer update and delete operations on a resource path that
+          contains the navigation properties reflecting the object composition.</String>
+        </Annotation>
+      </Term>
+
     </Schema>
   </edmx:DataServices>
 </edmx:Edmx>