Don't mention the "return URL" variant

SAP · Sep 19, 2023 · f37b4d8 · f37b4d8
1 parent 1f1bb4d
commit f37b4d8
Show file tree

Hide file tree

Showing 3 changed files with 23 additions and 100 deletions.
diff --git a/vocabularies/Common.json b/vocabularies/Common.json
@@ -1295,15 +1295,15 @@
       "$Type": "Common.QualifiedName",
       "$AppliesTo": ["EntityType"],
       "@Common.Experimental": true,
-      "@Core.Description": "Qualified name of a function that computes AI-based recommendations for entities of the annotated type (see [this template](#Template_RecommendationsFunction) and [this alternative](#Template_RecommendationsFunction2))"
+      "@Core.Description": "Qualified name of a function that computes AI-based recommendations for entities of the annotated type (see [this template](#Template_RecommendationsFunction))"
     },
     "Template_RecommendationsFunction": [
       {
         "$Kind": "Function",
         "$IsBound": true,
         "@Common.Experimental": true,
         "@Core.Description": "Template for functions that compute AI-based recommendations for the bound entity and its related entities",
-        "@Core.LongDescription": "If the function is invoked repeatedly in a stateful session, it SHOULD NOT\nrecompute recommendations whose predictors have not changed since the previous invocation.\n\nThe function computes the recommendations asynchronously and returns a URL where its result can be retrieved.\nThe result is a collection of [`Common.PropertyRecommendationType`](#PropertyRecommendationType)\nwhose entries differ in their `target`.\n\nThe template function itself cannot be invoked.",
+        "@Core.LongDescription": "If the function is invoked repeatedly in a stateful session, it SHOULD NOT\nrecompute recommendations whose predictors have not changed since the previous invocation.\n\nThe function SHOULD compute the recommendations asynchronously (`Prefer: respond-async`).\n\nThe template function itself cannot be invoked.",
         "$Parameter": [
           { "$Name": "Entity", "$Type": "Edm.EntityType" },
           {
@@ -1314,37 +1314,6 @@
             "@Core.LongDescription": "The request `SalesOrder('A')/ns.RecommendationsFunction?Targets=[\"\",\"Items(10)\"]`\n            retrieves recommendations for the entities `SalesOrder('A')` and `SalesOrder('A')/Items(10)`."
           }
         ],
-        "$ReturnType": {
-          "@Core.IsURL": true,
-          "@Core.Description": "URL (relative to the service URL) for retrieving the recommendations (which are computed asynchronously)",
-          "@Core.Example": {
-            "@odata.type": "https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Core.V1.xml#Core.PrimitiveExampleValue",
-            "Description": "Relative URL for invoking a function import of the [retrieval function](#Template_RecommendationsRetrievalFunction)",
-            "Value": "RetrieveRecommendations?ID=af43c2"
-          }
-        }
-      }
-    ],
-    "Template_RecommendationsFunction2": [
-      {
-        "$Kind": "Function",
-        "$IsBound": true,
-        "@Common.Experimental": true,
-        "@Core.Description": "Variant of [`Template_RecommendationsFunction`](#Template_RecommendationsFunction)",
-        "@Core.LongDescription": "The function returns the recommendations but can be invoked with `Prefer: respond-async`.\n\nThe template function itself cannot be invoked.",
-        "$Parameter": [
-          {
-            "$Name": "Entity",
-            "$Type": "Edm.EntityType",
-            "@Core.Description": "See parameter `Entity` in [`Template_RecommendationsFunction`](#Template_RecommendationsFunction)"
-          },
-          {
-            "$Name": "Targets",
-            "$Collection": true,
-            "@Core.IsURL": true,
-            "@Core.Description": "See parameter `Targets` in [`Template_RecommendationsFunction`](#Template_RecommendationsFunction)"
-          }
-        ],
         "$ReturnType": {
           "$Collection": true,
           "$Type": "Common.PropertyRecommendationType",

diff --git a/vocabularies/Common.md b/vocabularies/Common.md
@@ -110,8 +110,8 @@ Term|Type|Description
 [mediaUploadLink](./Common.xml#L1431:~:text=<Term%20Name="-,mediaUploadLink,-") *([Experimental](Common.md#Experimental))*|URL|<a name="mediaUploadLink"></a>URL for uploading new media content to a Document Management Service<br>In contrast to the `@odata.mediaEditLink` this URL allows to upload new media content without directly changing a stream property or media resource. The upload request typically uses HTTP POST with `Content-Type: multipart/form-data` following RFC 7578. The upload request must contain one multipart representing the content of the file. The `name` parameter in the `Content-Disposition` header (as described in RFC 7578) is irrelevant, but the `filename` parameter is expected. If the request succeeds the response will contain a JSON body of `Content-Type: application/json` with a JSON property `readLink`. The newly uploaded media resource can be linked to the stream property by changing the `@odata.mediaReadLink` to the value of this `readLink` in a subsequent PATCH request to the OData entity.
 [PrimitivePropertyPath](./Common.xml#L1446:~:text=<Term%20Name="-,PrimitivePropertyPath,-") *([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#L1451:~:text=<Term%20Name="-,WebSocketBaseURL,-") *([Experimental](Common.md#Experimental))*|URL|<a name="WebSocketBaseURL"></a>Base URL for WebSocket connections
-[RecommendationsFunction](./Common.xml#L1457:~:text=<Term%20Name="-,RecommendationsFunction,-") *([Experimental](Common.md#Experimental))*|[QualifiedName](#QualifiedName)|<a name="RecommendationsFunction"></a>Qualified name of a function that computes AI-based recommendations for entities of the annotated type (see [this template](#Template_RecommendationsFunction) and [this alternative](#Template_RecommendationsFunction2))
-[RecommendationsRole](./Common.xml#L1545:~:text=<Term%20Name="-,RecommendationsRole,-") *([Experimental](Common.md#Experimental))*|[RecommendationsRoleType](#RecommendationsRoleType)|<a name="RecommendationsRole"></a>Role of this property or parameter regarding AI-based recommendations
+[RecommendationsFunction](./Common.xml#L1457:~:text=<Term%20Name="-,RecommendationsFunction,-") *([Experimental](Common.md#Experimental))*|[QualifiedName](#QualifiedName)|<a name="RecommendationsFunction"></a>Qualified name of a function that computes AI-based recommendations for entities of the annotated type (see [this template](#Template_RecommendationsFunction))
+[RecommendationsRole](./Common.xml#L1517:~:text=<Term%20Name="-,RecommendationsRole,-") *([Experimental](Common.md#Experimental))*|[RecommendationsRoleType](#RecommendationsRoleType)|<a name="RecommendationsRole"></a>Role of this property or parameter regarding AI-based recommendations
 
 
 ## Functions
@@ -124,33 +124,15 @@ Template for functions that compute AI-based recommendations for the bound entit
 If the function is invoked repeatedly in a stateful session, it SHOULD NOT
 recompute recommendations whose predictors have not changed since the previous invocation.
 
-The function computes the recommendations asynchronously and returns a URL where its result can be retrieved.
-The result is a collection of [`Common.PropertyRecommendationType`](#PropertyRecommendationType)
-whose entries differ in their `target`.
+The function SHOULD compute the recommendations asynchronously (`Prefer: respond-async`).
 
 The template function itself cannot be invoked.
 
 Parameter|Type|Description
 :--------|:---|:----------
-**[Entity](./Common.xml#L1474:~:text=<Function%20Name="-,Template_RecommendationsFunction,-")**|EntityType|**Binding parameter**
-[Targets](./Common.xml#L1475:~:text=<Function%20Name="-,Template_RecommendationsFunction,-")|\[URL\]|URLs (relative to the request URL) that address entities, properties or action/function parameters for which recommendations shall be retrieved<br>The request `SalesOrder('A')/ns.RecommendationsFunction?Targets=["","Items(10)"]` retrieves recommendations for the entities `SalesOrder('A')` and `SalesOrder('A')/Items(10)`.
-[&rarr;](./Common.xml#L1483:~:text=<Function%20Name="-,Template_RecommendationsFunction,-")|URL|URL (relative to the service URL) for retrieving the recommendations (which are computed asynchronously) ([Example](./Common.xml#L1486))
-
-
-<a name="Template_RecommendationsFunction2"></a>
-### [Template_RecommendationsFunction2](./Common.xml#L1494:~:text=<Function%20Name="-,Template_RecommendationsFunction2,-") *([Experimental](Common.md#Experimental))*
-
-Variant of [`Template_RecommendationsFunction`](#Template_RecommendationsFunction)
-
-The function returns the recommendations but can be invoked with `Prefer: respond-async`.
-
-The template function itself cannot be invoked.
-
-Parameter|Type|Description
-:--------|:---|:----------
-**[Entity](./Common.xml#L1502:~:text=<Function%20Name="-,Template_RecommendationsFunction2,-")**|EntityType|**Binding parameter:** See parameter `Entity` in [`Template_RecommendationsFunction`](#Template_RecommendationsFunction)
-[Targets](./Common.xml#L1505:~:text=<Function%20Name="-,Template_RecommendationsFunction2,-")|\[URL\]|See parameter `Targets` in [`Template_RecommendationsFunction`](#Template_RecommendationsFunction)
-[&rarr;](./Common.xml#L1509:~:text=<Function%20Name="-,Template_RecommendationsFunction2,-")|\[[PropertyRecommendationType](#PropertyRecommendationType)\]|A collection of recommendations that differ in their `target`
+**[Entity](./Common.xml#L1472:~:text=<Function%20Name="-,Template_RecommendationsFunction,-")**|EntityType|**Binding parameter**
+[Targets](./Common.xml#L1473:~:text=<Function%20Name="-,Template_RecommendationsFunction,-")|\[URL\]|URLs (relative to the request URL) that address entities, properties or action/function parameters for which recommendations shall be retrieved<br>The request `SalesOrder('A')/ns.RecommendationsFunction?Targets=["","Items(10)"]` retrieves recommendations for the entities `SalesOrder('A')` and `SalesOrder('A')/Items(10)`.
+[&rarr;](./Common.xml#L1481:~:text=<Function%20Name="-,Template_RecommendationsFunction,-")|\[[PropertyRecommendationType](#PropertyRecommendationType)\]|A collection of recommendations that differ in their `target`
 
 
 <a name="TextFormatType"></a>
@@ -473,34 +455,34 @@ Use terms [Aggregation.RecursiveHierarchy](https://github.com/oasis-tcs/odata-vo
 User ID
 
 <a name="PropertyRecommendationType"></a>
-## [PropertyRecommendationType](./Common.xml#L1513:~:text=<ComplexType%20Name="-,PropertyRecommendationType,-") *([Experimental](Common.md#Experimental))*
+## [PropertyRecommendationType](./Common.xml#L1485:~:text=<ComplexType%20Name="-,PropertyRecommendationType,-") *([Experimental](Common.md#Experimental))*
 
 
 Property|Type|Description
 :-------|:---|:----------
-[target](./Common.xml#L1515:~:text=<ComplexType%20Name="-,PropertyRecommendationType,-")|URL|URL (relative to the URL of the recommendations function request) addressing a property [OData-URL, section 4.6] that is targeted by this recommendation<br>The request `SalesOrder('A')/ns.RecommendationsFunction?Targets=...` might retrieve a recommendation with `"target": "Items(10)/Product"`.
-[value](./Common.xml#L1523:~:text=<ComplexType%20Name="-,PropertyRecommendationType,-")|String|Recommended value, converted to string
-[text](./Common.xml#L1526:~:text=<ComplexType%20Name="-,PropertyRecommendationType,-")|String?|Description of the recommended value
-[alternatives](./Common.xml#L1529:~:text=<ComplexType%20Name="-,PropertyRecommendationType,-")|\[[AlternativeRecommendationType](#AlternativeRecommendationType)\]|A list of alternative values, sorted by confidence score in descending order<br>If a value is recommended via property `value`, it must be the first entry in this list.
+[target](./Common.xml#L1487:~:text=<ComplexType%20Name="-,PropertyRecommendationType,-")|URL|URL (relative to the URL of the recommendations function request) addressing a property [OData-URL, section 4.6] that is targeted by this recommendation<br>The request `SalesOrder('A')/ns.RecommendationsFunction?Targets=...` might retrieve a recommendation with `"target": "Items(10)/Product"`.
+[value](./Common.xml#L1495:~:text=<ComplexType%20Name="-,PropertyRecommendationType,-")|String|Recommended value, converted to string
+[text](./Common.xml#L1498:~:text=<ComplexType%20Name="-,PropertyRecommendationType,-")|String?|Description of the recommended value
+[alternatives](./Common.xml#L1501:~:text=<ComplexType%20Name="-,PropertyRecommendationType,-")|\[[AlternativeRecommendationType](#AlternativeRecommendationType)\]|A list of alternative values, sorted by confidence score in descending order<br>If a value is recommended via property `value`, it must be the first entry in this list.
 
 <a name="AlternativeRecommendationType"></a>
-## [AlternativeRecommendationType](./Common.xml#L1536:~:text=<ComplexType%20Name="-,AlternativeRecommendationType,-") *([Experimental](Common.md#Experimental))*
+## [AlternativeRecommendationType](./Common.xml#L1508:~:text=<ComplexType%20Name="-,AlternativeRecommendationType,-") *([Experimental](Common.md#Experimental))*
 
 
 Property|Type|Description
 :-------|:---|:----------
-[value](./Common.xml#L1538:~:text=<ComplexType%20Name="-,AlternativeRecommendationType,-")|String|Alternatively recommended value, converted to string
-[score](./Common.xml#L1541:~:text=<ComplexType%20Name="-,AlternativeRecommendationType,-")|Decimal?|Confidence score of the alternatively recommended value
+[value](./Common.xml#L1510:~:text=<ComplexType%20Name="-,AlternativeRecommendationType,-")|String|Alternatively recommended value, converted to string
+[score](./Common.xml#L1513:~:text=<ComplexType%20Name="-,AlternativeRecommendationType,-")|Decimal?|Confidence score of the alternatively recommended value
 
 <a name="RecommendationsRoleType"></a>
-## [RecommendationsRoleType](./Common.xml#L1549:~:text=<TypeDefinition%20Name="-,RecommendationsRoleType,-") *([Experimental](Common.md#Experimental))*
+## [RecommendationsRoleType](./Common.xml#L1521:~:text=<TypeDefinition%20Name="-,RecommendationsRoleType,-") *([Experimental](Common.md#Experimental))*
 **Type:** String
 
 
 
 Allowed Value|Description
 :------------|:----------
-[Input](./Common.xml#L1553:~:text=<TypeDefinition%20Name="-,RecommendationsRoleType,-")|The property is input for some recommendation
-[Output](./Common.xml#L1557:~:text=<TypeDefinition%20Name="-,RecommendationsRoleType,-")|The property or parameter is the target of some recommendation
-[InputOutput](./Common.xml#L1561:~:text=<TypeDefinition%20Name="-,RecommendationsRoleType,-")|The property is input for and the target of some recommendation
-[Required](./Common.xml#L1565:~:text=<TypeDefinition%20Name="-,RecommendationsRoleType,-")|The property is mandatory input for recommendations to be requested
+[Input](./Common.xml#L1525:~:text=<TypeDefinition%20Name="-,RecommendationsRoleType,-")|The property is input for some recommendation
+[Output](./Common.xml#L1529:~:text=<TypeDefinition%20Name="-,RecommendationsRoleType,-")|The property or parameter is the target of some recommendation
+[InputOutput](./Common.xml#L1533:~:text=<TypeDefinition%20Name="-,RecommendationsRoleType,-")|The property is input for and the target of some recommendation
+[Required](./Common.xml#L1537:~:text=<TypeDefinition%20Name="-,RecommendationsRoleType,-")|The property is mandatory input for recommendations to be requested
diff --git a/vocabularies/Common.xml b/vocabularies/Common.xml
@@ -1456,7 +1456,7 @@ If the request succeeds the response will contain a JSON body of `Content-Type:
 
       <Term Name="RecommendationsFunction" Type="Common.QualifiedName" Nullable="false" AppliesTo="EntityType">
         <Annotation Term="Common.Experimental" />
-        <Annotation Term="Core.Description" String="Qualified name of a function that computes AI-based recommendations for entities of the annotated type (see [this template](#Template_RecommendationsFunction) and [this alternative](#Template_RecommendationsFunction2))" />
+        <Annotation Term="Core.Description" String="Qualified name of a function that computes AI-based recommendations for entities of the annotated type (see [this template](#Template_RecommendationsFunction))" />
       </Term>
       <Function Name="Template_RecommendationsFunction" IsBound="true">
         <Annotation Term="Common.Experimental" />
@@ -1465,9 +1465,7 @@ If the request succeeds the response will contain a JSON body of `Content-Type:
           <String>If the function is invoked repeatedly in a stateful session, it SHOULD NOT
 recompute recommendations whose predictors have not changed since the previous invocation.
 
-The function computes the recommendations asynchronously and returns a URL where its result can be retrieved.
-The result is a collection of [`Common.PropertyRecommendationType`](#PropertyRecommendationType)
-whose entries differ in their `target`.
+The function SHOULD compute the recommendations asynchronously (`Prefer: respond-async`).
 
 The template function itself cannot be invoked.</String>
         </Annotation>
@@ -1480,32 +1478,6 @@ The template function itself cannot be invoked.</String>
             retrieves recommendations for the entities `SalesOrder('A')` and `SalesOrder('A')/Items(10)`.</String>
           </Annotation>
         </Parameter>
-        <ReturnType Type="Edm.String" Nullable="false">
-          <Annotation Term="Core.IsURL" />
-          <Annotation Term="Core.Description" String="URL (relative to the service URL) for retrieving the recommendations (which are computed asynchronously)" />
-          <Annotation Term="Core.Example">
-            <Record Type="Core.PrimitiveExampleValue">
-              <PropertyValue Property="Description" String="Relative URL for invoking a function import of the [retrieval function](#Template_RecommendationsRetrievalFunction)" />
-              <PropertyValue Property="Value" String="RetrieveRecommendations?ID=af43c2" />
-            </Record>
-          </Annotation>
-        </ReturnType>
-      </Function>
-      <Function Name="Template_RecommendationsFunction2" IsBound="true">
-        <Annotation Term="Common.Experimental" />
-        <Annotation Term="Core.Description" String="Variant of [`Template_RecommendationsFunction`](#Template_RecommendationsFunction)" />
-        <Annotation Term="Core.LongDescription">
-          <String>The function returns the recommendations but can be invoked with `Prefer: respond-async`.
-
-The template function itself cannot be invoked.</String>
-        </Annotation>
-        <Parameter Name="Entity" Type="Edm.EntityType" Nullable="false">
-          <Annotation Term="Core.Description" String="See parameter `Entity` in [`Template_RecommendationsFunction`](#Template_RecommendationsFunction)" />
-        </Parameter>
-        <Parameter Name="Targets" Type="Collection(Edm.String)" Nullable="false">
-          <Annotation Term="Core.IsURL" />
-          <Annotation Term="Core.Description" String="See parameter `Targets` in [`Template_RecommendationsFunction`](#Template_RecommendationsFunction)" />
-        </Parameter>
         <ReturnType Type="Collection(Common.PropertyRecommendationType)" Nullable="false">
           <Annotation Term="Core.Description" String="A collection of recommendations that differ in their `target`" />
         </ReturnType>