Skip to content

Annotation expressions go GA #2012

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 7 commits into
base: main
Choose a base branch
from
Open

Annotation expressions go GA #2012

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
90b60b4
Clarirfy that EDM JSON expressions are only a fallback
stewsk Aug 7, 2025
cc13633
edit
stewsk Aug 7, 2025
fe2511e
edit
stewsk Aug 7, 2025
3b3b958
add example
stewsk Aug 21, 2025
344114b
Merge branch 'main' into edmx-expressions
stewsk Aug 21, 2025
0f1e5b3
Remove "beta" and explain FK access
stewsk Aug 21, 2025
9510d78
Merge branch 'main' into edmx-expressions
stewsk Aug 22, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
89 changes: 68 additions & 21 deletions advanced/odata.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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,
Expand All @@ -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

Expand Down
8 changes: 4 additions & 4 deletions cds/cdl.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.

:::

Expand Down
Loading