Major (May) Release

.github/workflows/PR-SAP.yml

@@ -18,7 +18,7 @@ jobs:
         run: |
           git config --global credential.helper "cache --timeout=3600"
           echo -e "url=https://user:${GH_TOKEN}@github.com\n" | git credential approve
-          echo -e "url=https://user:${GH_TOKEN_PARENT}@github.tools.sap\n" | git credential approve
+          echo -e "url=https://user:${GH_TOKEN_TOOLS_DOCS}@github.tools.sap\n" | git credential approve
           git clone --depth 1 --no-single-branch https://github.tools.sap/cap/docs docs
           cd docs
           git checkout $GITHUB_HEAD_REF || git checkout main
@@ -27,7 +27,7 @@ jobs:
           git checkout $GITHUB_HEAD_REF
         env:
           GH_TOKEN:        ${{ secrets.GITHUB_TOKEN }}
-          GH_TOKEN_PARENT: ${{ secrets.GH_TOKEN_PARENT }}
+          GH_TOKEN_TOOLS_DOCS: ${{ secrets.GH_TOKEN_TOOLS_DOCS }}
       - name: Use Node.js
         uses: actions/setup-node@v4
         with:
@@ -44,6 +44,7 @@ jobs:
         working-directory: docs
         env:
           NODE_OPTIONS: "--max-old-space-size=6144"
+          VITE_CAPIRE_CI_HOST: "github.com"
       - name: Find broken anchor links
         working-directory: docs
         run: |

.github/workflows/lint.yml

@@ -19,7 +19,7 @@ jobs:
       run: |
         git config --global credential.helper "cache --timeout=3600"
         echo -e "url=https://user:${GH_TOKEN}@github.com\n" | git credential approve
-        echo -e "url=https://user:${GH_TOKEN_PARENT}@github.tools.sap\n" | git credential approve
+        echo -e "url=https://user:${GH_TOKEN_TOOLS_DOCS}@github.tools.sap\n" | git credential approve
         git clone --depth 1 --no-single-branch https://github.tools.sap/cap/docs docs
         cd docs
         git checkout $GITHUB_HEAD_REF || git checkout main
@@ -28,7 +28,7 @@ jobs:
         git checkout $GITHUB_HEAD_REF
       env:
         GH_TOKEN:        ${{ secrets.GITHUB_TOKEN }}
-        GH_TOKEN_PARENT: ${{ secrets.GH_TOKEN_PARENT }}
+        GH_TOKEN_TOOLS_DOCS: ${{ secrets.GH_TOKEN_TOOLS_DOCS }}
     - name: Use Node.js
       uses: actions/setup-node@v4
       with:

.vitepress/config.js

