diff --git a/docs/recommendations.md b/docs/recommendations.md index 9462019c..f216bfc9 100644 --- a/docs/recommendations.md +++ b/docs/recommendations.md @@ -1,4 +1,4 @@ -Invocation flow for a recommendations function implementing the signature of [`Common.GetRecommendations`](../vocabularies/Common.md#GetRecommendations) +Invocation flow for a recommendations function implementing the signature of [`Common.AIRecommendations`](../vocabularies/Common.md#AIRecommendations) ```mermaid sequenceDiagram diff --git a/vocabularies/Common.json b/vocabularies/Common.json index c5b941cf..3cae0ad4 100644 --- a/vocabularies/Common.json +++ b/vocabularies/Common.json @@ -1302,7 +1302,7 @@ { "$Name": "Entity", "$Type": "Edm.EntityType" }, { "$Name": "Targets", - "$Type": "Common.RecommendationsTargetsType", + "$Type": "Common.AIRecommendationsTargetsType", "@Core.Description": "Entities, properties or action/function parameters for which recommendations shall be retrieved", "@Core.LongDescription": "Implementations of this function MAY omit this parameter.\n If this parameter is omitted (by the implementation or in the invocation), all recommendations are retrieved.", "@Core.OptionalParameter": {} @@ -1310,28 +1310,28 @@ ], "$ReturnType": { "$Collection": true, - "$Type": "Common.PropertyRecommendationType", + "$Type": "Common.PropertyAIRecommendationType", "@Core.Description": "A collection of recommendations that differ in their `AIRecommendedFieldPath` property" } } ], - "RecommendationsTargetsType": { + "AIRecommendationsTargetsType": { "$Kind": "ComplexType", "@Common.Experimental": true, "URLs": { "$Collection": true, "@Core.IsURL": true, "@Core.Description": "URLs (relative to the request URL) that address entities, properties or action/function parameters for which recommendations shall be retrieved", - "@Core.LongDescription": "The request `SalesOrder('A')/ns.GetRecommendations?Targets={\"URLs\":[\"\",\"Items(10)\"]}`\n retrieves recommendations for the entities `SalesOrder('A')` and `SalesOrder('A')/Items(10)`." + "@Core.LongDescription": "The request `SalesOrder('A')/ns.AIRecommendations?Targets={\"URLs\":[\"\",\"Items(10)\"]}`\n retrieves recommendations for the entities `SalesOrder('A')` and `SalesOrder('A')/Items(10)`." } }, - "PropertyRecommendationType": { + "PropertyAIRecommendationType": { "$Kind": "ComplexType", "@Common.Experimental": true, "AIRecommendedFieldPath": { "@Core.IsURL": true, - "@Core.Description": "URL (relative to the URL of the [`GetRecommendations`](#GetRecommendations) function request) addressing a property [OData-URL, section 4.6](https://docs.oasis-open.org/odata/odata/v4.01/os/part2-url-conventions/odata-v4.01-os-part2-url-conventions.html#sec_AddressingaProperty) that is targeted by this recommendation", - "@Core.LongDescription": "The request `SalesOrder('A')/ns.GetRecommendations?Targets=...`\n might retrieve a recommendation with `\"AIRecommendedFieldPath\": \"Items(10)/Product\"`." + "@Core.Description": "URL (relative to the URL of the [`AIRecommendations`](#AIRecommendations) function request) addressing a property [OData-URL, section 4.6](https://docs.oasis-open.org/odata/odata/v4.01/os/part2-url-conventions/odata-v4.01-os-part2-url-conventions.html#sec_AddressingaProperty) that is targeted by this recommendation", + "@Core.LongDescription": "The request `SalesOrder('A')/ns.AIRecommendations?Targets=...`\n might retrieve a recommendation with `\"AIRecommendedFieldPath\": \"Items(10)/Product\"`." }, "AIRecommendedFieldValue": { "@Core.Description": "Recommended value, converted to string", @@ -1343,12 +1343,12 @@ }, "AIAltvRecmddFldVals": { "$Collection": true, - "$Type": "Common.AlternativeRecommendationType", + "$Type": "Common.AlternativeAIRecommendationType", "@Core.Description": "A list of alternative values, sorted by confidence score in descending order", "@Core.LongDescription": "If a value is recommended via property `AIRecommendedFieldValue`, it must be the first entry in this list." } }, - "AlternativeRecommendationType": { + "AlternativeAIRecommendationType": { "$Kind": "ComplexType", "@Common.Experimental": true, "AIRecommendedFieldValue": { "@Core.Description": "Alternatively recommended value, converted to string" }, @@ -1358,14 +1358,14 @@ "@Core.Description": "Confidence score of the alternatively recommended value" } }, - "RecommendationsRole": { + "AIRecommendationsRole": { "$Kind": "Term", - "$Type": "Common.RecommendationsRoleType", + "$Type": "Common.AIRecommendationsRoleType", "$AppliesTo": ["Property", "Parameter"], "@Common.Experimental": true, "@Core.Description": "Role of this property or parameter regarding AI-based recommendations" }, - "RecommendationsRoleType": { + "AIRecommendationsRoleType": { "$Kind": "TypeDefinition", "$UnderlyingType": "Edm.String", "@Common.Experimental": true, diff --git a/vocabularies/Common.md b/vocabularies/Common.md index 09ae3986..c956ec72 100644 --- a/vocabularies/Common.md +++ b/vocabularies/Common.md @@ -110,7 +110,7 @@ Term|Type|Description [mediaUploadLink](./Common.xml#L1431:~:text=URL for uploading new media content to a Document Management Service
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=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=Base URL for WebSocket connections -[RecommendationsRole](./Common.xml#L1529:~:text=Role of this property or parameter regarding AI-based recommendations +[AIRecommendationsRole](./Common.xml#L1529:~:text=Role of this property or parameter regarding AI-based recommendations ## Functions @@ -125,8 +125,8 @@ The function SHOULD compute the recommendations asynchronously, see [this diagra Parameter|Type|Description :--------|:---|:---------- **[Entity](./Common.xml#L1470:~:text=Implementations of this function MAY omit this parameter. If this parameter is omitted (by the implementation or in the invocation), all recommendations are retrieved. -[→](./Common.xml#L1481:~:text=Implementations of this function MAY omit this parameter. If this parameter is omitted (by the implementation or in the invocation), all recommendations are retrieved. +[→](./Common.xml#L1481:~:text= @@ -448,43 +448,43 @@ Use terms [Aggregation.RecursiveHierarchy](https://github.com/oasis-tcs/odata-vo User ID - -## [RecommendationsTargetsType](./Common.xml#L1485:~:text= +## [AIRecommendationsTargetsType](./Common.xml#L1485:~:text=The request `SalesOrder('A')/ns.GetRecommendations?Targets={"URLs":["","Items(10)"]}` retrieves recommendations for the entities `SalesOrder('A')` and `SalesOrder('A')/Items(10)`. +[URLs](./Common.xml#L1487:~:text=The request `SalesOrder('A')/ns.AIRecommendations?Targets={"URLs":["","Items(10)"]}` retrieves recommendations for the entities `SalesOrder('A')` and `SalesOrder('A')/Items(10)`. - -## [PropertyRecommendationType](./Common.xml#L1496:~:text= +## [PropertyAIRecommendationType](./Common.xml#L1496:~:text=The request `SalesOrder('A')/ns.GetRecommendations?Targets=...` might retrieve a recommendation with `"AIRecommendedFieldPath": "Items(10)/Product"`. -[AIRecommendedFieldValue](./Common.xml#L1506:~:text=If a value is recommended via property `AIRecommendedFieldValue`, it must be the first entry in this list. +[AIRecommendedFieldPath](./Common.xml#L1498:~:text=The request `SalesOrder('A')/ns.AIRecommendations?Targets=...` might retrieve a recommendation with `"AIRecommendedFieldPath": "Items(10)/Product"`. +[AIRecommendedFieldValue](./Common.xml#L1506:~:text=If a value is recommended via property `AIRecommendedFieldValue`, it must be the first entry in this list. - -## [AlternativeRecommendationType](./Common.xml#L1520:~:text= +## [AlternativeAIRecommendationType](./Common.xml#L1520:~:text= -## [RecommendationsRoleType](./Common.xml#L1533:~:text= +## [AIRecommendationsRoleType](./Common.xml#L1533:~:text=The function SHOULD compute the recommendations asynchronously, see [this diagram](../docs/recommendations.md). - + Implementations of this function MAY omit this parameter. @@ -1478,28 +1478,28 @@ If the request succeeds the response will contain a JSON body of `Content-Type: - + - + - The request `SalesOrder('A')/ns.GetRecommendations?Targets={"URLs":["","Items(10)"]}` + The request `SalesOrder('A')/ns.AIRecommendations?Targets={"URLs":["","Items(10)"]}` retrieves recommendations for the entities `SalesOrder('A')` and `SalesOrder('A')/Items(10)`. - + - + - The request `SalesOrder('A')/ns.GetRecommendations?Targets=...` + The request `SalesOrder('A')/ns.AIRecommendations?Targets=...` might retrieve a recommendation with `"AIRecommendedFieldPath": "Items(10)/Product"`. @@ -1510,14 +1510,14 @@ If the request succeeds the response will contain a JSON body of `Content-Type: - + If a value is recommended via property `AIRecommendedFieldValue`, it must be the first entry in this list. - + @@ -1526,11 +1526,11 @@ If the request succeeds the response will contain a JSON body of `Content-Type: - + - +