Merge remote-tracking branch 'origin/main' into

interface/hierarchy-maintenance
SAP · Jan 9, 2024 · b6d8974 · b6d8974
2 parents 89992d6 + 4e50dfc
commit b6d8974
Show file tree

Hide file tree

Showing 14 changed files with 825 additions and 722 deletions.
diff --git a/.github/workflows/nodejs.yml b/.github/workflows/nodejs.yml
@@ -8,7 +8,7 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [18.x, 20.x]
+        node-version: [20.x]
 
     steps:
       - uses: actions/checkout@v3

diff --git a/package-lock.json b/package-lock.json
diff --git a/vocabularies/Common.json b/vocabularies/Common.json
@@ -308,7 +308,7 @@
       "@Core.LongDescription": "When changes are requested, the value of this annotation in the before-image or after-image\n          of the request plays a role. These may differ if the value is given dynamically in the metadata.",
       "Mandatory": 7,
       "[email protected]": "Property is mandatory from a business perspective",
-      "[email protected]": "A request that sets the property to its initial value or null fails entirely if this annotation is `Mandatory` in the after-image of the request.\n\n            This annotation value does not imply any restrictions on the value range of the property. For restricting the value range use e.g. the standard type facet `Nullable` with a value of `false` to exclude the `null` value, or terms from the [Validation vocabulary](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Validation.V1.md).",
+      "[email protected]": "A request that\n            <br>- sets the property to null or an empty value or\n            <br>- creates a non-[draft](#DraftRoot) entity and omits the property or\n            <br>- activates a draft entity while the property is null or empty\n            <br>fails entirely if this annotation is `Mandatory` in the after-image of the request.\n            The empty string is an empty value. Service-specific rules may consider other values, also\n            of non-string type, empty.\n            Values in draft entities are never considered empty.\n            Mandatory properties SHOULD be decorated in the UI with an asterisk.\n            Null or empty values can also be disallowed by restricting the property value range with the standard type facet `Nullable` or terms from the [Validation vocabulary](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Validation.V1.md).",
       "Optional": 3,
       "[email protected]": "Property may have a value",
       "[email protected]": "This value does not make sense as a static annotation value.",
