SAP · HeikoTheissen · Jul 11, 2024 · Aug 17, 2023 · Aug 17, 2023 · Aug 17, 2023
diff --git a/_layouts/default.html b/_layouts/default.html
@@ -7,6 +7,18 @@
 
 {% seo %}
     <link rel="stylesheet" href="{{ "/assets/css/style.css?v=" | append: site.github.build_revision | relative_url }}">
+
+    <script type="text/javascript" id="MathJax-script" async
+      src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js">
+    </script>
+    <script>
+      MathJax = {
+        tex: {
+          inlineMath: [['$', '$']]
+        }
+      };
+    </script>
+
   </head>
   <body>
     <div class="container-lg px-3 my-5 markdown-body">
@@ -29,5 +41,12 @@ <h1><a href="{{ "/" | absolute_url }}">{{ site.title | default: site.github.repo
         </p> 
       </div>
     </footer>
+
+    <script type="module">
+      import mermaid from "https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs";
+      mermaid.initialize({startOnLoad: false});
+      mermaid.run({nodes: document.querySelectorAll('.language-mermaid')});
+    </script>
+
   </body>
 </html>
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
@@ -1690,6 +1690,42 @@
         "@Core.Description": "Path to property in the collection of recommended values. Format is identical to PropertyPath annotations."
       }
     },
+    "Recommendations": {
+      "$Kind": "Term",
+      "$Type": "Edm.ComplexType",
+      "@Common.Experimental": true,
+      "@Core.Description": "AI-based 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 AI-based 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 `AIRecommendedFieldValue`\n- a property to which the `Common.Text` annotation evaluates, its name may differ from `AIRecommendedFieldDescription`\n- a property named `AIRecommendedFieldScoreValue`\n- a Boolean property named `AIRecommendedFieldIsSuggestion`.",
+      "AIRecommendedFieldValue": {
+        "$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": "AIRecommendedFieldDescription" }
+      },
+      "AIRecommendedFieldDescription": {
+        "$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."
+      },
+      "AIRecommendedFieldScoreValue": {
+        "$Type": "Edm.Decimal",
+        "$Nullable": true,
+        "@Core.Description": "Confidence score of the recommended value"
+      },
+      "AIRecommendedFieldIsSuggestion": {
+        "$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 of `SAP__Recommendations`,\n            this flag can be true in at most one instance of the collection,\n            and only if the `AIRecommendedFieldScoreValue` 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#L1788:~: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#L1794:~: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#L1824:~: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#L1856:~: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#L1860:~: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#L1870:~: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#L1856:~:text=<Term%20Name="-,Recommendations,-") *([Experimental](Common.md#Experimental))*|ComplexType|<a name="Recommendations"></a>AI-based 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#L1905:~: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#L1909:~: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#L1919:~: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,-")
@@ -1126,8 +1127,25 @@ Property|Type|Description
 [LocalDataProperty](./UI.xml#L1848:~:text=<ComplexType%20Name="-,RecommendationBinding,-")|PropertyPath|Path to editable property for which recommended values exist
 [ValueListProperty](./UI.xml#L1851:~: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#L1868:~:text=<ComplexType%20Name="-,PropertyRecommendationType,-") *([Experimental](Common.md#Experimental))*
+Base type containing AI-based 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 `AIRecommendedFieldValue`
+- a property to which the `Common.Text` annotation evaluates, its name may differ from `AIRecommendedFieldDescription`
+- a property named `AIRecommendedFieldScoreValue`
+- a Boolean property named `AIRecommendedFieldIsSuggestion`.
+
+Property|Type|Description
+:-------|:---|:----------
+[AIRecommendedFieldValue](./UI.xml#L1878:~: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.
+[AIRecommendedFieldDescription](./UI.xml#L1885:~: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.
+[AIRecommendedFieldScoreValue](./UI.xml#L1891:~:text=<ComplexType%20Name="-,PropertyRecommendationType,-")|Decimal?|Confidence score of the recommended value
+[AIRecommendedFieldIsSuggestion](./UI.xml#L1894:~: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 of `SAP__Recommendations`, this flag can be true in at most one instance of the collection, and only if the `AIRecommendedFieldScoreValue` exceeds a certain threshold.
+
 <a name="ActionName"></a>
-## [ActionName](./UI.xml#L1875:~:text=<TypeDefinition%20Name="-,ActionName,-")
+## [ActionName](./UI.xml#L1924:~: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
@@ -1853,6 +1853,55 @@ This is in contrast to [DataFieldForIntentBasedNavigation](#DataFieldForIntentBa
         </Property>
       </ComplexType>
 
+      <Term Name="Recommendations" Type="Edm.ComplexType" Nullable="false">
+        <Annotation Term="Common.Experimental" />
+        <Annotation Term="Core.Description" String="AI-based 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 AI-based 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 `AIRecommendedFieldValue`
+- a property to which the `Common.Text` annotation evaluates, its name may differ from `AIRecommendedFieldDescription`
+- a property named `AIRecommendedFieldScoreValue`
+- a Boolean property named `AIRecommendedFieldIsSuggestion`.</String>
+        </Annotation>
+        <Property Name="AIRecommendedFieldValue" 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="AIRecommendedFieldDescription" />
+        </Property>
+        <Property Name="AIRecommendedFieldDescription" 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.</String>
+          </Annotation>
+        </Property>
+        <Property Name="AIRecommendedFieldScoreValue" Type="Edm.Decimal" Scale="variable" Nullable="true">
+          <Annotation Term="Core.Description" String="Confidence score of the recommended value" />
+        </Property>
+        <Property Name="AIRecommendedFieldIsSuggestion" 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 of `SAP__Recommendations`,
+            this flag can be true in at most one instance of the collection,
+            and only if the `AIRecommendedFieldScoreValue` 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>