Annotation expressions go GA (#2012)

Co-authored-by: Mahati Shankar <93712176+smahati@users.noreply.github.com>
Co-authored-by: Rene Jeglinsky <rene.jeglinsky@sap.com>

Author: 3 people

advanced/odata.md

@@ -542,12 +542,21 @@ The second example is for a (record type) term in the [Communication vocabulary]
 ```
 
 
-### Expressions <Beta /> { #expression-annotations }
+### Expressions { #expression-annotations }
 
 If the value of an OData annotation is an [expression](../cds/cdl#expressions-as-annotation-values),
 the OData backend provides improved handling of references and automatic mapping from
 CDS expression syntax to OData expression syntax.
 
+One of the main use cases for such dynamic expressions is SAP Fiori. Examples:
+```cds
+@UI.Hidden: (status <> 'visible')
+@UI.CreateHidden : (to_Travel.TravelStatus.code != #Open)
+```
+
+Note that SAP Fiori supports dynamic expressions only for
+[specific annotations](https://ui5.sap.com/#/topic/0e7b890677c240b8ba65f8e8d417c048).
+
 #### Flattening
 
 In contrast to [simple references](#references), the references in expression-like
@@ -672,12 +681,54 @@ Instead of relying on this copy mechanism, you can also explicitly annotate a fo
 annotate Books:author.ID with @Common.Text: ($self.author.name);  // here $self is necessary
 ```
 
-::: warning Restriction concerning the foreign key elements of managed associations
+A path that addresses a key element in the target of a managed association is always rewritten
+to address the local foreign key element.
 
-In an expression-valued annotation, it is not possible to reference the foreign key element
-of a managed association.
+Example:
+```cds
+service S {
+  entity Travels {
+    key id : Integer;
+    status : Association to TravelStatus;
+  };
+  entity TravelStatus {
+    key code : String(1) enum {Open = 'O'; Accepted = 'A'; Canceled = 'X'; };
+  }
+  @UI.CreateHidden : (travel.status.code != #Open) // [!code highlight]
+  entity Bookings {
+    key id : Integer;
+    travel : Association to Travels;
+  }
+}
+```
+
+Resulting OData API:
+```xml
+<Schema Namespace="S">
+  <!-- ... -->
+  <EntityType Name="Travels">
+    <!-- ... -->
+    <NavigationProperty Name="status" Type="S.TravelStatus"/>
+    <Property Name="status_code" Type="Edm.String" MaxLength="1"/> <!-- [!code highlight] -->
+  </EntityType>
+  <EntityType Name="TravelStatus">
+    <!-- ... -->
+  </EntityType>
+  <EntityType Name="Bookings">
+    <!-- ... -->
+    <NavigationProperty Name="travel" Type="S.Travels"/>
+  </EntityType>
+  <Annotations Target="S.Bookings">
+    <Annotation Term="UI.CreateHidden">
+      <Ne>
+        <Path>travel/status_code</Path> <!-- [!code highlight] -->
+        <String>O</String>
+      </Ne>
+    </Annotation>
+  </Annotations>
+</Schema>
+```
 
-:::
 
 #### Expression Translation
 
@@ -873,10 +924,19 @@ In any case, the resulting EDMX is:
 </Annotation>
 ```
 
-### Dynamic Expressions { #dynamic-expressions}
+### EDM JSON Expression Syntax { #dynamic-expressions}
+
+::: tip Use CDS expression syntax
 
-OData supports dynamic expressions in annotations.
-For OData annotations you can use the "edm-json inline mechanism" by providing a [dynamic expression](https://docs.oasis-open.org/odata/odata-csdl-json/v4.01/odata-csdl-json-v4.01.html#_Toc38466479) as defined
+Use the EDM JSON expression syntax only as fallback mechanism.
+Whenever possible, use [expression-like annotation values](#expression-annotations) instead.
+For the example below, simply write `@UI.Hidden: (status <> 'visible')`.
+
+:::
+
+In case you want to have an expression as value for an OData annotation that cannot be
+written as a [CDS expression ](#expression-annotations), 
+you can use the "edm-json inline mechanism" by providing an [EDM JSON expression](https://docs.oasis-open.org/odata/odata-csdl-json/v4.01/odata-csdl-json-v4.01.html#_Toc38466479) as defined
 in the [JSON representation of the OData Common Schema Language](https://docs.oasis-open.org/odata/odata-csdl-json/v4.01/odata-csdl-json-v4.01.html) enclosed in `{ $edmJson: { ... }}`.
 
 Note that here the CDS syntax for string literals with single quotes (`'foo'`) applies,
@@ -901,19 +961,6 @@ is translated to:
 </Annotation>
 ```
 
-One of the main use cases for such dynamic expressions is SAP Fiori,
-but note that SAP Fiori supports dynamic expressions only for
-[specific annotations](https://ui5.sap.com/#/topic/0e7b890677c240b8ba65f8e8d417c048).
-
-::: tip Use expression-like annotation values
-
-Instead of writing annotations directly with EDM JSON syntax,
-try using [expression-like annotation values](#expression-annotations), which
-are automatically translated. For the example above you would
-simply write `@UI.Hidden: (status <> 'visible')`.
-
-:::
-
 
 ### `sap:` Annotations
 

cds/cdl.md

@@ -1384,7 +1384,7 @@ Propagation of annotations can be stopped via value `null`, for example, `@anno:
 :::
 
 
-### Expressions as Annotation Values <Beta /> {#expressions-as-annotation-values}
+### Expressions as Annotation Values {#expressions-as-annotation-values}
 
 In order to use an expression as an annotation value, it must be enclosed in parentheses:
 ```cds
@@ -1481,7 +1481,7 @@ and a value written as expression `@aValueExpr: ( 11 )`, respectively.
 If the annotation value is an expression, it is sometimes necessary to adapt references inside the expression
 during propagation, for example, when a referenced element is renamed in a projection.
 The compiler automatically takes care of the necessary rewriting. When a reference in an annotation expression
-is rewritten, the `=` property is set to `true`.
+is rewritten, the `=` property is adapted accordingly if the expression is a single reference, otherwise it is set to `true`.
 
 Example:
 ```cds
@@ -1530,9 +1530,9 @@ rewritten to `@Common.Text: (descr)`.
 
 ::: info
 
-There are situations where automatic rewriting doesn't work, resulting in the compiler error
+There may be situations where automatic rewriting doesn't work, resulting in the compiler error
 [`anno-missing-rewrite`](https://cap.cloud.sap/docs/cds/compiler/messages#anno-missing-rewrite).
-Some of these situations are going to be addressed in upcoming releases.
+In these cases you can overwrite the annotation with the correct expression in the new location.
 
 :::