SAP · HeikoTheissen · Jul 11, 2024 · Aug 17, 2023 · Aug 17, 2023 · Aug 17, 2023
diff --git a/docs/recommendations.md b/docs/recommendations.md
@@ -0,0 +1,91 @@
+Entity types for which recommendations are available have an additional property carrying the recommendations and the following annotation pointing to this property:
+```xml
+<EntityType Name="...">
+  <Annotation Term="UI.Recommendations" Path="SAP__Recommendations" />
+  <Key>
+    <PropertyRef Name="ID" />
+  </Key>
+  <Property Name="ID" Type="Edm.String" Nullable="false" />
+  <Property Name="DocumentType" Type="Edm.String" />
+  ...
+  <Property Name="SAP__Recommendations" Type="self.RecommendationsType" />
+</EntityType>
+<ComplexType Name="RecommendationsType">
+  <Property Name="DocumentType" Type="Collection(UI.PropertyRecommendationType)" />
+  ...
+</ComplexType>
+```
+
+Clients request recommendations from the server at their discretion.
+
+```mermaid
+sequenceDiagram
+  actor client as Fiori client
+  actor otherclient as Other Fiori client<br>of same collaborative draft
+  box ABAP
+    participant server as OData service
+    participant task as New task
+  end
+  participant AI as BTP recommendations service
+  client ->>+ server: POST $batch
+  server ->> server: PATCH SalesOrder('A')
+  server ->> server: GET SalesOrder('A')?$expand=... for side effects
+  server -->> client: $batch response
+  par server decides whether to update recommendations
+    opt input for recommendations has changed
+      server ->>+ task: call function ... starting new task
+      deactivate server
+      task ->>+ AI: compute recommendations
+      AI -->>- task: return recommendations
+      task ->> task: update recommendations in draft
+      deactivate task
+    end
+  and
+    client ->>+ server: GET SalesOrder('A')?$select=SAP__Recommendations&$expand=...
+    server ->> server: read recommendations from draft
+    server -->>- client: return recommendations
+  and
+    otherclient ->>+ server: GET SalesOrder('A')?$select=SAP__Recommendations&$expand=...
+    server ->> server: read recommendations from draft
+    server -->>- otherclient: return recommendations
+  end
+```
+
+Alternatively, clients can be notified via web socket if recommendations have been updated.
+
+```mermaid
+sequenceDiagram
+  actor client as Fiori client
+  actor otherclient as Other Fiori client<br>of same collaborative draft
+  box ABAP
+    participant server as OData service
+    participant task as New task
+  end
+  participant AI as BTP recommendations service
+  client ->>+ server: POST $batch
+  server ->> server: PATCH SalesOrder('A')
+  server ->> server: GET SalesOrder('A')?$expand=... for side effects
+  server -->> client: $batch response
+  opt input for recommendations has changed
+    server ->>+ task: call function ... starting new task
+    deactivate server
+    task ->>+ AI: compute recommendations
+    AI -->>- task: return recommendations
+    task ->> task: update recommendations in draft
+    par
+      task ->> client: notify client of updated recommendations
+    and
+      task ->> otherclient: notify client of updated recommendations
+    end
+    deactivate task
+    par
+      client ->>+ server: GET SalesOrder('A')?$select=SAP__Recommendations&$expand=...
+      server ->> server: read recommendations from draft
+      server -->>- client: return recommendations
+    and
+      otherclient ->>+ server: GET SalesOrder('A')?$select=SAP__Recommendations&$expand=...
+      server ->> server: read recommendations from draft
+      server -->>- otherclient: return recommendations
+    end
+  end
+```
diff --git a/vocabularies/UI.json b/vocabularies/UI.json
@@ -1696,6 +1696,43 @@
         "@Core.Description": "Path to property in the collection of recommended values. Format is identical to PropertyPath annotations."
       }
     },