@@ -451,6 +451,12 @@
     },
     "IntervalType": {
       "$Kind": "ComplexType",
+      "Label": {
+        "$Nullable": true,
+        "@Common.Experimental": true,
+        "@Core.Description": "A short, human-readable text suitable for labels and captions in UIs",
+        "@Core.IsLanguageDependent": true
+      },
       "LowerBoundary": {
         "$Type": "Edm.PropertyPath",
         "@Core.Description": "Property holding the lower interval boundary"
@@ -591,12 +597,22 @@
       "$Type": "Core.Tag",
       "$DefaultValue": true,
       "$AppliesTo": ["Property", "Parameter"],
-      "@Core.Description": "If specified as true, there's only one value list mapping and its value list consists of a small number of fixed values"
+      "@Core.Description": "If specified as true, there's only one value list mapping and its value list consists of a small number of fixed values",
+      "@Validation.ApplicableTerms": ["Common.ValueListShowValuesImmediately"]
+    },
+    "ValueListShowValuesImmediately": {
+      "$Kind": "Term",
+      "$Type": "Core.Tag",
+      "$DefaultValue": true,
+      "$AppliesTo": ["Annotation"],
+      "@Common.Experimental": true,
+      "@Core.Description": "A value list with a very small number of fixed values, can decide to show all values immediately"
     },
     "ValueListForValidation": {
       "$Kind": "Term",
       "$AppliesTo": ["Property", "Parameter"],
-      "@Core.Description": "Contains the qualifier of the ValueList or ValueListMapping that should be used for validation"
+      "@Core.Description": "Contains the qualifier of the ValueList or ValueListMapping that should be used for validation",
+      "@Core.LongDescription": "An empty string identifies the ValueList or ValueListMapping without a qualifier."
     },
     "ValueListReferences": {
       "$Kind": "Term",

diff --git a/vocabularies/Common.md b/vocabularies/Common.md
diff --git a/vocabularies/Common.xml b/vocabularies/Common.xml
@@ -387,9 +387,16 @@
         <Member Name="Mandatory" Value="7">
           <Annotation Term="Core.Description" String="Property is mandatory from a business perspective" />
           <Annotation Term="Core.LongDescription">
-            <String>A request that sets the property to its initial value or null fails entirely if this annotation is `Mandatory` in the after-image of the request.
-
-            This annotation value does not imply any restrictions on the value range of the property. For restricting the value range use e.g. the standard type facet `Nullable` with a value of `false` to exclude the `null` value, or terms from the [Validation vocabulary](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Validation.V1.md).</String>
+            <String>A request that
+            &lt;br&gt;- sets the property to null or an empty value or
+            &lt;br&gt;- creates a non-[draft](#DraftRoot) entity and omits the property or
+            &lt;br&gt;- activates a draft entity while the property is null or empty
+            &lt;br&gt;fails entirely if this annotation is `Mandatory` in the after-image of the request.
+            The empty string is an empty value. Service-specific rules may consider other values, also
+            of non-string type, empty.
+            Values in draft entities are never considered empty.
+            Mandatory properties SHOULD be decorated in the UI with an asterisk.
+            Null or empty values can also be disallowed by restricting the property value range with the standard type facet `Nullable` or terms from the [Validation vocabulary](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Validation.V1.md).</String>
           </Annotation>
         </Member>
         <Member Name="Optional" Value="3">
@@ -560,6 +567,11 @@ The minimum structure is
         <Annotation Term="Core.Description" String="An interval with lower and upper boundaries described by two properties" />
       </Term>
       <ComplexType Name="IntervalType">
+        <Property Name="Label" Type="Edm.String" Nullable="true">
+          <Annotation Term="Common.Experimental" />
+          <Annotation Term="Core.Description" String="A short, human-readable text suitable for labels and captions in UIs" />
+          <Annotation Term="Core.IsLanguageDependent" />
+        </Property>
         <Property Name="LowerBoundary" Type="Edm.PropertyPath" Nullable="false">
           <Annotation Term="Core.Description" String="Property holding the lower interval boundary" />
         </Property>
@@ -702,10 +714,21 @@ The minimum structure is
 
       <Term Name="ValueListWithFixedValues" Type="Core.Tag" Nullable="false" DefaultValue="true" AppliesTo="Property Parameter">
         <Annotation Term="Core.Description" String="If specified as true, there's only one value list mapping and its value list consists of a small number of fixed values" />
+        <Annotation Term="Validation.ApplicableTerms">
+          <Collection>
+            <String>Common.ValueListShowValuesImmediately</String>
+          </Collection>
+        </Annotation>
+      </Term>
+
+      <Term Name="ValueListShowValuesImmediately" Type="Core.Tag" Nullable="false" DefaultValue="true" AppliesTo="Annotation">
+        <Annotation Term="Common.Experimental" />
+        <Annotation Term="Core.Description" String="A value list with a very small number of fixed values, can decide to show all values immediately" />
       </Term>
 
       <Term Name="ValueListForValidation" Type="Edm.String" Nullable="false" AppliesTo="Property Parameter">
         <Annotation Term="Core.Description" String="Contains the qualifier of the ValueList or ValueListMapping that should be used for validation" />
+        <Annotation Term="Core.LongDescription" String="An empty string identifies the ValueList or ValueListMapping without a qualifier." />
       </Term>
 
       <Term Name="ValueListReferences" Type="Collection(Edm.String)" Nullable="false" AppliesTo="Property Parameter">

diff --git a/vocabularies/Hierarchy.json b/vocabularies/Hierarchy.json
@@ -9,6 +9,9 @@
     },
     "https://sap.github.io/odata-vocabularies/vocabularies/Common.json": {
       "$Include": [{ "$Namespace": "com.sap.vocabularies.Common.v1", "$Alias": "Common" }]
+    },
+    "https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Validation.V1.json": {
+      "$Include": [{ "$Namespace": "Org.OData.Validation.V1", "$Alias": "Validation" }]
     }
   },
   "com.sap.vocabularies.Hierarchy.v1": {
@@ -28,7 +31,7 @@
       "@Common.Experimental": true,
       "@Common.IsInstanceAnnotation": true,
       "@Core.Description": "Hierarchy-specific information in the result set of a hierarchical request",
-      "@Core.LongDescription": "The [base term](https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Aggregation.V1.html#RecursiveHierarchy)\n          governs what are the nodes and parents in the hierarchy, whereas this annotation contains derived information."
+      "@Core.LongDescription": "The [base term](https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Aggregation.V1.html#RecursiveHierarchy)\n          governs what are the nodes and parents in the hierarchy, whereas this term defines derived information."
     },
     "RecursiveHierarchyType": {
       "$Kind": "ComplexType",
@@ -70,6 +73,12 @@
         "@Core.Description": "Number of ancestors an occurrence of a node has in the limited hierarchy",
         "@Core.LongDescription": "This equals the number of ancestors in the sub-hierarchy, if the request involves a sub-hierarchy."
       },
+      "LimitedRank": {
+        "$Type": "Edm.Int64",
+        "$Nullable": true,
+        "@Core.Description": "Rank of a node in the limited hierarchy in preorder or postorder",
+        "@Core.LongDescription": "The rank of a node is the index of the node in the sequence of nodes\n            created from a preorder or postorder traversal of the limited hierarchy. The first node in the traversal has rank 0."
+      },
       "SiblingRank": {
         "$Type": "Edm.Int64",
         "$Nullable": true,
@@ -98,7 +107,8 @@
     },
     "RecursiveHierarchyActionsType": {
       "$Kind": "ComplexType",
-      "@Core.LongDescription": "The qualified action names identify actions for maintaining nodes in the recursive hierarchy,\nwhich are specific for the given annotation qualifier.\nThese binding parameter of the actions MUST be the entity type on which the recursive hierarchy is defined.\nThe resource path of the binding parameter MUST traverse the hierarchy collection,\nincluding any hierarchy directory.",
+      "@Common.Experimental": true,
+      "@Core.LongDescription": "The qualified action names identify actions for maintaining nodes in the recursive hierarchy,\n          which are specific for the given annotation qualifier.\n          These binding parameter of the actions MUST be the entity type on which the recursive hierarchy is defined.\n          The resource path of the binding parameter MUST traverse the hierarchy collection,\n          including any hierarchy directory.",
       "ChangeNextSiblingAction": {
         "$Type": "Common.QualifiedName",
         "$Nullable": true,
@@ -117,7 +127,7 @@
       "@Common.Experimental": true,
       "@Common.IsInstanceAnnotation": true,
       "@Core.Description": "Instance annotation on the result of an `$apply` query option containing the number of matching nodes after hierarchical transformations",
-      "@Core.LongDescription": "The service MAY designate a subset of the `$apply` result as \"matching nodes\".\n          For requests following the pattern described [here](#RecursiveHierarchyType), this subset is the output set of the\n          `filter` or `search` transformation that occurs as the fourth parameter\n          of the last `ancestors` transformation or occurs nested into it.<br>\n          For requests not following this pattern, the subset NEED NOT be defined.<br>\n          This instance annotation is available if [`RecursiveHierarchy/MatchedProperty`](#RecursiveHierarchyType)\n          and `RecursiveHierarchy/MatchedDescendantCountProperty` are also available."
+      "@Core.LongDescription": "The service MAY designate a subset of the `$apply` result as \"matching nodes\".\n          For requests following the pattern described [here](#RecursiveHierarchyType), this subset is the output set of the\n          `filter` or `search` transformation that occurs as the fourth parameter\n          of the last `ancestors` transformation or occurs nested into it.<br>\n          For requests not following this pattern, the subset NEED NOT be defined.<br>\n          This instance annotation is available if [`RecursiveHierarchy/Matched`](#RecursiveHierarchyType)\n          and [`RecursiveHierarchy/MatchedDescendantCount`](#RecursiveHierarchyType) are also available."
     },
     "TopLevels": [
       {
@@ -147,26 +157,12 @@
             "@Core.OptionalParameter": {},
             "@Validation.Minimum": 1
           },
-          {
-            "$Name": "Expand",
-            "$Collection": true,
-            "@Core.Revisions": [{ "Kind": "Deprecated", "Description": "Deprecated in favor of `ExpandLevels`" }],
-            "@Core.Description": "Identifiers of nodes to be expanded",
-            "@Core.OptionalParameter": {}
-          },
           {
             "$Name": "Show",
             "$Collection": true,
             "@Core.Description": "Identifiers of nodes to be shown",
             "@Core.OptionalParameter": {}
           },
-          {
-            "$Name": "Collapse",
-            "$Collection": true,
-            "@Core.Revisions": [{ "Kind": "Deprecated", "Description": "Deprecated in favor of `ExpandLevels`" }],
-            "@Core.Description": "Identifiers of nodes to be collapsed",
-            "@Core.OptionalParameter": {}
-          },
           {
             "$Name": "ExpandLevels",
             "$Collection": true,
@@ -181,6 +177,7 @@
     "TopLevelsExpandType": {
       "$Kind": "ComplexType",
       "@Common.Experimental": true,
+      "@Core.Description": "Information about nodes to be expanded",
       "NodeID": { "@Core.Description": "Identifier of a node to be expanded" },
       "Levels": {
         "$Type": "Edm.Int64",
@@ -195,7 +192,8 @@
       "$AppliesTo": ["Collection"],
       "@Core.AppliesViaContainer": true,
       "@Common.Experimental": true,
-      "@Core.Description": "Whether the annotated collection acts as a [`RecursiveHierarchy`](#RecursiveHierarchy) with the given qualifier"
+      "@Core.Description": "Whether the annotated collection acts as a [`RecursiveHierarchy`](#RecursiveHierarchy) with the given qualifier",
+      "@Core.LongDescription": "This tag is applied to a collection with the same qualifier as the [`RecursiveHierarchy`](#RecursiveHierarchy) term which is applied to its entity type.\n          The recursive hierarchy can then only be addressed through a collection where this tag is true."
     },
     "ChangeNextSibling": [
       {