@@ -70,7 +70,7 @@ const config = defineConfig({
 
   vite: {
     build: {
-      chunkSizeWarningLimit: 5000, // chunk for local search index dominates
+      chunkSizeWarningLimit: 6000, // chunk for local search index dominates
     },
     css: {
       preprocessorOptions: {
@@ -106,8 +106,8 @@ config.rewrites = rewrites
 // Add custom capire info to the theme config
 config.themeConfig.capire = {
   versions: {
-    java_services: '3.9.0',
-    java_cds4j: '3.9.0'
+    java_services: '3.10.1',
+    java_cds4j: '3.10.1'
   },
   gotoLinks: [],
   maven_host_base: 'https://repo1.maven.org/maven2'

.vitepress/theme/styles.scss

@@ -144,9 +144,7 @@ main {
 
     table {
       tr, th, td {
-        // &:nth-child(2n) {
-          background-color: transparent !important;
-        // }
+        background-color: var(--vp-c-bg);
       }
       td, th {
         border-color: #bbb; .dark & { border-color: #555 };
@@ -520,11 +518,6 @@ a.learn-more, p.learn-more, .learn-more {
 
 .VPBadge { white-space: nowrap; }
 
-/* remove transparency in the odd rows (when it scrolls over outline) */
-tr:nth-child(odd) {
-  background-color: var(--vp-c-bg);
-}
-
 html.java {
   & .node {
     display: none;
@@ -550,6 +543,10 @@ html.node {
   table:focus {
     min-width: fit-content;
   }
+  tr { // make wide rows go over outline, not below it
+    z-index: 1;
+    position: relative;
+  }
   [class*='language-'] pre {
     overflow: hidden !important;
   }

advanced/hana.md

@@ -50,7 +50,7 @@ Steps to match the signature of a database object in a facade entity:
 * For a view, table function, or calculation view with parameters, check that the parameter names and types match, too.
   Functions with table-like input parameters are not supported.
 
-> Note: If a field of that entity is defined as `not null` and you want to disable its runtime check, you can add [`@assert.notNull: false`](../guides/providing-services#assert-notnull). This is important if you want to use, for example [SAP HANA history tables](https://help.sap.com/docs/SAP_HANA_PLATFORM/6b94445c94ae495c83a19646e7c3fd56/d0b2c5142a19405fb912f71782cd0a84.html).
+> Note: If a field of that entity is defined as `not null` and you want to disable its runtime check, you can add `@assert.notNull: false`. This is important if you want to use, for example [SAP HANA history tables](https://help.sap.com/docs/SAP_HANA_PLATFORM/6b94445c94ae495c83a19646e7c3fd56/d0b2c5142a19405fb912f71782cd0a84.html).
 
 
 As a result, the database name is defined by the name of the entity or its elements, after applying the SQL name mapping.

advanced/odata.md

@@ -104,7 +104,7 @@ Content-Type: application/json
 
 PATCH requests with delta payload are executed using batch delete and [upsert](../java/working-with-cql/query-api#bulk-upsert) statements, and are more efficient than OData [batch requests](https://docs.oasis-open.org/odata/odata/v4.01/csprd02/part1-protocol/odata-v4.01-csprd02-part1-protocol.html#sec_BatchRequests).
 
-Use PATCH on entity collections for uploading mass data using a dedicated service, which is secured using [role-based authorization](../java/security#role-based-auth). Delta updates must be explicitly enabled by annotating the entity with
+Use PATCH on entity collections for uploading mass data using a dedicated service, which is secured using [role-based authorization](../guides/security/authorization#requires). Delta updates must be explicitly enabled by annotating the entity with
 
 ```cds
 @Capabilities.UpdateRestrictions.DeltaUpdateSupported
@@ -1060,14 +1060,13 @@ If the `groupby` transformation only includes a subset of the entity keys, the r
 | `aggregate`                  | aggregate values                            |        <X/>        | <X/>  |
 | `compute`                    | add computed properties to the result set   |       <Na/>        | <X/>  |
 | `expand`                     | expand navigation properties                |       <Na/>        | <Na/> |
-| `concat`                     | append additional aggregation to the result | <X/><sup>(1)</sup> | <X/>  |
-| `skip` / `top`               | paginate                                    | <X/><sup>(1)</sup> | <X/>  |
-| `orderby`                    | sort the input set                          | <X/><sup>(1)</sup> | <X/>  |
+| `concat`                     | append additional aggregation to the result |        <X/>        | <X/>  |
+| `skip` / `top`               | paginate                                    |        <X/>        | <X/>  |
+| `orderby`                    | sort the input set                          |        <X/>        | <X/>  |
 | `topcount`/`bottomcount`     | retain highest/lowest _n_ values            |       <Na/>        | <Na/> |
 | `toppercent`/`bottompercent` | retain highest/lowest _p_% values           |       <Na/>        | <Na/> |
 | `topsum`/`bottomsum`         | retain _n_ values limited by sum            |       <Na/>        | <Na/> |
 
-- <sup>(1)</sup> Supported with experimental feature `cds.features.odata_new_parser = true`
 
 #### `concat`
 
@@ -1139,6 +1138,71 @@ GET SalesOrganizations?$apply=
    /ancestors(..., ID, filter(contains(Name, 'New York')), keep start)
 ```
 
+#### Modeling Recursive Hierarchies
+
+Recursive hierarchies are parent-child hierarchies, where each entity references its parent and through that defines the hierarchical structure. A common example is a company organization structure or HR reporting, where each employee entity references another employee a as direct report or manager.
+
+##### Domain Model
+
+The simplest domain model looks as follows:
+
+```cds
+entity Employee : Hierarchy {
+  key ID       : UUID;
+      parent   : Association to Employee;
+      fullName : String;
+}
+
+aspect Hierarchy {
+  virtual LimitedDescendantCount : Integer64;
+  virtual DistanceFromRoot       : Integer64;
+  virtual DrillState             : String;
+  virtual LimitedRank            : Integer64;
+}
+```
+
+The entity `Employee` has the element `ID`, which identifies the hierarchy node. The `parent` association references the same entity, which establishes the parent-child relationship.
+
+##### Virtual Elements of a Hierarchy
+
+The `Hierarchy` aspect defines a set of virtual elements, automatically calculated by the backend at runtime, to describe the state of the hierarchy. This information is requested by the UI to correctly render the hierarchy in a *TreeTable* during user interaction.
+
+##### Service Model
+
+The following service defines the projection on the domain model.
+
+```cds
+service HRService {
+    entity HREmployee as projection on Employee;
+}
+```
+
+
+##### OData v4 Annotations for Fiori
+
+To link the backend and Fiori UI, the projected service entity must be enriched with the following annotations.
+
+```cds
+annotate HRService.HREmployee with @Aggregation.RecursiveHierarchy #EmployeeHierarchy: {
+    $Type: 'Aggregation.RecursiveHierarchyType',
+    NodeProperty: ID,
+    ParentNavigationProperty: parent
+};
+```
+
+Here the `EmployeeHierarchy` specifies a hierarchy qualifier, `NodeProperty` (identifying the hierarchy node) is linked to `ID` of the entity `HREmployee`, and the `ParentNavigationProperty` is linked to a corresponding `parent` association.
+
+```cds
+annotate HRService.HREmployee with @Hierarchy.RecursiveHierarchy #EmployeeHierarchy: {
+  $Type: 'Hierarchy.RecursiveHierarchyType',
+  LimitedDescendantCount: LimitedDescendantCount,
+  DistanceFromRoot: DistanceFromRoot,
+  DrillState: DrillState,
+  LimitedRank: LimitedRank
+};
+```
+
+Here the same qualifier `EmployeeHierarchy` is referenced to list the names of the [virtual elements of the hierarchy](#virtual-elements-of-a-hierarchy).
 
 ### Aggregation Methods
 

advanced/publishing-apis/asyncapi.md

@@ -110,6 +110,39 @@ service CatalogService {
 }
 ```
 
+## Extensions { #extensions}
+
+`@AsyncAPI.Extensions` can be used to provide arbitrary extensions. 
+If a specific annotation exists for a given extension, it takes precedence over the definition using @AsyncAPI.Extensions.
+For example, if both `@AsyncAPI.ShortText` and `@AsyncAPI.Extensions: { ![sap-shortText]: 'baz' }` are provided, the value from `@AsyncAPI.ShortText` will override the one defined in @AsyncAPI.Extensions.
+
+For example:
+
+```cds
+@AsyncAPI.Extensions   : {
+  ![foo-bar]                    : 'baz',
+  ![sap-shortText]              : 'Service Base 1'
+}
+
+service CatalogService {
+  @AsyncAPI.Extensions          : {
+    ![sap-event-source]           : '/{region}/sap.app.test'
+  }
+  event SampleEntity.Changed.v1 : projection on CatalogService.SampleEntity;
+}
+```
+
+The `@AsyncAPI.Extensions` annotation can be applied at both the service level and the event level.
+
+Since the AsyncAPI specification requires all extensions to be prefixed with `x-`, the compiler will automatically add this prefix. Therefore, do not include the `x-` prefix when specifying extensions in `@AsyncAPI.Extensions`.
+
+### Behavior with `--merged` flag
+
+When the `--merged` CLI flag is used:
+
+- Extensions defined via `@AsyncAPI.Extensions` on `services` are **ignored**.
+- Extensions defined via `@AsyncAPI.Extensions` on `events` remain effective and are applied as expected.
+
 ## Type Mapping { #mapping}
 
 CDS Type to AsyncAPI Mapping
@@ -120,15 +153,15 @@ CDS Type to AsyncAPI Mapping
 | `Boolean`                              | `{ "type": "boolean" }`                                                                             |
 | `Integer`                              | `{ "type": "integer" }`                                                                             |
 | `Integer64`                            | `{ "type": "string", "format": "int64" }`                                                           |
-| `Decimal`, `{precision, scale}`        | `{ "type": "string", "format": "decimal", "formatPrecision": <precision>, "formatScale": <scale> }` |
-| `Decimal`, without scale               | `{ "type": "string", "format": "decimal", "formatPrecision": <precision> }`                         |
+| `Decimal`, `{precision, scale}`        | `{ "type": "string", "format": "decimal", "x-sap-precision": <precision>, "x-sap-scale": <scale> }` |
+| `Decimal`, without scale               | `{ "type": "string", "format": "decimal", "x-sap-precision": <precision> }`                         |
 | `Decimal`, without precision and scale | `{ "type": "string", "format": "decimal" }`                                                         |
 | `Double`                               | `{ "type": "number" }`                                                                              |
 | `Date`                                 | `{ "type": "string", "format": "date" }`                                                            |
 | `Time`                                 | `{ "type": "string", "format": "partial-time" }`                                                    |
 | `DateTime`                             | `{ "type": "string", "format": "date-time" }`                                                       |
 | `Timestamp`                            | `{ "type": "string", "format": "date-time" }`                                                       |
-| `String`                               | `{ "type": "string", "maxLength": length }`                                                         |
-| `Binary`                               | `{ "type": "string", "maxLength": length }`                                                         |
+| `String`, `{maxLength}`                | `{ "type": "string", "maxLength": length }`                                                         |
+| `Binary`, `{maxLength}`                | `{ "type": "string", "maxLength": length }`                                                         |
 | `LargeBinary`                          | `{ "type": "string" }`                                                                              |
 | `LargeString`                          | `{ "type": "string" }`                                                                              |

cds/annotations.md

@@ -28,8 +28,6 @@ uacp: Used as link target from Help Portal at https://help.sap.com/products/BTP/
 
 | Annotation    | Description                                                      |
 |---------------|------------------------------------------------------------------|
-| `@readonly`   | see [Input Validation](../guides/providing-services#readonly)   |
-| `@insertonly` | see [Generic Handlers](../guides/providing-services)            |
 | `@restrict`   | see [Authorization](../guides/security/authorization#restrict-annotation) |
 | `@requires`   | see [Authorization](../guides/security/authorization#requires)            |
 
@@ -40,12 +38,9 @@ uacp: Used as link target from Help Portal at https://help.sap.com/products/BTP/
 |---------------------|----------------------------------------------------------------------|
 | `@readonly `        | see [Input Validation](../guides/providing-services#readonly)       |
 | `@mandatory`        | see [Input Validation](../guides/providing-services#mandatory)      |
-| `@assert.unique`    | see [Input Validation](../guides/providing-services#assert-unique)         |
-| `@assert.integrity` | see [Input Validation](../guides/databases#database-constraints)           |
 | `@assert.target`    | see [Input Validation](../guides/providing-services#assert-target)  |
 | `@assert.format`    | see [Input Validation](../guides/providing-services#assert-format)  |
 | `@assert.range`     | see [Input Validation](../guides/providing-services#assert-range)   |
-| `@assert.notNull`   | see [Input Validation](../guides/providing-services#assert-notnull) |
 
 
 
@@ -102,4 +97,3 @@ Intrinsically supported OData Annotations:
 | `@Core.IsMediaType`    | see [Media Data](../guides/providing-services#serving-media-data)                          |
 | `@Core.IsUrl`          | see [Media Data](../guides/providing-services#serving-media-data)                          |
 | `@Capabilities...`     | see [Fiori](../advanced/fiori)                                   |
-| `@Common.FieldControl` | see [Input Validation](../guides/providing-services#common-fieldcontrol) |

cds/cdl.md

@@ -302,20 +302,9 @@ entity Employees {
 ```
 
 The text of a doc comment is stored in CSN in the property `doc`.
-When generating OData EDM(X), it appears as value for the annotation `@Core.Description`.
-
-When generating output for deployment to SAP HANA, the first paragraph of a doc comment is translated to the HANA `COMMENT` feature for tables, table columns, and for views (but not for view columns):
-
-```sql
-CREATE TABLE Employees (
-  ID INTEGER,
-  name NVARCHAR(...) COMMENT 'I am the description for "name"'
-) COMMENT 'I am the description for "Employee"'
-```
-
-::: tip
-Propagation of doc comments can be stopped via an empty one: `/** */`.
-:::
+Doc comments are not propagated. For example, a doc comment defined for an entity
+isn't automatically copied to projections of this entity.
+When generating OData EDM(X), doc comments are translated to the annotation `@Core.Description`.
 
 In CAP Node.js, doc comments need to be switched on when calling the compiler:
 
@@ -331,13 +320,20 @@ cds.compile(..., { docs: true })
 
 :::
 
-::: tip Doc comments are enabled by default in CAP Java.
-In CAP Java, doc comments are automatically enabled by the [CDS Maven Plugin](../java/developing-applications/building#cds-maven-plugin). In generated interfaces they are [converted to corresponding Javadoc comments](../java/assets/cds-maven-plugin-site/generate-mojo.html#documentation).
+::: tip Doc comments are automatically enabled in CAP Java.
+In CAP Java, doc comments are automatically enabled by the [CDS Maven Plugin](../java/developing-applications/building#cds-maven-plugin).
+In generated interfaces they are [converted to corresponding Javadoc comments](../java/assets/cds-maven-plugin-site/generate-mojo.html#documentation).
 :::
 
+When generating output for deployment to SAP HANA, the first paragraph of a doc comment is translated
+to the HANA `COMMENT` feature for tables, table columns, and for views (but not for view columns):
 
-
-
+```sql
+CREATE TABLE Employees (
+  ID INTEGER,
+  name NVARCHAR(...) COMMENT 'I am the description for "name"'
+) COMMENT 'I am the description for "Employee"'
+```
 
 
 ## Entities & Type Definitions
@@ -808,6 +804,21 @@ By using a cast, annotations and other properties are inherited from the provide
 
 <div id="afterinferredsig" />
 
+### Virtual elements in views
+
+Virtual elements can be defined in views or projections like this:
+```cds
+entity SomeView as select from Employee {
+  // ...,
+  virtual virt1 : String(22),
+  virtual virt2  // virtual element without type
+}
+```
+These virtual elements have no relation to the query source `Employee` but are new fields
+in the view. Virtual elements in views or projections are handled as described in the
+section on [virtual elements in entities](#virtual-elements).
+
+
 <div id="beforeviewwithparam" />
 
 ### Views with Parameters

cds/cql.md

@@ -399,7 +399,7 @@ SQL casts and CDL casts. The former produces SQL casts when rendered into SQL, w
 SELECT cast (foo+1 as Decimal) as bar from Foo;  -- standard SQL
 SELECT from Foo { foo+1 as bar : Decimal };      -- CDL-style
 ```
-[learn more about CDL type definitions](./cdl#types){.learn-more}
+[Learn more about CDL type definitions](./cdl#types){.learn-more}
 
 Use SQL casts when you actually want a cast in SQL. CDL casts are useful for expressions such as `foo+1` as the compiler does not deduce types.
 For the OData backend, by specifying a type, the compiler will also assign the correct EDM type in the generated EDM(X) files.