February Release (#1684)

Author: renejeglinsky

.vitepress/config.js

@@ -101,8 +101,8 @@ config.rewrites = rewrites
 // Add custom capire info to the theme config
 config.themeConfig.capire = {
   versions: {
-    java_services: '3.7.1',
-    java_cds4j: '3.7.0'
+    java_services: '3.8.0',
+    java_cds4j: '3.8.0'
   },
   gotoLinks: [],
   maven_host_base: 'https://repo1.maven.org/maven2'

.vitepress/languages/log.tmLanguage.json

@@ -25,6 +25,10 @@
       "name": "comment.indented",
       "match": "^\\s+(?!___________________________)(.*)"
     },
+    {
+      "name": "comment.code",
+      "match": "//\\s*\\[\\!code.*$"
+    },
     {
       "begin": "\\{",
       "end": "\\}",

.vitepress/theme/components/ConfigInspect.vue

@@ -15,12 +15,13 @@
       </div>
       <div class="vp-code-group vp-doc" v-else>
         <CodeGroup :groups="[
-          { id: 'pkg-priv', label: '~/.cdsrc.json',  lang: 'json',       group, code: pkgStr, private: true },
-          { id: 'pkg', label: 'package/.cdsrc.json', lang: 'json',       group, code: pkgStr },
-          { id: 'js',  label: '.cdsrc.js',           lang: 'js',         group, code: jsStr },
-          { id: 'yml', label: '.cdsrc.yaml',         lang: 'yml',        group, code: ymlStr },
+          { id: 'pkg-rc',   label: 'package.json',   lang: 'json',       group, code: pkgStr },
+          { id: 'pkg-priv', label: '~/.cdsrc.json',  lang: 'json',       group, code: rcJsonStr, private: true },
+          { id: 'pkg',      label: '.cdsrc.json',    lang: 'json',       group, code: rcJsonStr },
+          { id: 'js',  label: '.cdsrc.js',           lang: 'js',         group, code: rcJsStr },
+          { id: 'yml', label: '.cdsrc.yaml',         lang: 'yml',        group, code: rcYmlStr },
           { id: 'env', label: '.env file',           lang: 'properties', group, code: propStr },
-          { id: 'shl', label: 'Linux/macOS Shells',  lang: 'sh',         group, code: envStr, transient: true },
+          { id: 'shl', label: 'Linux/macOS Shells',  lang: 'sh',         group, code: 'export '+envStr, transient: true },
           { id: 'shp', label: 'Powershell',          lang: 'powershell', group, code: '$Env:'+envStr, transient: true },
           { id: 'shw', label: 'Cmd Shell',           lang: 'cmd',        group, code: 'set '+envStr, transient: true }
         ]" />
@@ -53,19 +54,23 @@
           h('input', { type: 'radio', name: 'group', id: `${b.group}-${b.id}`, checked: idx === 0 }),
           h('label', { for: `${b.group}-${b.id}` }, b.label)
       ])),
