December Release

.vitepress/config.js

@@ -106,8 +106,8 @@ config.rewrites = rewrites
 // Add custom capire info to the theme config
 config.themeConfig.capire = {
   versions: {
-    java_services: '4.5.0',
-    java_cds4j: '4.5.0'
+    java_services: '4.6.0',
+    java_cds4j: '4.6.0'
   },
   gotoLinks: []
 }

.vitepress/theme/components/Alpha.vue

@@ -1,7 +1,7 @@
 <template>
-  <Badge
-    type="warning"
-    text="alpha"
+  <StatusBadge
+    type="danger"
+    text="Alpha"
     title="Alpha features are experimental. They may never be generally available. If released subsequently, the APIs and behavior might change."
   />
 </template>

.vitepress/theme/components/Beta.vue

@@ -1,7 +1,7 @@
 <template>
-  <Badge
+  <StatusBadge
     type="warning"
-    text="beta"
+    text="Beta"
     title="Beta features are planned to be generally available in subsequent releases, however, APIs and their behavior are not final and may change in the general release."
   />
 </template>

.vitepress/theme/components/Concept.vue

@@ -1,7 +1,7 @@
 <template>
-  <Badge
-    type="warning"
-    text="concept"
+  <StatusBadge
+    type="info"
+    text="Concept"
     title="Concept features are ideas for potential future enhancements and an opportunity for you to give feedback. This is not a commitment to implement the feature though."
   />
 </template>

.vitepress/theme/components/Gamma.vue

@@ -0,0 +1,7 @@
+<template>
+  <StatusBadge
+    type="tip"
+    text="Gamma"
+    title="Gamma features are finalized and ready to use, stable, and supported long term. Yet, as they have a broad scope and range, you should ensure to test them thoroughly."
+  />
+</template>

.vitepress/theme/components/Since.vue

@@ -1,5 +1,9 @@
 <template>
-  <Badge type="info" :text="`since ${of} ${version}`" :title="`This feature is only available as of ${of} version ${version} or higher.`" />
+  <StatusBadge
+    type="tip"
+    :text="`Since ${of} ${version}`"
+    :title="`This feature is only available as of ${of} version ${version} or higher.`"
+  />
 </template>
 
 <script setup lang="ts">

.vitepress/theme/components/StatusBadge.vue

@@ -0,0 +1,17 @@
+<template>
+  <Badge
+    :type="type"
+    :text="text"
+    :title="title"
+    @click="click" style="cursor: pointer"
+  />
+</template>
+
+<script setup lang="ts">
+defineProps<{ type: string, text:string, title:string  }>()
+
+import { withBase } from 'vitepress'
+function click() {
+  location.href = withBase('../get-started/learning-sources#feature-status-badges')
+}
+</script>

.vitepress/theme/index.ts

@@ -3,8 +3,10 @@ import { EnhanceAppContext } from 'vitepress';
 import Layout from './Layout.vue';
 import IndexList from './components/IndexList.vue';
 import ImplVariantsHint from './components/implvariants/ImpVariantsHint.vue';
+import StatusBadge from './components/StatusBadge.vue';
 import Alpha from './components/Alpha.vue';
 import Beta from './components/Beta.vue';
+import Gamma from './components/Gamma.vue';
 import Concept from './components/Concept.vue'
 import Since from './components/Since.vue';
 import UnderConstruction from './components/UnderConstruction.vue';
@@ -25,8 +27,10 @@ export default {
     ctx.app.component('Config', CfgInspect)
     ctx.app.component('IndexList', IndexList)
     ctx.app.component('ImplVariantsHint', ImplVariantsHint)
+    ctx.app.component('StatusBadge', StatusBadge)
     ctx.app.component('Alpha', Alpha)
     ctx.app.component('Beta', Beta)
+    ctx.app.component('Gamma', Gamma)
     ctx.app.component('Concept', Concept)
     ctx.app.component('Since', Since)
     ctx.app.component('UnderConstruction', UnderConstruction)

.vitepress/theme/styles.scss

@@ -535,7 +535,19 @@ a.learn-more, p.learn-more, .learn-more {
   }
 }
 