+    "Recommendations": {
+      "$Kind": "Term",
+      "$Type": "Edm.ComplexType",
+      "$AppliesTo": ["EntityType"],
+      "@Common.Experimental": true,
+      "@Core.Description": "Recommendations for an entity",
+      "@Core.LongDescription": "This complex-typed annotation contains structural properties corresponding via name equality\nto non-key structural properties of the entity type for which recommendations are available.\nThe type of such a property is a collection of an informal specialization of [`PropertyRecommendationType`](#PropertyRecommendationType).\n\nClients retrieve the recommendations with a GET request that includes this annotation in a `$select` clause.\nThe recommendations SHOULD be computed asynchronously, see [this diagram](../docs/recommendations.md)."
+    },
+    "PropertyRecommendationType": {
+      "$Kind": "ComplexType",
+      "$Abstract": true,
+      "@Common.Experimental": true,
+      "@Core.Description": "Base type containing recommendations for an entity type property",
+      "@Core.LongDescription": "Informal specializations of this base type have four properties:\n- a property that is the target of a [`Common.Text`](Common.md#Text) annotation, its name may differ from `RecommendedFieldValue`\n- a property to which the `Common.Text` annotation evaluates, its name may differ from `RecommendedFieldDescription`\n- a property named `RecommendedFieldScoreValue`\n- a Boolean property named `RecommendedFieldIsSuggestion`.",
+      "RecommendedFieldValue": {
+        "$Type": "Edm.PrimitiveType",
+        "@Core.Description": "Recommended value",
+        "@Core.LongDescription": "In specializations of this base type, this property is specialized to the primitive type of the entity type property.",
+        "@Common.Text": { "$Path": "RecommendedFieldDescription" }
+      },
+      "RecommendedFieldDescription": {
+        "$Nullable": true,
+        "@Core.Description": "Description of the recommended value",
+        "@Core.LongDescription": "In specializations of this base type, this property is specialized to the string type of the text property corresponding to the entity type property.\n            This property is omitted from specializations for recommendations without text."
+      },
+      "RecommendedFieldScoreValue": {
+        "$Type": "Edm.Decimal",
+        "$Nullable": true,
+        "@Core.Description": "Confidence score of the recommended value"
+      },
+      "RecommendedFieldIsSuggestion": {
+        "$Type": "Edm.Boolean",
+        "$DefaultValue": false,
+        "@Core.Description": "Whether the recommended value shall be suggested in the input field",
+        "@Core.LongDescription": "For any collection of a specialization of `PropertyRecommendationType`\n            in a property containing [`Recommendations`](#Recommendations),\n            this flag can be true in at most one instance of the collection,\n            and only if the `RecommendedFieldScoreValue` exceeds a certain threshold."
+      }
+    },
     "ExcludeFromNavigationContext": {
       "$Kind": "Term",
       "$Type": "Core.Tag",

diff --git a/vocabularies/UI.md b/vocabularies/UI.md
@@ -72,9 +72,10 @@ Term|Type|Description
 [ParameterDefaultValue](./UI.xml#L1789:~:text=<Term%20Name="-,ParameterDefaultValue,-")|PrimitiveType?|<a name="ParameterDefaultValue"></a>Define default values for action parameters<br>For unbound actions the default value can either be a constant expression, or a dynamic expression using absolute paths, e.g. singletons or function import results. Whereas for bound actions the bound entity and its properties and associated properties can be used as default values
 [RecommendationState](./UI.xml#L1795:~:text=<Term%20Name="-,RecommendationState,-")|[RecommendationStateType](#RecommendationStateType)|<a name="RecommendationState"></a>Indicates whether a field contains or has a recommended value<br>Intelligent systems can help users by recommending input the user may "prefer".
 [RecommendationList](./UI.xml#L1825:~:text=<Term%20Name="-,RecommendationList,-")|[RecommendationListType](#RecommendationListType)|<a name="RecommendationList"></a>Specifies how to get a list of recommended values for a property or parameter<br>Intelligent systems can help users by recommending input the user may "prefer".
-[ExcludeFromNavigationContext](./UI.xml#L1857:~:text=<Term%20Name="-,ExcludeFromNavigationContext,-")|[Tag](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#Tag)|<a name="ExcludeFromNavigationContext"></a>The contents of this property must not be propagated to the app-to-app navigation context
-[DoNotCheckScaleOfMeasuredQuantity](./UI.xml#L1861:~:text=<Term%20Name="-,DoNotCheckScaleOfMeasuredQuantity,-") *([Experimental](Common.md#Experimental))*|Boolean|<a name="DoNotCheckScaleOfMeasuredQuantity"></a>Do not check the number of fractional digits of the annotated measured quantity<br>The annotated property contains a measured quantity, and the user may enter more fractional digits than defined for the corresponding unit of measure.<br/>This switches off the validation of user input with respect to decimals.
-[LeadingEntitySet](./UI.xml#L1871:~:text=<Term%20Name="-,LeadingEntitySet,-") *([Experimental](Common.md#Experimental))*|String|<a name="LeadingEntitySet"></a>The referenced entity set is the preferred starting point for UIs using this service
+[Recommendations](./UI.xml#L1857:~:text=<Term%20Name="-,Recommendations,-") *([Experimental](Common.md#Experimental))*|ComplexType|<a name="Recommendations"></a>Recommendations for an entity<br>This complex-typed annotation contains structural properties corresponding via name equality to non-key structural properties of the entity type for which recommendations are available. The type of such a property is a collection of an informal specialization of [`PropertyRecommendationType`](#PropertyRecommendationType).<br/>Clients retrieve the recommendations with a GET request that includes this annotation in a `$select` clause. The recommendations SHOULD be computed asynchronously, see [this diagram](../docs/recommendations.md).
+[ExcludeFromNavigationContext](./UI.xml#L1907:~:text=<Term%20Name="-,ExcludeFromNavigationContext,-")|[Tag](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#Tag)|<a name="ExcludeFromNavigationContext"></a>The contents of this property must not be propagated to the app-to-app navigation context
+[DoNotCheckScaleOfMeasuredQuantity](./UI.xml#L1911:~:text=<Term%20Name="-,DoNotCheckScaleOfMeasuredQuantity,-") *([Experimental](Common.md#Experimental))*|Boolean|<a name="DoNotCheckScaleOfMeasuredQuantity"></a>Do not check the number of fractional digits of the annotated measured quantity<br>The annotated property contains a measured quantity, and the user may enter more fractional digits than defined for the corresponding unit of measure.<br/>This switches off the validation of user input with respect to decimals.
+[LeadingEntitySet](./UI.xml#L1921:~:text=<Term%20Name="-,LeadingEntitySet,-") *([Experimental](Common.md#Experimental))*|String|<a name="LeadingEntitySet"></a>The referenced entity set is the preferred starting point for UIs using this service
 
 <a name="HeaderInfoType"></a>
 ## [HeaderInfoType](./UI.xml#L68:~:text=<ComplexType%20Name="-,HeaderInfoType,-")
@@ -1138,8 +1139,25 @@ Property|Type|Description
 [LocalDataProperty](./UI.xml#L1849:~:text=<ComplexType%20Name="-,RecommendationBinding,-")|PropertyPath|Path to editable property for which recommended values exist
 [ValueListProperty](./UI.xml#L1852:~:text=<ComplexType%20Name="-,RecommendationBinding,-")|String|Path to property in the collection of recommended values. Format is identical to PropertyPath annotations.
 
+<a name="PropertyRecommendationType"></a>
+## [*PropertyRecommendationType*](./UI.xml#L1869:~:text=<ComplexType%20Name="-,PropertyRecommendationType,-") *([Experimental](Common.md#Experimental))*
+Base type containing recommendations for an entity type property
+
+Informal specializations of this base type have four properties:
+- a property that is the target of a [`Common.Text`](Common.md#Text) annotation, its name may differ from `RecommendedFieldValue`
+- a property to which the `Common.Text` annotation evaluates, its name may differ from `RecommendedFieldDescription`
+- a property named `RecommendedFieldScoreValue`
+- a Boolean property named `RecommendedFieldIsSuggestion`.
+
+Property|Type|Description
+:-------|:---|:----------
+[RecommendedFieldValue](./UI.xml#L1879:~:text=<ComplexType%20Name="-,PropertyRecommendationType,-")|PrimitiveType|Recommended value<br>In specializations of this base type, this property is specialized to the primitive type of the entity type property.
+[RecommendedFieldDescription](./UI.xml#L1886:~:text=<ComplexType%20Name="-,PropertyRecommendationType,-")|String?|Description of the recommended value<br>In specializations of this base type, this property is specialized to the string type of the text property corresponding to the entity type property. This property is omitted from specializations for recommendations without text.
+[RecommendedFieldScoreValue](./UI.xml#L1893:~:text=<ComplexType%20Name="-,PropertyRecommendationType,-")|Decimal?|Confidence score of the recommended value
+[RecommendedFieldIsSuggestion](./UI.xml#L1896:~:text=<ComplexType%20Name="-,PropertyRecommendationType,-")|Boolean|Whether the recommended value shall be suggested in the input field<br>For any collection of a specialization of `PropertyRecommendationType` in a property containing [`Recommendations`](#Recommendations), this flag can be true in at most one instance of the collection, and only if the `RecommendedFieldScoreValue` exceeds a certain threshold.
+
 <a name="ActionName"></a>
-## [ActionName](./UI.xml#L1876:~:text=<TypeDefinition%20Name="-,ActionName,-")
+## [ActionName](./UI.xml#L1926:~:text=<TypeDefinition%20Name="-,ActionName,-")
 **Type:** String
 
 Name of an Action, Function, ActionImport, or FunctionImport in scope

diff --git a/vocabularies/UI.xml b/vocabularies/UI.xml
@@ -1854,6 +1854,56 @@ This is in contrast to [DataFieldForIntentBasedNavigation](#DataFieldForIntentBa
         </Property>
       </ComplexType>
 
+      <Term Name="Recommendations" Type="Edm.ComplexType" Nullable="false" AppliesTo="EntityType">
+        <Annotation Term="Common.Experimental" />
+        <Annotation Term="Core.Description" String="Recommendations for an entity" />
+          <Annotation Term="Core.LongDescription">
+          <String>This complex-typed annotation contains structural properties corresponding via name equality
+to non-key structural properties of the entity type for which recommendations are available.
+The type of such a property is a collection of an informal specialization of [`PropertyRecommendationType`](#PropertyRecommendationType).
+
+Clients retrieve the recommendations with a GET request that includes this annotation in a `$select` clause.
+The recommendations SHOULD be computed asynchronously, see [this diagram](../docs/recommendations.md).</String>
+          </Annotation>
+      </Term>
+      <ComplexType Name="PropertyRecommendationType" Abstract="true">
+        <Annotation Term="Common.Experimental" />
+        <Annotation Term="Core.Description" String="Base type containing recommendations for an entity type property" />
+        <Annotation Term="Core.LongDescription">
+          <String>Informal specializations of this base type have four properties:
+- a property that is the target of a [`Common.Text`](Common.md#Text) annotation, its name may differ from `RecommendedFieldValue`
+- a property to which the `Common.Text` annotation evaluates, its name may differ from `RecommendedFieldDescription`
+- a property named `RecommendedFieldScoreValue`
+- a Boolean property named `RecommendedFieldIsSuggestion`.</String>
+        </Annotation>
+        <Property Name="RecommendedFieldValue" Type="Edm.PrimitiveType" Nullable="false">
+          <Annotation Term="Core.Description" String="Recommended value" />
+          <Annotation Term="Core.LongDescription">
+            <String>In specializations of this base type, this property is specialized to the primitive type of the entity type property.</String>
+          </Annotation>
+          <Annotation Term="Common.Text" Path="RecommendedFieldDescription" />
+        </Property>
+        <Property Name="RecommendedFieldDescription" Type="Edm.String" Nullable="true">
+          <Annotation Term="Core.Description" String="Description of the recommended value" />
+          <Annotation Term="Core.LongDescription">
+            <String>In specializations of this base type, this property is specialized to the string type of the text property corresponding to the entity type property.
+            This property is omitted from specializations for recommendations without text.</String>
+          </Annotation>
+        </Property>
+        <Property Name="RecommendedFieldScoreValue" Type="Edm.Decimal" Scale="variable" Nullable="true">
+          <Annotation Term="Core.Description" String="Confidence score of the recommended value" />
+        </Property>
+        <Property Name="RecommendedFieldIsSuggestion" Type="Edm.Boolean" Nullable="false" DefaultValue="false">
+          <Annotation Term="Core.Description" String="Whether the recommended value shall be suggested in the input field" />
+          <Annotation Term="Core.LongDescription">
+            <String>For any collection of a specialization of `PropertyRecommendationType`
+            in a property containing [`Recommendations`](#Recommendations),
+            this flag can be true in at most one instance of the collection,
+            and only if the `RecommendedFieldScoreValue` exceeds a certain threshold.</String>
+          </Annotation>
+        </Property>
+      </ComplexType>
+
       <Term Name="ExcludeFromNavigationContext" Type="Core.Tag" Nullable="false" DefaultValue="true" AppliesTo="Property">
         <Annotation Term="Core.Description" String="The contents of this property must not be propagated to the app-to-app navigation context" />
       </Term>