-      h('div', { class: 'blocks' }, groups.flatMap((b, idx) => [
-        h('div', { class: ['language-'+b.lang, idx === 0 ? 'active': ''] }, [
-          h('button', { title: 'Copy Code', class: 'copy' }),
-          h('span', { class: 'lang' }, b.lang),
-          h('pre', { class: 'shiki' },
-            h('code',
-              h('span', { class: 'line' },
-                h('span', b.code)
+      h('div', { class: 'blocks' }, groups
+        .filter((b) => filesOnly ? !b.transient : true)
+        .filter((b) => showPrivate ? true : !b.private)
+        .flatMap((b, idx) => [
+          h('div', { class: ['language-'+b.lang, idx === 0 ? 'active': ''] }, [
+            h('button', { title: 'Copy Code', class: 'copy' }),
+            h('span', { class: 'lang' }, b.lang),
+            h('pre', { class: 'shiki' },
+              h('code',
+                h('span', { class: 'line' },
+                  h('span', b.code)
+                )
               )
             )
-          )
-        ])
-      ]))
+          ])
+        ]
+      ))
     ], {
       props: {
         groups: { type: Array<{id:string, group:string, code:string, label:string, lang:string, transient?:boolean, private?:boolean }>, required: true }
@@ -85,8 +90,9 @@
   const popperVisible = ref(false)
   const group = ref()
   const pkgStr = ref()
-  const jsStr = ref()
-  const ymlStr = ref()
+  const rcJsonStr = ref()
+  const rcJsStr = ref()
+  const rcYmlStr = ref()
   const propStr = ref()
   const envStr = ref()
   const javaAppyml = ref()
@@ -111,11 +117,16 @@
     const pkg = toJson(key, jsonVal ?? value)
 
     pkgStr.value = JSON.stringify(pkg, null, 2)
-    jsStr.value = 'module.exports = ' + pkgStr.value.replace(/"(\w*?)":/g, '$1:')
+    rcJsonStr.value = JSON.stringify(pkg.cds, null, 2)
+    rcJsStr.value = 'module.exports = ' + rcJsonStr.value.replace(/"(\w*?)":/g, '$1:')
+    rcYmlStr.value = yaml.stringify(pkg.cds)
     propStr.value = `${key}=${jsonVal ? JSON.stringify(jsonVal) : value}`
-    envStr.value = `${key.replaceAll('_', '__').replaceAll('.', '_').toUpperCase()}=${jsonVal ? JSON.stringify(jsonVal) : value}`
 
-    javaAppyml.value = ymlStr.value = yaml.stringify(pkg)
+    let envKey = key.replaceAll('_', '__').replaceAll('.', '_')
+    if (/^[a-z_]+$/.test(envKey)) envKey = envKey.toUpperCase() // only uppercase if not camelCase
+    envStr.value = `${envKey}=${jsonVal ? JSON.stringify(jsonVal) : value}`
+
+    javaAppyml.value = yaml.stringify(pkg)
     javaEnvStr.value = `-D${propStr.value}`
   })
 

.vitepress/theme/styles.scss

@@ -45,7 +45,7 @@
 
   --vp-c-text-1: #000;
   .VPHomeHero {
-    h1 { line-height: 1.2em; }
+    h1 span.name { line-height: 1.2em; }
   }
   h1, h2, h3, h4, h5 { color: rgba(60, 60, 67) }
   h6 { color: transparent; position: absolute; margin-top: -7.7em; right: 0px; } // we use h6 for alternative anchor targets

advanced/fiori.md

@@ -454,7 +454,7 @@ Adding the annotation `@fiori.draft.enabled` won't work if the corresponding `_t
 ![An SAP Fiori UI showing how a book is edited in the bookshop sample and that the translations tab is used for non-standard languages.](../assets/draft-for-localized-data.png){style="margin:0"}
 [See it live in **cap/samples**.](https://github.com/sap-samples/cloud-cap-samples/tree/main/fiori/app/admin-books/fiori-service.cds#L50){.learn-more}
 
-If you're editing data in multiple languages, the _General_ tab in the example above is reserved for the default language (often "en"). Any change to other languages has to be done in the _Translations_ tab, where a corresponding language can be chosen from a drop-down menu as illustrated above. This also applies if you use the URL parameter `sap-language` on the draft page.
+If you're editing data in multiple languages, the _General_ tab in the example above is reserved for the default language (often "en"). Any change to other languages has to be done in the _Translations_ tab, where a corresponding language can be chosen [from a drop-down menu](https://github.com/SAP-samples/cloud-cap-samples/blob/14ac3efaa13fc025f621b4eed369d03f1ca48341/fiori/app/admin-books/fiori-service.cds#L70) as illustrated above. This also applies if you use the URL parameter `sap-language` on the draft page.
 
 ### Validating Drafts
 

advanced/hybrid-testing.md

@@ -142,6 +142,10 @@ Only services that have the `shareable` flag in the metadata set to `true` can b
 See the [CloudFoundry docs](https://docs.cloudfoundry.org/devguide/services/sharing-instances.html) for further details.
 :::
 
+::: tip Allow dynamic deploy targets
+Service bindings created by `cds bind` contain the Cloud Foundry API endpoint, org, and space. You can allow your services to connect to the currently targeted Cloud Foundry org and space by removing these properties from the binding structure.
+:::
+
 ### Services on Kubernetes
 
 
@@ -522,31 +526,25 @@ No credentials are saved!
 In your CI/CD pipeline you can resolve the bindings and inject them into the test commands:
 
 ```sh
-# Install DK for "cds env"
-npm i @sap/cds-dk --no-save
-
 # Login
 cf auth $USER $PASSWORD
-
-## Uncomment if your service bindings have
-## no "org" and "space" set (see note below)
-# cf target -o $ORG -s $SPACE
+# Optional if your bindings have org and space removed to be agnostic
+cf target -o $ORG -s $SPACE
 
 # Set profile
-export CDS_ENV=integration-test
+export CDS_ENV=integration-test  # [!code highlight]
+
 # Set resolved bindings
-export cds_requires="$(cds env get requires --resolve-bindings)"
+export cds_requires="$(cds env get requires --resolve-bindings)"  # [!code highlight]
 
-# Execute test
-npm run integration-test
+# Run tests
+npm run integration-test  # [!code highlight]
 ```
 
-<!-- TODO: "cds deploy" should take the existing bindings for hana -->
-
-With `CDS_ENV`, you specify the configuration profile for the test, where you previously put the service binding configuration.
+Some comments to the previous snippet:
+- With `CDS_ENV` you specify the [configuration profile](../node.js/cds-env#profiles) for the test, where you previously put the service binding configuration.
+- [`cds env get requires`](../node.js/cds-env#services) prints the `requires` section of the configuration as a JSON string. Through `--resolve-bindings`, it includes the credentials of the service bindings from the cloud. To make the credentials available for all subsequent `cds` commands and the tests, the `requires` JSON string is put into the `cds_requires` script variable.
+- In `npm run integration-test` any test code can run, for example, [`cds.test`](../node.js/cds-test).
 
-`cds env get requires` prints the `requires` section of the configuration as a JSON string. By adding the `--resolve-bindings` option, it includes the credentials of the service bindings from the cloud. To make the credentials available for all subsequent `cds` commands and the tests, the `requires` JSON string is put into the `cds_requires` variable.
 
-::: tip Allow dynamic deploy targets
-Service bindings created by `cds bind` contain the Cloud Foundry API endpoint, org, and space. You can allow your services to connect to the currently targeted Cloud Foundry org and space by removing these properties from the binding structure.
-:::
+<!-- TODO: "cds deploy" should take the existing bindings for hana -->

advanced/odata.md

@@ -633,14 +633,48 @@ The CDS path `f.struc.y` is translated to the OData path `f/struc_y`:
 </Schema>
 ```
 
-::: warning Restrictions concerning the foreign key elements of managed associations
+#### Managed Associations
 
-1. Usually an annotation assigned to a managed association is copied to the foreign key elements of the association.
-This is a workaround for the lack of possibility to directly annotate a foreign key element.
-This copy mechanism is _not_ applied for annotations with expression values. So it is currently not possible
-to use expression-valued annotations for annotating foreign keys of a managed association.
+The OData backend translates managed associations into unmanaged ones plus explicit foreign key elements.
+During this translation, annotations assigned to the managed association are copied to the respective foreign key elements.
 
-2. In an expression-valued annotation, it is not possible to reference the foreign key element
+Example:
+```cds
+service S {
+  entity Authors { key ID : Integer; name : String; }
+  entity Books   { key ID : Integer; author : Association to Authors; }
+
+  annotate Books:author with @Common.Text: (author.name); 
+}
+```
+
+Resulting OData API:
+```xml
+<Schema Namespace="S">
+  <!-- ... -->
+  <EntityType Name="Authors">
+    <!-- ... -->
+    <Property Name="name" Type="Edm.String"/>
+  </EntityType>
+  <EntityType Name="Books">
+    <!-- ... -->
+    <NavigationProperty Name="author" Type="S.Authors"/>
+    <Property Name="author_ID" Type="Edm.Int32"/>
+  </EntityType>
+  <Annotations Target="S.Books/author_ID">
+    <Annotation Term="Common.Text" Path="author/name"/>
+  </Annotations>
+</Schema>
+```
+
+Instead of relying on this copy mechanism, you can also explicitly annotate a foreign key element:
+```cds
+annotate Books:author.ID with @Common.Text: ($self.author.name);  // here $self is necessary
+```
+
+::: warning Restriction concerning the foreign key elements of managed associations
+
+In an expression-valued annotation, it is not possible to reference the foreign key element
 of a managed association.
 
 :::
@@ -1187,6 +1221,7 @@ GET /Books?$apply=aggregate(stock with sum as stock) HTTP/1.1
 #### Currencies and Units of Measure
 
 If a property represents a monetary amount, it may have a related property that indicates the amount's *currency code*. Analogously, a property representing a measured quantity can be related to a *unit of measure*. To indicate that a property is a currency code or a unit of measure it can be annotated with the [Semantics Annotations](https://help.sap.com/docs/SAP_NETWEAVER_750/cc0c305d2fab47bd808adcad3ca7ee9d/fbcd3a59a94148f6adad80b9c97304ff.html) `@Semantics.currencyCode` or `@Semantics.unitOfMeasure`.
+The aggregation method (typically, sum) is specified with the `@Aggregation.default` annotation.
 
 ```cds
 @Aggregation.CustomAggregate#amount   : 'Edm.Decimal'
@@ -1195,6 +1230,7 @@ entity Sales {
     key id        : GUID;
         productId : GUID;
         @Semantics.amount.currencyCode: 'currency'
+        @Aggregation.default: #SUM
         amount    : Decimal(10,2);
         @Semantics.currencyCode
         currency  : String(3);

advanced/performance-modeling.md

@@ -207,9 +207,10 @@ GET http://localhost/odata/OrderItemsViewAssoc?$expand=Items&$select=OrderNo,Ite
 First sort on the `OrdersItems` and then join back to the `OrdersHeaders` with the help of an association:
 
 ```cds
-view SortedOrdersAssoc as select
-from OrdersItems {*, Header.OrderNo, Header.buyer, Header.currency }
-order by OrdersItems.title;
+view SortedOrdersAssoc as select {*, Header.OrderNo, Header.buyer, Header.currency } as Flatten 
+from (
+  select from OrdersItems {*} order by OrdersItems.title
+);
 ```
 
 #### **Bad**{.bad}
@@ -239,9 +240,11 @@ Basically, what is true for [Sorting](#sorting) is also valid for filtering.
 #### **Good**{.good}
 
 ```cds
-view FilteredOrdersAssoc as select
-from OrdersItems {*, Header.OrderNo, Header.buyer, Header.currency }
-where OrdersItems.price > 100;
+view FilteredOrdersAssoc as select {*, Header.OrderNo, Header.buyer, Header.currency } as Flatten
+from (
+  select from OrdersItems {*}
+  where OrdersItems.price > 100
+);
 ```
 
 #### **Bad**{.bad}
@@ -260,7 +263,7 @@ view FilteredOrdersJoin as select
 from OrdersHeaders JOIN OrdersItems on OrdersHeaders.ID = OrdersItems.Header.ID
 where price > 100;
 ```
-This query cannot utilize database indexes properly.
+This query needs to identify that prices can be filtered before the join. Filtering beforehand prevents the full join from being materialized and then reduced to a smaller subset.
 
 ## Calculated Fields
 Database operations on calculated fields cannot leverage any DB indexes.  This impacts performance significantly, as calculated fields cause full table scans.

advanced/publishing-apis/openapi.md

@@ -128,12 +128,12 @@ See [Frequently Asked Questions](#faq) for examples on how to use these annotati
 |   `/SortRestrictions/...`                         | EntitySet, Singleton | `$orderby` system query option for reading related entities via a navigation path                     |
 |   `/TopSupported`                                 | EntitySet, Singleton | `$top` system query option for reading contained entities via a navigation path                       |
 |   `/UpdateRestrictions/...`                       | EntitySet, Singleton | `PATCH` operation for modifying a contained entity via a navigation path                              |
-| `ReadByKeyRestrictions`<br />&emsp;`/Readable`              | EntitySet            | `GET` operation for reading a single entity by key                                                    |
 | &emsp;`/Description`                                        | EntitySet            | `summary` of Operation Object                                                                         |
 | &emsp;`/LongDescription`                                    | EntitySet            | `description` of Operation Object                                                                     |
 | `ReadRestrictions`<br />&emsp;`/Readable`                   | EntitySet, Singleton | `GET` operation for reading an entity set or singleton                                                |
 | &emsp;`/Description`                                        | EntitySet, Singleton | `summary` of Operation Object                                                                         |
 | &emsp;`/LongDescription`                                    | EntitySet, Singleton | `description` of Operation Object                                                                     |
+| &emsp;`ReadByKeyRestrictions`<br />&emsp;&emsp;`/Readable`  | EntitySet            | `GET` operation for reading a single entity by key                                                    |
 | `SearchRestrictions`<br />&emsp;`/Searchable`               | EntitySet            | `$search` system query option for `GET` operation                                                     |
 | `SelectSupport`<br />&emsp;`/Supported`                     | EntitySet, Singleton | `$select` system query option for `GET` operation                                                     |
 | `SkipSupported`                                             | EntitySet            | `$skip` system query option for `GET` operation                                                       |
@@ -170,17 +170,26 @@ This is an example of a CDS service annotated with the annotations above:
 annotate MyService with @(
   Authorization: {
     Authorizations: [
-      { $Type : 'Auth.Http', Name : 'Basic', Scheme : 'basic' },
-      { $Type : 'Auth.Http', Name : 'JWT',   Scheme : 'bearer', BearerFormat : 'JWT' },
+      { $Type : 'Authorization.Http', Name : 'Basic', Scheme : 'basic' },
+      { $Type : 'Authorization.Http', Name : 'JWT',   Scheme : 'bearer', BearerFormat : 'JWT' },
+      { $Type : 'Authorization.OAuth2ClientCredentials', Name : 'OAuth2',
+        Scopes     : [{
+          Scope      : 'some_scope',
+          Description: 'Scope description'
+        }],
+        RefreshUrl : 'https://some.host/oauth/token/refresh',
+        TokenUrl   : 'https://some.host/oauth/token'
+      },
     ],
     SecuritySchemes: [
       { Authorization : 'Basic' },
       { Authorization : 'JWT', RequiredScopes : [] },
+      { Authorization : 'OAuth2' },
     ]
   }
 );
 ```
-[See it in context.](https://github.com/chgeo/cds-swagger-ui-express/blob/e5794c55b53dd3e43ebe8ffcfff69341b6eac9c7/tests/app/services.cds#L23-L34){.learn-more}
+[See it in context.](https://github.com/chgeo/cds-swagger-ui-express/blob/651013b529168b30c024f8653c249f170ba9d114/tests/app/services.cds#L35-L55){.learn-more}
 
 
 ## [Common](https://github.com/SAP/odata-vocabularies/blob/main/vocabularies/Common.md)

cds/cdl.md

@@ -426,6 +426,20 @@ entity Books {
 }
 ```
 
+You can declare structured types based on other
+definitions using the `projection on` syntax.
+You can use nested projections or aliases as known from entity projections.
+Only the effective signature of the projection is relevant.
+
+<!-- cds-mode: upcoming -->
+```cds
+type CustomerData : projection on Customer {
+  name.firstName, // select from structures
+  name.lastName,
+  address as customerAddress, // aliases
+}
+```
+
 
 ### Arrayed Types
 
@@ -628,6 +642,14 @@ type Complex {
 }
 ```
 
+If the element has an enum type, you can use the enum symbol instead of a literal value:
+```cds
+type Status : String enum {open; closed;}
+entity Order {
+  status : Status default #open;
+}
+```
+
 
 ### Type References
 
@@ -2071,7 +2093,7 @@ service MyOrders { ...
 }
 ```
 
-An event can also be defined as projection on an entity, type, or another event.
+An event can also be defined as projection on an entity, structured type, or another event.
 Only the effective signature of the projection is relevant.
 ```cds
 service MyOrders { ...