-.VPBadge { white-space: nowrap; }
+.VPBadge {
+  &.tip { 
+    background-color: #ced; color: #031; .dark & { 
+      background-color: #031; color: #9ca; 
+    } 
+  }
+  margin-top: 3px !important;
+  padding: 0 0.7em !important;
+  font-size: 80%;
+  line-height: 1.5em; 
+  border-radius: 1.5em;
+  white-space: nowrap; 
+}
 
 html.java {
   & .node {

about/features.md

@@ -115,7 +115,7 @@ Following is an index of the features currently covered by CAP, with status and
 | [Streaming & Media Types](../guides/providing-services#serving-media-data)                 | <X/>  |  <X/>   | <X/> |
 | [Conflict Detection through _ETags_](../guides/providing-services#etag)                    | <X/>  |  <X/>   | <X/> |
 | [Authentication via JWT](../guides/security/authorization#prerequisite-authentication)     | <Na/> |  <X/>   | <X/> |
-| [Basic Authentication](../guides/security/authorization#prerequisite-authentication)       | <Na/> |  <X/>   | <X/> |
+| [Mocked Authentication](../guides/security/authorization#prerequisite-authentication)      | <Na/> |  <X/>   | <X/> |
 
 
 <br>

advanced/fiori.md

@@ -745,9 +745,9 @@ Cache Control feature is currently supported on the Java runtime only.
 
 ## Hierarchical Tree Views
 
-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 as a direct report or manager.
+Recursive hierarchies are parent-child related structures: 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 as a direct report or manager.
 
-A generic hierarchy implementation for hierarchies is available on all relational datases supported by the CAP runtimes.
+A generic hierarchy implementation for hierarchies is available on all relational databases supported by the CAP runtimes.
 
 ::: warning
 On H2, only small hierarchies should be used for performance reasons.
@@ -761,6 +761,7 @@ Let's assume we have the following domain model and its projection in a service:
 namespace my.bookshop;
 
 entity Genres { //...
+  ID : UUID;
   parent : Association to Genres;
 }
 ```
@@ -774,19 +775,67 @@ service AdminService {
 ```
 :::
 
+In this example, there is a managed to-one association `parent` that defines the parent-child hierarchy
+based on a single key element. In such a situation you can define the Tree View via the annotation `@hierarchy`:
 
-Annotate/extend the entity in the service as follows:
+```cds
+annotate AdminService.Genres with @hierarchy : parent;
+```
+
+If the entity contains only one such association, you can even omit the value:
+
+```cds
+annotate AdminService.Genres with @hierarchy;
+```
+
+Configure the TreeTable in UI5's _manifest.json_ file:
+
+```jsonc
+  "sap.ui5": { ...
+    "routing": { ...
+      "targets": { ...
+        "GenresList": { ...
+          "options": {
+            "settings": { ...
+              "controlConfiguration": {
+                "@com.sap.vocabularies.UI.v1.LineItem": {
+                  "tableSettings": {
+                    "hierarchyQualifier": "GenresHierarchy", // [!code focus]
+                    "type": "TreeTable" // [!code focus]
+                  }
+                }
+              }
+            }
+          }
+        },
+      },
+    },
+```
+
+> Note: construct the `hierarchyQualifier` with the following pattern: <br>
+> `<entity name in service>Hierarchy`
+
+You can now start the server with `cds watch` and see the hierarchical tree view in action in the [_Browse Genres_](http://localhost:4004/fiori-apps.html#Genres-display) app.
+
+![Fiori UI with hierarchical tree view.](assets/hierarchical-tree-view.png) {style="filter: drop-shadow(0 2px 5px rgba(0,0,0,.40));"}
+
+The compiler automatically expands the shortcut annotation `@hierarchy` to the
+following `annotate` and `extend` statements. 
+
+### Manual Approach
+
+The following documents what happens behind the scenes, done by the compiler as described before. You can also use it, if you cannot use the `@hierarchy` annotation, for example, because you only have an unmanaged parent association.
 
 ```cds
 // declare a hierarchy with the qualifier "GenresHierarchy"
-annotate AdminService.Genres with @Aggregation.RecursiveHierarchy #GenresHierarchy : {
+annotate AdminService.Genres with @Aggregation.RecursiveHierarchy #GenresHierarchy: {
   NodeProperty             : ID,    // identifies a node, usually the key
   ParentNavigationProperty : parent // navigates to a node's parent
 };
 
 extend AdminService.Genres with @(
   // The computed properties expected by Fiori to be present in hierarchy entities
-  Hierarchy.RecursiveHierarchy #GenresHierarchy : {
+  Hierarchy.RecursiveHierarchy #GenresHierarchy: {
     LimitedDescendantCount : LimitedDescendantCount,
     DistanceFromRoot       : DistanceFromRoot,
     DrillState             : DrillState,
@@ -797,7 +846,7 @@ extend AdminService.Genres with @(
     'LimitedDescendantCount', 'DistanceFromRoot', 'DrillState', 'LimitedRank'
   ],
   // Disallow sorting on these properties from Fiori UIs
-  Capabilities.SortRestrictions.NonSortableProperties    : [
+  Capabilities.SortRestrictions.NonSortableProperties: [
     'LimitedDescendantCount', 'DistanceFromRoot', 'DrillState', 'LimitedRank'
   ],
 ) columns { // Ensure we can query these columns from the database
@@ -811,31 +860,5 @@ extend AdminService.Genres with @(
 > Note: When naming the hierarchy qualifier, use the following pattern: <br>
 > `<entity name in service>Hierarchy`
 
-Configure the TreeTable in UI5's _manifest.json_ file:
-
-```jsonc
-  "sap.ui5": { ...
-    "routing": { ...
-      "targets": { ...
-        "GenresList": { ...
-          "options": {
-            "settings": { ...
-              "controlConfiguration": {
-                "@com.sap.vocabularies.UI.v1.LineItem": {
-                  "tableSettings": {
-                    "hierarchyQualifier": "GenresHierarchy", // [!code focus]
-                    "type": "TreeTable" // [!code focus]
-                  }
-                }
-              }
-            }
-          }
-        },
-      },
-    },
-```
-
-> Note: use the `hierarchyQualifier` declared earlier
-
 <div id="reserved-words" />
 

advanced/publishing-apis/openapi.md

@@ -97,11 +97,15 @@ See [Frequently Asked Questions](#faq) for examples on how to use these annotati
 | `Description`      | Action, ActionImport, Function, FunctionImport                                | `summary` of Operation Object                                     |
 | `Description`      | EntitySet, Singleton                                                          | `description` of Tag Object                                       |
 | `Description`      | EntityType                                                                    | `title` of Request Body Object                                    |
-| `Description`      | ComplexType, EntityType, EnumerationType, Parameter, Property, TypeDefinition | `title` of Schema Object                                          |
+| `Description`      | ComplexType, EntityType, EnumerationType, TypeDefinition                      | `title` of Schema Object                                          |
+| `Description`      | Parameter                                                                     | `description` of Parameter Object (fallback if `LongDescription` not present) |
+| `Description`      | Property                                                                      | `description` of Schema Object (fallback if `LongDescription` not present) |
 | `Description`      | Schema, EntityContainer                                                       | `info.title`                                                      |
 | `Example`          | Property                                                                      | `example` of Schema Object                                        |
 | `Immutable`        | Property                                                                      | omit from Update structure                                        |
 | `LongDescription`  | Action, ActionImport, Function, FunctionImport                                | `description` of Operation Object                                 |
+| `LongDescription`  | Parameter                                                                     | `description` of Parameter Object                                 |
+| `LongDescription`  | Property                                                                      | `description` of Schema Object                                    |
 | `LongDescription`  | Schema, EntityContainer                                                       | `info.description`                                                |
 | `Permissions:Read` | Property                                                                      | omit read-only properties from Create and Update structures       |
 | `SchemaVersion`    | Schema                                                                        | `info.version`                                                    |

cds/annotations.md

@@ -36,11 +36,11 @@ 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)       |
-| `@mandatory`        | see [Input Validation](../guides/providing-services#mandatory)      |
-| `@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)   |
+| `@readonly `        | see [Input Validation](../guides/services/constraints#readonly)       |
+| `@mandatory`        | see [Input Validation](../guides/services/constraints#mandatory)      |
+| `@assert.target`    | see [Input Validation](../guides/services/constraints#assert-target)  |
+| `@assert.format`    | see [Input Validation](../guides/services/constraints#assert-format)  |
+| `@assert.range`     | see [Input Validation](../guides/services/constraints#assert-range)   |
 
 
 
@@ -91,8 +91,8 @@ Intrinsically supported OData Annotations:
 
 | Annotation             | Description                                                      |
 |------------------------|------------------------------------------------------------------|
-| `@Core.Computed`       | see [Providing Services](../guides/providing-services#readonly) |
-| `@Core.Immutable`      | see [Providing Services](../guides/providing-services#readonly) |
+| `@Core.Computed`       | see [Providing Services](../guides/services/constraints#readonly) |
+| `@Core.Immutable`      | see [Providing Services](../guides/services/constraints#readonly) |
 | `@Core.MediaType`      | see [Media Data](../guides/providing-services#serving-media-data)                          |
 | `@Core.IsMediaType`    | see [Media Data](../guides/providing-services#serving-media-data)                          |
 | `@Core.IsUrl`          | see [Media Data](../guides/providing-services#serving-media-data)                          |