Strengthen the specification of CopyAction (#370)

SAP · Feb 18, 2025 · 9dfb163 · 9dfb163
1 parent 80ec2a4
commit 9dfb163
Show file tree

Hide file tree

Showing 3 changed files with 20 additions and 8 deletions.
diff --git a/vocabularies/Hierarchy.json b/vocabularies/Hierarchy.json
@@ -224,7 +224,7 @@
         "$IsBound": true,
         "@Common.Experimental": true,
         "@Core.Description": "Template for actions that copy a node and its descendants and are named in [`RecursiveHierarchyActions/CopyAction`](#RecursiveHierarchyActionsType)",
-        "@Core.LongDescription": "To give the copied sub-hierarchy a parent, the action invocation can be followed\nby a PATCH that binds the parent navigation property (for example, `Superordinate` in the following JSON batch request).\n```json\n{\"requests\": [{\n  \"id\": \"1\",\n  \"method\": \"post\",\n  \"url\": \"HierarchyDirectory(1)/Nodes('A')/CopyAction\"\n}, {\n  \"id\": \"2\",\n  \"dependsOn\": [\"1\"],\n  \"method\": \"patch\",\n  \"url\": \"$1\",\n  \"body\": {\n    \"[email protected]\": \"Nodes('B')\"\n  }\n}]}\n```",
+        "@Core.LongDescription": "The action copies a node A and its descendants and the parent navigation properties between them\nso that the copied nodes form a sub-hierarchy. It returns the copy of A. No assumption is made about the parent of the copy of A.\n\nTo specify the parent of the copy of A, the action invocation MUST be followed\nby a PATCH that binds its parent navigation property (for example, `Superordinate` in the following JSON batch request)\nto the desired parent B or to `null`.\n```json\n{\"requests\": [{\n  \"id\": \"1\",\n  \"method\": \"post\",\n  \"url\": \"HierarchyDirectory(1)/Nodes('A')/CopyAction\"\n}, {\n  \"id\": \"2\",\n  \"dependsOn\": [\"1\"],\n  \"method\": \"patch\",\n  \"url\": \"$1\",\n  \"body\": {\n    \"[email protected]\": \"Nodes('B')\"\n  }\n}]}\n```\nIf a certain position of the copy of A among its new siblings is desired, an additional invocation of\n[`ChangeNextSiblingAction`](#Template_ChangeNextSiblingAction) can be included in the batch request.",
         "$Parameter": [{ "$Name": "Node", "$Type": "Edm.EntityType", "@Core.Description": "The node to be copied" }],
         "$ReturnType": { "$Type": "Edm.EntityType", "@Core.Description": "The copied node" }
       }

diff --git a/vocabularies/Hierarchy.md b/vocabularies/Hierarchy.md
@@ -32,8 +32,12 @@ Parameter|Type|Description
 
 Template for actions that copy a node and its descendants and are named in [`RecursiveHierarchyActions/CopyAction`](#RecursiveHierarchyActionsType)
 
-To give the copied sub-hierarchy a parent, the action invocation can be followed
-by a PATCH that binds the parent navigation property (for example, `Superordinate` in the following JSON batch request).
+The action copies a node A and its descendants and the parent navigation properties between them
+so that the copied nodes form a sub-hierarchy. It returns the copy of A. No assumption is made about the parent of the copy of A.
+
+To specify the parent of the copy of A, the action invocation MUST be followed
+by a PATCH that binds its parent navigation property (for example, `Superordinate` in the following JSON batch request)
+to the desired parent B or to `null`.
 ```json
 {"requests": [{
   "id": "1",
@@ -49,11 +53,13 @@ by a PATCH that binds the parent navigation property (for example, `Superordinat
   }
 }]}
 ```
+If a certain position of the copy of A among its new siblings is desired, an additional invocation of
+[`ChangeNextSiblingAction`](#Template_ChangeNextSiblingAction) can be included in the batch request.
 
 Parameter|Type|Description
 :--------|:---|:----------
-**[Node](Hierarchy.xml#L359)**|EntityType|**Binding parameter:** The node to be copied
-[&rarr;](Hierarchy.xml#L362)|EntityType|The copied node
+**[Node](Hierarchy.xml#L365)**|EntityType|**Binding parameter:** The node to be copied
+[&rarr;](Hierarchy.xml#L368)|EntityType|The copied node
 
 
 

diff --git a/vocabularies/Hierarchy.xml b/vocabularies/Hierarchy.xml
@@ -338,8 +338,12 @@ and [`RecursiveHierarchy/MatchedDescendantCount`](#RecursiveHierarchyType) are a
         <Annotation Term="Common.Experimental" />
         <Annotation Term="Core.Description" String="Template for actions that copy a node and its descendants and are named in [`RecursiveHierarchyActions/CopyAction`](#RecursiveHierarchyActionsType)" />
         <Annotation Term="Core.LongDescription">
-          <String>To give the copied sub-hierarchy a parent, the action invocation can be followed
-by a PATCH that binds the parent navigation property (for example, `Superordinate` in the following JSON batch request).
+          <String>The action copies a node A and its descendants and the parent navigation properties between them
+so that the copied nodes form a sub-hierarchy. It returns the copy of A. No assumption is made about the parent of the copy of A.
+
+To specify the parent of the copy of A, the action invocation MUST be followed
+by a PATCH that binds its parent navigation property (for example, `Superordinate` in the following JSON batch request)
+to the desired parent B or to `null`.
 ```json
 {"requests": [{
   "id": "1",
@@ -354,7 +358,9 @@ by a PATCH that binds the parent navigation property (for example, `Superordinat
     "[email protected]": "Nodes('B')"
   }
 }]}
-```</String>
+```
+If a certain position of the copy of A among its new siblings is desired, an additional invocation of
+[`ChangeNextSiblingAction`](#Template_ChangeNextSiblingAction) can be included in the batch request.</String>
         </Annotation>
         <Parameter Name="Node" Type="Edm.EntityType" Nullable="false">
           <Annotation Term="Core.Description" String="The node to be copied" />