Annotate return value

SAP · Oct 9, 2023 · 8b22fa5 · 8b22fa5
1 parent c4a1c00
commit 8b22fa5
Show file tree

Hide file tree

Showing 3 changed files with 71 additions and 12 deletions.
diff --git a/vocabularies/Common.json b/vocabularies/Common.json
@@ -1,5 +1,5 @@
 {
-  "$Version": "4.0",
+  "$Version": "4.01",
   "$Reference": {
     "https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Core.V1.json": {
       "$Include": [{ "$Namespace": "Org.OData.Core.V1", "$Alias": "Core" }]
@@ -1292,17 +1292,44 @@
     "Recommendation": {
       "$Kind": "Term",
       "$Type": "Edm.PrimitiveType",
+      "$AppliesTo": ["Property", "ReturnType"],
+      "@Common.Experimental": true,
+      "@Core.Description": "A recommended value for this property or in this returned value",
+      "@Validation.ApplicableTerms": ["Common.Text", "Common.RecommendationScore"]
+    },
+    "RecommendationScore": {
+      "$Kind": "Term",
+      "$Type": "Edm.Decimal",
       "$AppliesTo": ["Property"],
       "@Common.Experimental": true,
-      "@Core.Description": "A recommended value for this property",
-      "@Validation.ApplicableTerms": ["Common.Text"]
+      "@Core.Description": "Confidence score of a recommendation"
     },
     "RecommendationAlternatives": {
       "$Kind": "Term",
       "$Collection": true,
-      "$AppliesTo": ["Property"],
+      "$Type": "Edm.Untyped",
+      "$AppliesTo": ["Property", "ReturnType"],
       "@Common.Experimental": true,
-      "@Core.Description": "Alternative recommended values for this property"
+      "@Core.Description": "Alternative recommended values for this property or in this returned value",
+      "@Validation.DerivedTypeConstraint": [
+        "Edm.Binary",
+        "Edm.Boolean",
+        "Edm.Byte",
+        "Edm.Date",
+        "Edm.DateTimeOffset",
+        "Edm.Decimal",
+        "Edm.Double",
+        "Edm.Duration",
+        "Edm.Guid",
+        "Edm.Int16",
+        "Edm.Int32",
+        "Edm.Int64",
+        "Edm.SByte",
+        "Edm.Single",
+        "Edm.String",
+        "Edm.TimeOfDay"
+      ],
+      "@Validation.ApplicableTerms": ["Common.Text", "Common.RecommendationScore"]
     }
   }
 }
diff --git a/vocabularies/Common.md b/vocabularies/Common.md
@@ -110,8 +110,9 @@ Term|Type|Description
 [mediaUploadLink](./Common.xml#L1427:~: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#L1442:~: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#L1447:~:text=<Term%20Name="-,WebSocketBaseURL,-") *([Experimental](Common.md#Experimental))*|URL|<a name="WebSocketBaseURL"></a>Base URL for WebSocket connections
-[Recommendation](./Common.xml#L1453:~:text=<Term%20Name="-,Recommendation,-") *([Experimental](Common.md#Experimental))*|PrimitiveType|<a name="Recommendation"></a>A recommended value for this property<br>Can be annotated with:<br>- [Text](#Text)
-[RecommendationAlternatives](./Common.xml#L1462:~:text=<Term%20Name="-,RecommendationAlternatives,-") *([Experimental](Common.md#Experimental))*|\[String\]|<a name="RecommendationAlternatives"></a>Alternative recommended values for this property
+[Recommendation](./Common.xml#L1453:~:text=<Term%20Name="-,Recommendation,-") *([Experimental](Common.md#Experimental))*|PrimitiveType|<a name="Recommendation"></a>A recommended value for this property or in this returned value<br>Can be annotated with:<br>- [Text](#Text)<br>- [RecommendationScore](#RecommendationScore)
+[RecommendationScore](./Common.xml#L1463:~:text=<Term%20Name="-,RecommendationScore,-") *([Experimental](Common.md#Experimental))*|Decimal|<a name="RecommendationScore"></a>Confidence score of a recommendation
+[RecommendationAlternatives](./Common.xml#L1467:~:text=<Term%20Name="-,RecommendationAlternatives,-") *([Experimental](Common.md#Experimental))*|\[Untyped\]|<a name="RecommendationAlternatives"></a>Alternative recommended values for this property or in this returned value<br>Can be annotated with:<br>- [Text](#Text)<br>- [RecommendationScore](#RecommendationScore)
 
 <a name="TextFormatType"></a>
 ## [TextFormatType](./Common.xml#L116:~:text=<EnumType%20Name="-,TextFormatType,-")

diff --git a/vocabularies/Common.xml b/vocabularies/Common.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<edmx:Edmx xmlns:edmx="http://docs.oasis-open.org/odata/ns/edmx" Version="4.0">
+<edmx:Edmx xmlns:edmx="http://docs.oasis-open.org/odata/ns/edmx" Version="4.01">
   <edmx:Reference Uri="https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Core.V1.xml">
     <edmx:Include Alias="Core" Namespace="Org.OData.Core.V1" />
   </edmx:Reference>
@@ -1450,18 +1450,49 @@ If the request succeeds the response will contain a JSON body of `Content-Type:
         <Annotation Term="Core.Description" String="Base URL for WebSocket connections" />
       </Term>
 
-      <Term Name="Recommendation" Type="Edm.PrimitiveType" Nullable="false" AppliesTo="Property">
+      <Term Name="Recommendation" Type="Edm.PrimitiveType" Nullable="false" AppliesTo="Property ReturnType">
         <Annotation Term="Common.Experimental" />
-        <Annotation Term="Core.Description" String="A recommended value for this property" />
+        <Annotation Term="Core.Description" String="A recommended value for this property or in this returned value" />
         <Annotation Term="Validation.ApplicableTerms">
           <Collection>
             <String>Common.Text</String>
+            <String>Common.RecommendationScore</String>
           </Collection>
         </Annotation>
       </Term>
-      <Term Name="RecommendationAlternatives" Type="Collection(Edm.String)" Nullable="false" AppliesTo="Property">
+      <Term Name="RecommendationScore" Type="Edm.Decimal" Scale="variable" Nullable="false" AppliesTo="Property">
         <Annotation Term="Common.Experimental" />
-        <Annotation Term="Core.Description" String="Alternative recommended values for this property" />
+        <Annotation Term="Core.Description" String="Confidence score of a recommendation" />
+      </Term>
+      <Term Name="RecommendationAlternatives" Type="Collection(Edm.Untyped)" Nullable="false" AppliesTo="Property ReturnType">
+        <Annotation Term="Common.Experimental" />
+        <Annotation Term="Core.Description" String="Alternative recommended values for this property or in this returned value" />
+        <Annotation Term="Validation.DerivedTypeConstraint">
+          <Collection>
+            <String>Edm.Binary</String>
+            <String>Edm.Boolean</String>
+            <String>Edm.Byte</String>
+            <String>Edm.Date</String>
+            <String>Edm.DateTimeOffset</String>
+            <String>Edm.Decimal</String>
+            <String>Edm.Double</String>
+            <String>Edm.Duration</String>
+            <String>Edm.Guid</String>
+            <String>Edm.Int16</String>
+            <String>Edm.Int32</String>
+            <String>Edm.Int64</String>
+            <String>Edm.SByte</String>
+            <String>Edm.Single</String>
+            <String>Edm.String</String>
+            <String>Edm.TimeOfDay</String>
+          </Collection>
+        </Annotation>
+        <Annotation Term="Validation.ApplicableTerms">
+          <Collection>
+            <String>Common.Text</String>
+            <String>Common.RecommendationScore</String>
+          </Collection>
+        </Annotation>
       </Term>
 
     </Schema>