@sap/cds-dk 10.1.2 → 10.2.0

package/node_modules/@sap/cds-compiler/doc/EffectiveCSN.md

@@ -0,0 +1,3314 @@
+# Effective CSN
+
+> **Status:** feature - implemented, up-to-date, Sep 2026
+
+<!-- toc: start -->
+
+1. [Introduction](#introduction)
+2. [How to obtain Effective CSN](#how-to-obtain-effective-csn)
+    1. [Via compiler CLI (`cdsc`)](#via-compiler-cli-cdsc)
+    2. [Via compiler API](#via-compiler-api)
+3. [Options](#options)
+4. [Starting point: "Inferred CSN"](#starting-point-inferred-csn)
+    1. [Full and complete model](#full-and-complete-model)
+    2. [Extensions and Includes are applied](#extensions-and-includes-are-applied)
+    3. [Composition of aspect is unfolded](#composition-of-aspect-is-unfolded)
+    4. [Annotations are propagated](#annotations-are-propagated)
+    5. [Inferred elements are computed for views and projections](#inferred-elements-are-computed-for-views-and-projections)
+    6. [Localized elements are unfolded](#localized-elements-are-unfolded)
+    7. [Effective CSN feature/flavor "Service Exposure Rendering"](#effective-csn-featureflavor-service-exposure-rendering)
+5. [Further transformations](#further-transformations)
+    1. [Upper/lower case](#upperlower-case)
+    2. [Stay with CDS type system](#stay-with-cds-type-system)
+    3. [Resolve simple types](#resolve-simple-types)
+    4. [Flatten structured types](#flatten-structured-types)
+    5. [Resolve Managed Associations](#resolve-managed-associations)
+    6. [Keep array types (many)](#keep-array-types-many)
+    7. [Cleanup: remove no longer needed objects and attributes](#cleanup-remove-no-longer-needed-objects-and-attributes)
+    8. [Virtual elements](#virtual-elements)
+    9. [Enums](#enums)
+    10. [Session variables](#session-variables)
+    11. [Actions and Functions](#actions-and-functions)
+    12. [Associations via backlink](#associations-via-backlink)
+    13. [Calculated Elements](#calculated-elements)
+    14. [$calc](#calc)
+    15. [Draft](#draft)
+    16. [Queries](#queries)
+    17. [Query: No assoc2join](#query-no-assoc2join)
+    18. [Query: EXISTS paths](#query-exists-paths)
+    19. [Query: CDL style cast](#query-cdl-style-cast)
+    20. [Query: $projection](#query-projection)
+    21. [Query: select *](#query-select-)
+    22. [Query: filter](#query-filter)
+    23. [Query: expand and inline](#query-expand-and-inline)
+    24. [Query: path in FROM](#query-path-in-from)
+    25. [Query: path in WHERE, GROUP BY](#query-path-in-where-group-by)
+    26. [Query: Projection vs View](#query-projection-vs-view)
+    27. [Query: Mixin associations](#query-mixin-associations)
+    28. [Query: Redirect](#query-redirect)
+    29. [Query: Defining associations in the select list](#query-defining-associations-in-the-select-list)
+    30. [Query: Exposing associations](#query-exposing-associations)
+    31. [Annotations](#annotations)
+    32. [Localized metadata](#localized-metadata)
+    33. [Reduce to one service](#reduce-to-one-service)
+
+<!-- toc: end -->
+
+
+
+## Introduction
+
+This document describes "Effective CSN", i.e. the CSN produced by the `for.effective` compiler function.
+
+The term "Effective CSN" means that this CSN is designed for consumption. It is __not__ intended for further
+modelling, and it is also not intended to be extended, as everything is already expanded/unfolded/computed/...
+
+The main purpose is to produce a CSN that can be consumed by parties outside of CAP by transforming
+CAP-specific features (for example, managed associations) into generally understood representations.
+
+Effective CSN is produced by starting with the core compiler CSN ("Inferred CSN" or "Client CSN")
+and then applying additional transformations, which are described in detail below.
+
+This document only describes enumerable properties of Effective CSN. If you look directly
+at the JSON object as it is returned from the respective compiler function, there may
+also be additional non-enumerable properties. These non-enumerable properties are not
+part of the stable, documented API and may change at any time.
+
+
+## How to obtain Effective CSN
+
+### Via compiler CLI (`cdsc`)
+
+After installing `@sap/cds-compiler` (see the README for install instructions), the `cdsc` binary
+is available on the PATH. Use the `forEffective` command:
+
+```sh
+cdsc forEffective <file.cds>
+```
+
+Options can be passed as `--<optionName>` flags, e.g.:
+
+```sh
+cdsc forEffective --resolveProjections <file.cds>
+```
+
+Run `cdsc --help` for a full list of commands and flags.
+
+### Via compiler API
+
+The function is exposed as `for.effective` on the compiler API:
+
+```js
+const cds = require('@sap/cds-compiler');
+
+const inferredCsn = cds.compileSync(['<file.cds>'], dir, {});
+const effectiveCsn = cds.for.effective(inferredCsn, options);
+```
+
+`inferredCsn` is a CSN object (e.g. the result of `cds.compileSync(...)`) and
+`options` is an optional object with any of the supported option keys (see [Options](#options) below).
+
+
+## Options
+
+The following options are supported by `for.effective`:
+
+| Option                  | Description |
+|-------------------------|-------------|
+| `resolveSimpleTypes`    | experimental, see section [Resolve simple types](#resolve-simple-types) |
+| `resolveProjections`    | see section [Query: Projection vs View](#query-projection-vs-view) |
+| `keepLocalized`         | see section [Localized elements are unfolded](#localized-elements-are-unfolded) |
+| `effectiveServiceName`  | see section [Reduce to one service](#reduce-to-one-service) |
+| `stringifyAnnoXpr`      | see section [Annotations](#annotations) |
+
+
+## Starting point: "Inferred CSN"
+
+The CSN generated by the CDS compiler ("Inferred CSN" or "client CSN") already has the
+features/flavors described in the following sections.
+
+
+### Full and complete model
+
+The Inferred CSN contains the full model. There are no dangling references.
+
+Note: `cds build` compiles CDS files from the _db_, _srv_, and _app_ folders.
+Thus also annotations (e.g. labels) from the _app_ folder get into the Effective CSN.
+
+
+### Extensions and Includes are applied
+
+All extends, annotates, and includes are applied.
+
+Inferred CSN still contains
+* named aspects
+* annotates that cannot be applied
+
+For Effective CSN, a cleanup is done (see section [Cleanup](#cleanup-remove-no-longer-needed-objects-and-attributes)),
+where for example aspects and unapplied annotations are removed.
+
+Example:  
+CDS:
+```cds
+aspect A { x : Integer; };
+entity E : A {}
+extend E with { y : Integer; }
+annotate E:x with @Foo;
+annotate E:miss with @Foo;
+```
+
+<details>
+  <summary>Inferred CSN</summary>
+
+```json
+{
+  "definitions": {
+    "A": {
+      "kind": "aspect",
+      "elements": {
+        "x": { "type": "cds.Integer" }
+      }
+    },
+    "E": {
+      "kind": "entity",
+      "includes": ["A"],
+      "elements": {
+        "x": {"@Foo": true,
+              "type": "cds.Integer"},
+        "y": {"type": "cds.Integer"}
+      }
+    }
+  },
+  "extensions": [
+    {
+      "annotate": "E",
+      "elements": {
+        "miss": { "@Foo": true }
+      }
+    }
+  ]
+}
+```
+
+</details>
+
+<details>
+  <summary>Effective CSN</summary>
+
+```json
+{
+  "definitions": {
+    "E": {
+      "kind": "entity",
+      "elements": {
+        "x": {"@Foo": true,
+              "type": "cds.Integer"},
+        "y": {"type": "cds.Integer"}
+      }
+    }
+  }
+}
+```
+</details>
+
+
+### Composition of aspect is unfolded
+
+All "composition of aspect" are unfolded, i.e. respective child entities are generated
+and linked to the parent entity via a managed `up_` association.
+
+For Effective CSN, in a later step [Resolve Managed Associations](#resolve-managed-associations)
+the managed associations are converted to unmanaged ones and `targetAspect` properties
+are removed during [Cleanup](#cleanup-remove-no-longer-needed-objects-and-attributes).
+
+
+Example:  
+CDS:
+```cds
+aspect A { x : Integer; };
+
+entity E {
+  key id : Integer;
+  c1 : Composition of many A;                // named aspect
+  c2 : Composition of many { x : Integer; }  // anonymous aspect
+}
+```
+
+<details>
+  <summary>Inferred CSN</summary>
+
+```jsonc
+{
+  "definitions": {
+    "A": {
+      "kind": "aspect",
+      "elements": {
+        "x": { "type": "cds.Integer" }
+      }
+    },
+    "E": {
+      "kind": "entity",
+      "elements": {
+        "id": {"key": true, "type": "cds.Integer"},
+        "c1": {
+          "type": "cds.Composition",
+          "cardinality": { "max": "*" },
+          "targetAspect": "A",
+          "target": "E.c1",
+          "on": [{"ref": ["c1","up_"]}, "=", {"ref": ["$self"]}]
+        },
+        "c2": {
+          "type": "cds.Composition",
+          "cardinality": { "max": "*" },
+          "targetAspect": {
+            "elements": {
+              "x": { "type": "cds.Integer" }
+            }
+          },
+          "target": "E.c2",
+          "on": [{"ref": ["c2","up_"]}, "=", {"ref": ["$self"]}]
+        }
+      }
+    },
+    "E.c1": {
+      "kind": "entity",
+      "elements": {
+        "up_": {
+          "key": true,
+          "type": "cds.Association",
+          "cardinality": { "min": 1, "max": 1 },
+          "target": "E",
+          "keys": [{"ref": ["id"]}],
+          "notNull": true
+        },
+        "x": {"type": "cds.Integer"}
+      }
+    },
+    "E.c2": {
+      /* like E.c1 */
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+  <summary>Effective CSN</summary>
+
+```json
+{
+  "definitions": {
+    "E": {
+      "kind": "entity",
+      "elements": {
+        "id": {"key": true, "type": "cds.Integer"},
+        "c1": {
+          "type": "cds.Composition",
+          "cardinality": {"max": "*"},
+          "target": "E.c1",
+          "on": [{"ref": ["c1","up_"]},"=",{"ref": ["$self"]}]
+        },
+        "c2": {
+          "type": "cds.Composition",
+          "cardinality": {"max": "*"},
+          "target": "E.c2",
+          "on": [{"ref": ["c2","up_"]},"=",{"ref": ["$self"]}]
+        }
+      }
+    },
+    "E.c1": {
+      "kind": "entity",
+      "elements": {
+        "up_": {
+          "type": "cds.Association",
+          "cardinality": {"min": 1,"max": 1},
+          "target": "E",
+          "on": [{"ref": ["up_","id"]},"=",{"ref": ["up__id"]}]
+        },
+        "up__id": {
+          "type": "cds.Integer",
+          "notNull": true,
+          "key": true
+        },
+        "x": {"type": "cds.Integer"}
+      }
+    },
+    "E.c2": {
+      /* like E.c1 */
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+  <summary>CDS source equivalent to Effective CSN</summary>
+
+```cds
+entity E {
+  key id: Integer;
+  c1 : Composition of many E.c1 on c1.up_ = $self;
+  c2 : Composition of many E.c2 on c2.up_ = $self;
+}
+entity E.c1 {
+  up_: Association to one E on up_.id = up__id;
+  key up__id : Integer;
+  x : Integer;
+}
+entity E.c2 {
+  up_: Association to one E on up_.id = up__id;
+  key up__id : Integer;
+  x : Integer;
+}
+```
+</details>
+
+
+### Annotations are propagated
+
+All annotations are explicitly inherited/propagated along type chains, views/projections, and includes.
+
+Example:  
+CDS:
+```cds
+@Foo
+type T : Integer;
+
+@FromAspect
+aspect A {};
+
+entity E {
+  @Bar
+  a : T;
+}
+
+entity P as select from E { a };
+```
+
+<details>
+  <summary>Inferred CSN</summary>
+
+```json
+{
+  "definitions": {
+    "T": {
+      "kind": "type",
+      "@Foo": true,
+      "type": "cds.Integer"
+    },
+    "A": {
+      "kind": "aspect",
+      "@FromAspect": true,
+      "elements": {}
+    },
+    "E": {
+      "kind": "entity",
+      "@FromAspect": true,
+      "includes": [
+        "A"
+      ],
+      "elements": {
+        "a": {"@Bar": true, "@Foo": true, "type": "T"}
+      }
+    },
+    "P": {
+      "kind": "entity",
+      "@FromAspect": true,
+      "query": {
+        "SELECT": {
+          "from": {"ref": ["E"]},
+          "columns": [
+            {"ref": ["a"]}
+          ]
+        }
+      },
+      "elements": {
+        "a": {"@Bar": true, "@Foo": true, "type": "T"}
+      }
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+  <summary>Effective CSN</summary>
+
+Here [types are already resolved](#resolve-simple-types).
+```json
+{
+  "definitions": {
+    "E": {
+      "kind": "entity",
+      "@FromAspect": true,
+      "elements": {
+        "a": {"@Bar": true, "@Foo": true, "type": "cds.Integer"}
+      }
+    },
+    "P": {
+      "kind": "entity",
+      "@FromAspect": true,
+      "query": {
+        "SELECT": {
+          "from": {"ref": ["E"]},
+          "columns": [
+            {"ref": ["a"]}
+          ]
+        }
+      },
+      "elements": {
+        "a": {"@Bar": true, "@Foo": true, "type": "cds.Integer"}
+      }
+    }
+  }
+}
+```
+</details>
+
+
+### Inferred elements are computed for views and projections
+
+Inferred elements are computed for views and projections. They are not computed
+for the single queries inside the view/projection.
+
+Example: see other examples with views/projections.
+
+
+### Localized elements are unfolded
+
+For localized elements, the corresponding text entity and associations are generated.
+
+Example:  
+CDS:
+```cds
+entity E {
+  key id : Integer;
+  t1 : localized String;
+  t2 : localized String;
+}
+```
+<details>
+  <summary>Inferred CSN</summary>
+
+```json
+{
+  "definitions": {
+    "E": {
+      "kind": "entity",
+      "elements": {
+        "id": {"key": true,"type": "cds.Integer" },
+        "t1": {"localized": true,"type": "cds.String"},
+        "t2": {"localized": true,"type": "cds.String"},
+        "texts": {
+          "type": "cds.Composition",
+          "cardinality": {"max": "*"},
+          "target": "E.texts",
+          "on": [{"ref": ["texts","id"]},"=",{"ref": ["id"]}]
+        },
+        "localized": {
+          "type": "cds.Association",
+          "target": "E.texts",
+          "on": [
+            {"ref": ["localized","id"]}, "=", {"ref": ["id"]},
+            "and",
+            {"ref": ["localized","locale"]}, "=", {"ref": ["$user","locale"]}
+          ]
+        }
+      }
+    },
+    "E.texts": {
+      "kind": "entity",
+      "elements": {
+        "locale": {"key": true,"type": "cds.String","length": 14},
+        "id": {"key": true,"type": "cds.Integer"},
+        "t1": {"localized": null,"type": "cds.String"},
+        "t2": {"localized": null,"type": "cds.String"}
+      }
+    }
+  }
+}
+```
+
+</details>
+
+By default, in Effective CSN the property `localized` is removed.
+
+<details>
+  <summary>Effective CSN </summary>
+
+Effective CSN looks like Inferred CSN, except that
+* property `localized: true` is removed from `E:t1` and `E:t2`.
+* property `localized: null` is removed from `E:texts.t1` and `E:texts.t2`.
+</details>
+
+<details>
+  <summary>CDS source equivalent to Effective CSN</summary>
+
+```cds
+entity E {
+  key id : Integer;
+  t1 : String;
+  t2 : String;
+  texts : Composition of many E.texts on texts.id = id;
+  localized : Association to one E.texts on localized.id = id and localized.locale = $user.locale;
+}
+entity E.texts {
+  key locale : String(14);
+  key id : Integer;
+  t1 : String;
+  t2 : String;
+}
+```
+
+</details>
+
+When option `keepLocalized` is set to `true` (default is `false`),
+the property `localized` is kept and there is no difference between Inferred CSN and Effective CSN.
+
+
+<br />
+
+#### Unsolved problem: Localized data in effective CSN
+
+Above the layer of base entities, where we have associations `texts` and `localized`,
+the model (CSN) usually contains no information about how to obtain the translations
+for a given localized element:
+* Associations `texts` and `localized` are not propagated automatically. If wanted,
+  users have to explicitly propagate them through the view stack.
+* If a view selects localized elements from two or more data sources, there is no
+  canonic `localized` or `texts` association any more that points to
+  the respective localized texts.
+* If a calculated field contains localized data, it effectively is also depending
+  on the locale, but there is no model info about how to get the corresponding translations.
+
+CAP today generates localized convenience views in the SQL persistence.
+They implicitly contain the knowledge about how to get translated texts
+throughout the view stack and provide the CAP runtimes with simple access to them.
+But these views are considered as an implementation detail and are represented neither
+in effective CSN nor in inferred CSN.
+
+This means: In a view/projection entity in effective CSN, we may see whether an element is
+localized or not, but we have no information on how to obtain the respective translated data.
+This is a missing piece if we for example want to use effective CSN to define an API service.
+
+
+### Effective CSN feature/flavor "Service Exposure Rendering"
+
+For entities in a service, the compiler applies auto-redirection and auto-exposure
+when producing Inferred CSN.
+
+#### Auto-redirection
+
+If an entity in a service has an association/composition with a target outside of the service, the compiler
+tries to find a suitable "redirection target" inside the service. A suitable redirection target
+is a view or projection on top of the original target, or an entity that includes the original target
+(this is a simplified explanation, but we don't go into the details here).
+If a suitable redirection target is found, the association/composition is automatically redirected to the new target.
+
+<details>
+  <summary>Example</summary>
+
+CDS:
+```cds
+entity E {
+  key id : Integer;
+  f : Association to F on f.id = id;
+  g : Association to G on g.id = id;
+}
+
+entity F {
+  key id : Integer;
+}
+
+entity G {
+  key id : Integer;
+}
+
+service S {
+  entity PE as projection on E;
+  entity PF as projection on F;
+}
+```
+
+Inferred CSN:
+```jsonc
+{
+  "definitions": {
+    "E": {
+      "kind": "entity",
+      "elements": {
+        "id": {"key": true, "type": "cds.Integer"},
+        "f": {
+          "type": "cds.Association",
+          "target": "F",
+          "on": [{"ref": ["f","id"]}, "=", {"ref": ["id"]}]
+        },
+        "g": {
+          "type": "cds.Association",
+          "target": "G",
+          "on": [{"ref": ["g","id"]}, "=", {"ref": ["id"]}]
+        }
+      }
+    },
+    "F": {
+      "kind": "entity",
+      "elements": {
+        "id": {"key": true, "type": "cds.Integer"}
+      }
+    },
+    "G": {
+      "kind": "entity",
+      "elements": {
+        "id": {"key": true, "type": "cds.Integer"}
+      }
+    },
+    "S": {
+      "kind": "service"
+    },
+    "S.PE": {
+      "kind": "entity",
+      "projection": {
+        "from": {"ref": ["E"]}
+      },
+      "elements": {
+        "id": {"key": true,"type": "cds.Integer"},
+        "f": {
+          "type": "cds.Association",
+          "target": "PF",            // has been redirected
+          "on": [{"ref": ["f","id"]},"=",{"ref": ["id"]}]
+        },
+        "g": {
+          "type": "cds.Association",
+          "target": "G",             // still has target outside of service
+          "on": [{"ref": ["g","id"]},"=",{"ref": ["id"]}]
+        }
+      }
+    },
+    "S.PF": {
+      "kind": "entity",
+      "projection": {
+        "from": {"ref": ["F"]}
+      },
+      "elements": {
+        "id": {"key": true, "type": "cds.Integer"}
+      }
+    }
+  }
+}
+```
+</details>
+
+
+#### Auto-exposure
+
+If for a composition no suitable redirection target is found, the compiler generates a
+projection on top of the original target in the service and redirects the composition to it.  
+If for an association no suitable redirection target is found but the original target
+is annotated with `@cds.autoexpose : true`, the compiler generates a projection on top of the
+original target in the service and redirects the association to it.
+
+If after auto-redirection and auto-exposure an association still points to a target outside
+of the service, this association is by default not removed but kept as is.
+When option `effectiveServiceName` is used to reduce the output to one service, such
+associations are removed (see section [Reduce to one service](#reduce-to-one-service)).
+
+
+## Further transformations
+
+Based on the Inferred CSN produced by the compiler, the following transformations are applied
+when producing Effective CSN.
+
+
+### Upper/lower case
+
+Names are kept as they are in the model (usually camel case).
+
+
+### Stay with CDS type system
+
+No transformation applied for Effective CSN.
+
+Keep the [CDS types](https://cap.cloud.sap/docs/cds/types#built-in-types). Don't map to e.g. HANA types.
+
+CAP CDS allows to define elements of type String and Binary without a length.
+When translating to SQL, for these elements a configurable default length is added.
+_No_ default length is added for Effective CSN.
+
+CAP CDS has the type `cds.UUID`. For SQL it is translated to a `cds.String(36)`. In Effective CSN it stays `cds.UUID`.
+
+
+### Resolve simple types
+
+By default, all references to simple types are resolved up to the respective primitive type
+(also in CDL style casts, in entity parameters, and in action/function definitions).
+Simple type definitions are removed from the CSN.
+
+Example:  
+CDS:
+```cds
+type T : Integer;
+type T2 : T;
+type T3 : T2;
+entity E {
+  a : T;
+  b : T3;
+  c : type of b;
+  d : type of c;
+  e : type of F:x;  // also cross-entity
+}
+entity F {
+  x : T;
+} actions {
+  action A(par: T2) returns T3;
+}
+entity V (par: T3) as select from E {
+  a : T3
+}
+```
+
+<details>
+  <summary>Inferred CSN</summary>
+
+Inferred CSN still contains the original type info.
+```jsonc
+{
+  "definitions": {
+    "T": {"kind": "type", "type": "cds.Integer"},
+    "T2": {"kind": "type", "type": "T"},
+    "T3": {"kind": "type", "type": "T2"},
+    "E": {
+      "kind": "entity",
+      "elements": {
+        "a": {"type": "T"},
+        "b": {"type": "T3"},
+        "c": {"type": {"ref": ["E", "b"]}},
+        "d": {"type": {"ref": ["E", "c"]}},
+        "e": {"type": {"ref": ["F", "x"]}}
+      }
+    },
+    "F": {
+      "kind": "entity",
+      "elements": {
+        "x": {"type": "T"}
+      },
+      "actions": {
+        "A": {
+          "kind": "action",
+          "params": {
+            "par": {"type": "T2"}
+          },
+          "returns": {"type": "T3"}
+        }
+      }
+    },
+    "V": {
+      "kind": "entity",
+      "params": {
+        "par": {"type": "T3"}
+      },
+      "query": {
+        "SELECT": {
+          "from": {"ref": ["E"]},
+          "columns": [{
+            "ref": ["a"], "cast": {"type": "T3"}
+          }]
+        }
+      },
+      "elements": {
+        "a": {"type": "T3"}
+      }
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+  <summary>Effective CSN</summary>
+
+```json
+{
+  "definitions": {
+    "E": {
+      "kind": "entity",
+      "elements": {
+        "a": {"type": "cds.Integer"},
+        "b": {"type": "cds.Integer"},
+        "c": {"type": "cds.Integer"},
+        "d": {"type": "cds.Integer"},
+        "e": {"type": "cds.Integer"}
+      }
+    },
+    "F": {
+      "kind": "entity",
+      "elements": {
+        "x": {"type": "cds.Integer"}
+      },
+      "actions": {
+        "A": {
+          "kind": "action",
+          "params": {
+            "par": {"type": "cds.Integer"}
+          },
+          "returns": {"type": "cds.Integer"}
+        }
+      }
+    },
+    "V": {
+      "kind": "entity",
+      "params": {
+        "par": {"type": "cds.Integer"}
+      },
+      "query": {
+        "SELECT": {
+          "from": {"ref": ["E"]},
+          "columns": [{
+            "ref": ["a"], "cast": {"type": "cds.Integer"}
+          }]
+        }
+      },
+      "elements": {
+        "a": {"type": "cds.Integer"}
+      }
+    }
+  }
+}
+```
+</details>
+
+#### Option `resolveSimpleTypes`
+
+When option `resolveSimpleTypes` is set to `false` (default is `true`), references to simple types
+are not resolved and the simple type definitions are kept. In this case, there is no difference
+between Inferred CSN and Effective CSN.
+The behavior for simple types is not completely consistent when this option is set to `false`.
+
+
+> [!WARNING]
+> This option is __experimental__ and must not be used for productive use cases.
+> You must not rely on the resulting CSN representation.
+> Name and behavior of this option may change in the future.
+
+
+#### Note on references to built-in types
+
+In CAP, a CSN may contain references to built-in types (deprecated, should only occur in old CSNs).
+In Effective CSN, such references are replaced by the built-in types themselves:
+```json
+"elements": {
+  "a": { "type": { "ref": ["cds.Integer"]} }
+}
+```
+Effective CSN:
+```json
+"elements": {
+  "a": {"type": "cds.Integer"}
+}
+```
+
+#### Note on managed associations
+
+A named type can also be a managed association:
+```cds
+type MyAssoc : Association to E;
+```
+References to such types are resolved, too, and in a later step [Resolve Managed Associations](#resolve-managed-associations)
+the managed association is turned into an unmanaged one.
+
+This happens even if option `resolveSimpleTypes` is set to `false`. However, the behavior of such types
+when this experimental option is disabled is undefined, and consumers must not rely on the resulting
+CSN representation.
+
+
+#### Note on retaining type information in the future
+
+Having the simple types in the CSN in principle is desired in order to retain
+the semantic information that is inherent to a type. But CDS allows type chains, which
+are quite complicated to handle. So, for the time being, the types are resolved.
+
+As a workaround, one could add annotations like
+```cds
+@workaround: 'I am a T'
+type T : Integer;
+```
+
+
+### Flatten structured types
+
+Type references to structured types are resolved.
+Structured elements are flattened, all references are adapted accordingly.
+Definitions of named structured types are removed from the CSN.
+
+Example:  
+CDS:
+```cds
+type S {
+  x : Integer;
+  y : Integer;
+};
+type S2 : S;
+
+entity E {
+  s : S2;
+  t {
+    x : Integer;
+    y : Integer;
+  }
+  e : Association to E on e.t.x = s.y;
+}
+```
+
+<details>
+  <summary>Effective CSN</summary>
+
+```json
+{
+  "definitions": {
+    "E": {
+      "kind": "entity",
+      "elements": {
+        "s_x": {"type": "cds.Integer"},
+        "s_y": {"type": "cds.Integer"},
+        "t_x": {"type": "cds.Integer"},
+        "t_y": {"type": "cds.Integer"},
+        "e": {
+          "type": "cds.Association",
+          "target": "E",
+          "on": [{"ref": ["e", "t_x"]}, "=", {"ref": ["s_y"]}]
+        }
+      }
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+  <summary>CDS source equivalent to Effective CSN</summary>
+
+```cds
+entity E {
+  s_x : Integer;
+  s_y : Integer;
+  t_x : Integer;
+  t_y : Integer;
+  e : Association to E on e.t_x = s_y;
+}
+```
+
+</details>
+
+<br />
+
+References to the leaves of structured elements are adapted, e.g. in views.
+
+CDS:
+```cds
+entity V1 as select from E {
+  s.x  // resulting element name is x
+} where s.x = t.y group by s.x;
+```
+
+<details>
+  <summary>Effective CSN</summary>
+
+```jsonc
+{
+  "definitions": {
+    "E": { /*...*/ },
+    "V1": {
+      "kind": "entity",
+      "query": {
+        "SELECT": {
+          "from": {"ref": ["E"]},
+          "columns": [
+            { "ref": ["s_x"], "as": "x" }
+          ],
+          "groupBy": [{"ref": ["s_x"]}],
+          "where": [{"ref": ["s_x"]}, "=", {"ref": ["t_y"]}]
+        }
+      },
+      "elements": {
+        "x": {"type": "cds.Integer"}
+      }
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+  <summary>CDS source equivalent to Effective CSN</summary>
+
+```cds
+entity V1 as select from E {
+  s_x as x
+} where s_x = t_y group by s_x;
+```
+
+</details>
+
+<br />
+
+References to the structured elements themselves are expanded.
+
+CDS:
+```cds
+entity V2 as select from E {
+  s
+} where s = t group by s;
+```
+
+<details>
+  <summary>Effective CSN</summary>
+
+```jsonc
+{
+  "definitions": {
+    "E": { /*...*/ },
+    "V2": {
+      "kind": "entity",
+      "query": {
+        "SELECT": {
+          "from": {"ref": ["E"]},
+          "columns": [
+            {"ref": ["E","s_x"]},
+            {"ref": ["E","s_y"]}
+          ],
+          "groupBy": [{"ref": ["E","s_x"]}, {"ref": ["E","s_y"]}],
+          "where": [{"xpr": [{"ref": ["s_x"]}, "=", {"ref": ["t_x"]},
+                             "and",
+                             {"ref": ["s_y"]}, "=", {"ref": ["t_y"]}]}]
+        }
+      },
+      "elements": {
+        "s_x": {"type": "cds.Integer"},
+        "s_y": {"type": "cds.Integer"}
+      }
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+  <summary>CDS source equivalent to Effective CSN</summary>
+
+```cds
+entity V2 as select from E {
+  E.s_x,
+  E.s_y
+} where s_x = t_x and s_y = t_y group by E.s_x, E.s_y;
+```
+
+</details>
+
+<br />
+
+
+#### View parameters
+
+Currently, a structured parameter leads to an error.
+This may change in the future, so that flattening is also applied to view parameters.
+
+<details>
+  <summary>Example</summary>
+
+CDS:
+```cds
+type S {
+  x : Integer;
+  y : Integer;
+}
+entity E {
+  key id : Integer;
+  s : S;
+}
+
+entity V ( p1 : S, p2 : { x : Integer; y : Integer; })
+as select from E {
+  id
+} where s = :p1;
+```
+
+Could result in this Effective CSN:
+```cds
+entity E {
+  key id : Integer;
+  s_x : Integer;
+  s_y : Integer;
+}
+
+entity V ( p1_x : Integer, p1_y : Integer, p2_x : Integer, p2_y : Integer)
+as select from E {
+  id
+} where s_x = :p1_x and s_y = :p1_y;
+```
+</details>
+
+#### Action/function parameters
+
+The behavior of non-primitive action and function parameters in effective CSN
+is __not defined__. Behavior may change in the future.
+
+Current behavior: Structures are inlined, but not flattened. If a structure
+contains a managed association, it is converted to an unmanaged one plus explicit FK.
+
+
+### Resolve Managed Associations
+
+Managed associations are converted to unmanaged associations, and explicit foreign key elements are added.
+The `keys` array (added by the compiler in Inferred CSN) vanishes.
+
+Example:  
+CDS:
+```cds
+entity E {
+  f : Association to F;
+}
+entity F { key id : Integer; x : Integer; }
+```
+
+<details>
+  <summary>Inferred CSN</summary>
+
+```jsonc
+{
+  "definitions": {
+    "E": {
+      "kind": "entity",
+      "elements": {
+        "f": {
+          "type": "cds.Association",
+          "target": "F",
+          "keys": [{"ref": ["id"]}]
+        }
+      }
+    },
+    "F": { /*...*/ }
+  }
+}
+```
+
+</details>
+
+<details>
+  <summary>Effective CSN</summary>
+
+```json
+{
+  "definitions": {
+    "E": {
+      "kind": "entity",
+      "elements": {
+        "f": {
+          "type": "cds.Association",
+          "target": "F",
+          "on": [{"ref": ["f","id"]}, "=", {"ref": ["f_id"]}]
+        },
+        "f_id": {
+          "type": "cds.Integer"
+        }
+      }
+    },
+    "F": {
+      "kind": "entity",
+      "elements": {
+        "id": {"key": true,"type": "cds.Integer"},
+        "x": {"type": "cds.Integer"}
+      }
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+  <summary>CDS source equivalent to Effective CSN</summary>
+
+```cds
+entity E {
+  f_id : Integer;
+  f : Association to F on f.id = f_id;
+}
+entity F { key id : Integer; x : Integer; }
+```
+</details>
+
+<br />
+
+In the definition of an unmanaged association (also in the ON condition of explicit JOINs)
+it is possible to reference the foreign keys of a "neighbor" managed association.
+When resolving managed associations, this is always interpreted as accessing the local
+foreign key element, never as "navigating" the association to the target:
+
+Example:  
+CDS:
+```cds
+entity E {
+  f : Association to F;
+  g : Association to G on g.id = f.id;  // f.x is NOT allowed
+}
+entity F { key id : Integer; x : Integer; }
+entity G { key id : Integer; }
+```
+
+<details>
+  <summary>CDS source equivalent to Effective CSN</summary>
+
+```cds
+entity E {
+  f_id : Integer;
+  f : Association to F on f.id = f_id;
+  g : Association to G on g.id = f_id;
+}
+entity F { /*...*/ }
+entity G { /*...*/ }
+```
+</details>
+
+<br />
+
+Publication of a managed association in a view/projection is also adapted
+and results in publishing the foreign key and the corresponding unmanaged association.
+
+Example:  
+CDS:
+```cds
+entity E {
+  f : Association to F;  // < managed
+}
+entity F {
+   key id : Integer;
+}
+view V as select from E {
+  f  // < managed
+}
+```
+
+<details>
+  <summary>Effective CSN</summary>
+
+```jsonc
+{
+  "definitions": {
+    "E": {
+      "kind": "entity",
+      "elements": {
+        "f": {
+          "type": "cds.Association",
+          "target": "F",
+          "on": [{"ref": ["f","id"]}, "=", {"ref": ["f_id"]}]
+        },
+        "f_id": {"type": "cds.Integer"}
+      }
+    },
+    "F": { /*...*/ },
+    "V": {
+      "kind": "entity",
+      "query": {
+        "SELECT": {
+          "from": {"ref": ["E"]},
+          "columns": [
+            {"ref": ["f"]},
+            {"ref": ["f_id"]}
+          ]
+        }
+      },
+      "elements": {
+        "f": {
+          "type": "cds.Association",
+          "target": "F",
+          "on": [{"ref": ["f","id"]}, "=", {"ref": ["f_id"]}
+          ]
+        },
+        "f_id": {"type": "cds.Integer"}
+      }
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+  <summary>CDS source equivalent to Effective CSN</summary>
+
+```cds
+entity E {
+  f_id : Integer;
+  f : Association to F on f.id = f_id;  // < unmanaged
+}
+entity F {
+   key id : Integer;
+}
+view V as select from E {
+  f_id,
+  f  // < unmanaged
+}
+```
+</details>
+
+
+#### Ambiguity
+
+Let's have a look at this view:
+```cds
+// original CDS source
+view V as select from E {
+  f.id
+}
+```
+There are two possibilities to interpret the path `f.id`:
+1. Select the local foreign key element of the managed association
+2. Navigate to the target entity and select the key element there
+
+When resolving unmanaged associations, option 1 results in
+```cds
+// CDS source equivalent to Effective CSN
+view V as select from E {
+  f_id as id
+}
+```
+while option 2 yields
+```cds
+// CDS source equivalent to Effective CSN
+view V as select from E {
+  f.id
+}
+```
+
+We _always_ choose option 1, i.e. we interpret and translate `f.id`
+as access to the FK element `f_id`.
+This doesn't change if there are other paths like `f.val` where `val` is not a FK
+(in SQL this would lead to a join, and then `f.id` would be changed to get `id` from the target).
+This also holds for paths in the clauses WHERE, GROUP BY, and ORDER BY.
+
+
+#### Annotations for FKs
+
+When resolving managed associations, all annotations of the managed association are copied
+to the generated FK elements (like for OData).
+
+Example:  
+CDS:
+```cds
+entity E {
+  @Foo: 8
+  f : Association to F;
+}
+
+entity F { key id : Integer; x : Integer; }
+```
+
+<details>
+  <summary>Effective CSN</summary>
+
+```jsonc
+{
+  "definitions": {
+    "E": {
+      "kind": "entity",
+      "elements": {
+        "f": {
+          "@Foo": 8,
+          "type": "cds.Association",
+          "target": "F",
+          "on": [{"ref": ["f","id"]},"=",{"ref": ["f_id"]}]
+        },
+        "f_id": {
+          "@Foo": 8,        // < anno copied to FK
+          "type": "cds.Integer"
+        }
+      }
+    },
+    "F": { ... }
+  }
+}
+```
+</details>
+
+
+#### No unmanaged association inside structures
+
+There is a _potential_ problem: The compiler allows to define managed associations
+inside structured elements/types, but unmanaged associations inside structured elements/types are
+not supported. Thus, if we transform a managed association inside a structured element into an
+unmanaged association, the resulting CSN can no longer be compiled.
+
+In the context of Effective CSN, however, that is not a real problem, as we also flatten all structured elements.
+
+
+### Keep array types (many)
+
+For Effective CSN, we don't replace `items`, but keep it as it is.
+
+Type references inside `items` are resolved, references to structured types are inlined.
+
+Example:  
+CDS:
+```cds
+type T : String;
+type S {
+  x: Integer;
+  y: T;
+}
+
+entity E {
+  emails : many T;
+  someS : many S;
+}
+```
+
+<details>
+  <summary>Effective CSN</summary>
+
+```json
+{
+  "definitions": {
+    "E": {
+      "kind": "entity",
+      "elements": {
+        "emails": {
+          "items": {
+            "type": "cds.String"
+          }
+        },
+        "someS": {
+          "items": {
+            "elements": {
+              "x": {"type": "cds.Integer"},
+              "y": {"type": "cds.String"}
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+</details>
+
+
+### Cleanup: remove no longer needed objects and attributes
+
+Inferred CSN still contains some definitions and properties that are not needed in
+Effective CSN (as it is not intended to use it for further modelling).
+
+We remove property `namespace`.
+
+After applying _all_ of
+* Apply extensions and includes
+* Unfold managed composition of aspect
+* Resolve simple type references (could refer to the type of an aspect element)
+* Flatten structured types (could refer to the type of an aspect element)
+
+in Effective CSN we
+* remove all aspects (they are mere building blocks for modelling)
+* remove all attributes `targetAspect`
+* remove property `extensions` (unapplied annotations)
+* remove property `includes` (property of an entity that lists all included objects)
+
+
+
+See examples in [Extensions and Includes are applied](#extensions-and-includes-are-applied)
+and [Composition of aspect is unfolded](#composition-of-aspect-is-unfolded).
+
+
+### Virtual elements
+
+No transformation applied for Effective CSN.
+
+Virtual elements are elements that are not present in the persistence layer.
+They can be used in an API (e.g. OData) and need to be handled in custom code.
+
+We keep them in Effective CSN.
+
+Example:  
+CDS:
+```cds
+entity E {
+  key id : Integer;
+  a : Integer;
+  virtual v : Integer;
+}
+
+entity V as select from E {
+  a,
+  v
+};
+```
+
+<details>
+  <summary>Effective CSN</summary>
+
+```json
+{
+  "definitions": {
+    "E": {
+      "kind": "entity",
+      "elements": {
+        "id": {"key": true,"type": "cds.Integer"},
+        "a": {"type": "cds.Integer"},
+        "v": {"@Core.Computed": true,
+              "virtual": true,          // <
+              "type": "cds.Integer"
+             }
+      }
+    },
+    "V": {
+      "kind": "entity",
+      "query": {
+        "SELECT": {
+          "from": {"ref": ["E"]},
+          "columns": [
+            {"ref": ["a"]},
+            {"ref": ["v"]}
+          ]
+        }
+      },
+      "elements": {
+        "a": {"type": "cds.Integer"},
+        "v": {"@Core.Computed": true,
+              "virtual": true,          // <
+              "type": "cds.Integer"
+        }
+      }
+    }
+  }
+}
+```
+</details>
+
+#### Note on removing virtual elements
+
+It is not possible to simply remove the virtual elements from the CSN, as they can occur also
+in expressions, e.g. in a where condition:
+```cds
+entity V2 as select from E {
+  a
+} where v > 4;
+```
+When generating SQL, the CAP compiler ignores all virtual element definitions and also ignores
+all select items that simply select a virtual element. But it issues an error, when a virtual element
+occurs in an expression.
+
+
+### Enums
+
+CAP CDS allows to define enums. Currently they can only be used in annotations.
+We keep them in Effective CSN.
+
+```cds
+// original CDS source
+entity E {
+  @Color: #green
+  key id : Integer;
+  color : Integer enum {red=1; green=2; blue=3;}
+}
+```
+
+<details>
+  <summary>Effective CSN</summary>
+
+```json
+{
+  "definitions": {
+    "E": {
+      "kind": "entity",
+      "elements": {
+        "id": {
+          "@Color": {"#": "green"},
+          "key": true,
+          "type": "cds.Integer"
+        },
+        "color": {
+          "type": "cds.Integer",
+          "enum": {
+            "red":   {"val": 1},
+            "green": {"val": 2},
+            "blue":  {"val": 3}
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+</details>
+
+
+### Session variables
+
+Session variables are kept unchanged in Effective CSN.
+Mapping to the respective HANA expression is done by the consumer.
+
+Expressions can contain references to so called session variables. Supported variables for
+view definitions and the corresponding replacements for HANA are:
+
+| name         | HANA                                          |
+| ---          | ---                                           |
+| $user.id     | `SESSION_CONTEXT('APPLICATIONUSER')`          |
+| $user.locale | `SESSION_CONTEXT('LOCALE')`                   |
+| $valid.from  | `TO_TIMESTAMP(SESSION_CONTEXT('VALID-FROM'))` |
+| $valid.to    | `TO_TIMESTAMP(SESSION_CONTEXT('VALID-TO'))`   |
+| $at.from     | `TO_TIMESTAMP(SESSION_CONTEXT('VALID-FROM'))` |
+| $at.to       | `TO_TIMESTAMP(SESSION_CONTEXT('VALID-TO'))`   |
+| $now         | `CURRENT_TIMESTAMP`                           |
+
+Remarks:
+* `$user.locale` is used in the generated association `localized` for localized elements.
+* `$user.id` may be used for accessing personalized table content
+* `$valid.from/to` and `$at.from/to` are used for feature "temporal", which is not yet official
+
+
+Example:
+```cds
+// original CDS source
+entity E {
+  key id : Integer;
+  name : String;
+  createdAt : Timestamp default $now;
+}
+entity V as select from E {
+  id
+} where name = $user.id;
+```
+
+<details>
+  <summary>Effective CSN</summary>
+
+```json
+{
+  "definitions": {
+    "E": {
+      "kind": "entity",
+      "elements": {
+        "id": {
+          "key": true,
+          "type": "cds.Integer"
+        },
+        "name": {
+          "type": "cds.String"
+        },
+        "createdAt": {
+          "type": "cds.Timestamp",
+          "default": {"ref": ["$now"]}
+        }
+      }
+    },
+    "V": {
+      "kind": "entity",
+      "query": {
+        "SELECT": {
+          "from": {"ref": ["E"]},
+          "columns": [{"ref": ["id"]}],
+          "where": [{"ref": ["name"]}, "=", {"ref": ["$user","id"]}]
+        }
+      },
+      "elements": {
+        "id": {"key": true,"type": "cds.Integer"}
+      }
+    }
+  }
+}
+```
+
+</details>
+
+
+### Actions and Functions
+
+CAP CDS supports the definition of bound/unbound actions and functions.
+We keep them in Effective CSN.
+
+Example:
+```cds
+// original CDS source
+entity E {
+  key id : Integer;
+} actions {
+  action A(p : Integer);
+  function F(p : Integer) returns String;
+}
+
+service S {
+  action A(p : Integer);
+  function F(p : Integer) returns String;
+}
+```
+
+<details>
+  <summary>Effective CSN</summary>
+
+```json
+{
+  "definitions": {
+    "E": {
+      "kind": "entity",
+      "elements": {
+        "id": {"key": true,"type": "cds.Integer"}
+      },
+      "actions": {
+        "A": {
+          "kind": "action",
+          "params": {"p": {"type": "cds.Integer"}}
+        },
+        "F": {
+          "kind": "function",
+          "params": {"p": {"type": "cds.Integer"}},
+          "returns": {"type": "cds.String"}
+        }
+      }
+    },
+    "S": {
+      "kind": "service"
+    },
+    "S.A": {
+      "kind": "action",
+      "params": {"p": {"type": "cds.Integer"}}
+    },
+    "S.F": {
+      "kind": "function",
+      "params": {"p": {"type": "cds.Integer"}},
+      "returns": {"type": "cds.String"}
+    }
+  }
+}
+```
+
+</details>
+
+
+### Associations via backlink
+
+In CAP CDS, an association from `A` to `B` can be defined based on an association
+from `B` to `A` via a special ON condition.
+
+Usually this is used with a managed association:
+```cds
+// original CDS source
+entity Books {
+  key id : Integer;
+  author : Association to one Authors;  // backlink association
+}
+entity Authors {
+  key id : Integer;
+  books : Association to many Books on books.author = $self;  // association via backlink
+                                    // books.author.id = id   // effective ON condition
+}
+```
+
+but also works with an unmanaged association:
+```cds
+// original CDS source
+entity Books {
+  key id : Integer;
+  author_id : Integer;
+  author : Association to one Authors on author.id = author_id;
+}
+entity Authors {
+  key id : Integer;
+  books : Association to many Books on books.author = $self;  // association via backlink
+                                    // books.author.id = id   // effective ON condition
+}
+```
+
+In Effective CSN, these ON conditions with `$self` are rewritten to ordinary ON conditions,
+like indicated in the examples.
+
+
+### Calculated Elements
+
+### $calc
+
+The compiler adds property `$calc` to those elements of views/projections, which are
+calculated fields (i.e. have a column expression) or references to
+a calculated field or element further down the view stack.
+
+For Effective CSN, `$calc` is removed.
+
+Example:
+```cds
+entity E {
+  key id : Integer;
+  a : Integer;
+  b : Integer;
+  cal : Integer = a + b;
+}
+
+view V as select from E {
+  id,
+  a, b,
+  a+b as ab,  // has $calc in Inferred CSN
+  cal         // has $calc in Inferred CSN
+}
+
+view W as select from V {
+  id,
+  a, b,
+  ab,        // has $calc in Inferred CSN
+  cal        // has $calc in Inferred CSN
+}
+```
+
+<details>
+  <summary>Inferred CSN</summary>
+
+```jsonc
+{
+  "definitions": {
+    "E": { /* ... */ },
+    "V": {
+      "kind": "entity",
+      "query": { /* ... */ },
+      "elements": {
+        "id": { "key": true, "type": "cds.Integer" },
+        "a": { "type": "cds.Integer" },
+        "b": { "type": "cds.Integer" },
+        "ab": {
+          "@Core.Computed": true,
+          "$calc": { "xpr": [{"ref": ["a"]}, "+", {"ref": ["b"]}] }
+        },
+        "cal": {
+          "@Core.Computed": true,
+          "type": "cds.Integer",
+          "$calc": { "xpr": [{"ref": ["a"]}, "+", {"ref": ["b"]}] }
+        }
+      }
+    },
+    "W": {
+      "kind": "entity",
+      "query": { /* ... */ },
+      "elements": {
+        "id": { "key": true, "type": "cds.Integer" },
+        "a": { "type": "cds.Integer" },
+        "b": { "type": "cds.Integer" },
+        "ab": {
+          "@Core.Computed": true,
+          "$calc": { "xpr": [{"ref": ["a"]}, "+", {"ref": ["b"]}] }
+        },
+        "cal": {
+          "@Core.Computed": true,
+          "type": "cds.Integer",
+          "$calc": { "xpr": [{"ref": ["a"]}, "+", {"ref": ["b"]}] }
+        }
+      }
+    }
+  }
+}
+```
+
+</details>
+
+
+#### Calculated elements on-read
+
+[Calculated elements](https://cap.cloud.sap/docs/cds/cdl#on-read) are elements
+in non-query entity that hold an expression. They can be used in views/projections at every place
+where an expression can occur.
+
+For Effective CSN, calculated element definitions are removed
+and each reference to a calculated element is replaced with the respective expression.
+
+Example:  
+CDS:
+```cds
+entity E {
+  key id : Integer;
+  a : Integer;
+  b : Integer;
+  c1 : Integer = a + b;
+  c2 : Integer = 2 * c1;  // can be nested
+}
+
+view V as select from E {
+  id,
+  c1,
+  4 + c2 as x,
+  c1 + c2 as c3,
+  c1 + 4 as c4,
+  $projection.c4 + 4 as c5
+};
+
+view V2 as select from V {
+  id,
+  c1,
+  x,
+  c3
+};
+```
+In the SQL table generated for `E`, the calculated elements are not present.
+
+<details>
+  <summary>CDS source equivalent to Effective CSN</summary>
+
+```cds
+entity E {
+  key id : Integer;
+  a : Integer;
+  b : Integer;
+}
+
+view V as select from E {
+  id,
+  a + b as c1 : Integer,
+  4 + (2 * (a + b)) as x : Integer,
+  (a+b) + 2*(a+b) as c3,
+  (a + b) + 4 as c4,
+  $projection.c4 + 4 as c5 // > see section $projection below
+};
+
+view V2 as select from E {
+  id,
+  c1,
+  x,
+  c3
+};
+```
+
+</details>
+
+#### Calculated elements on-write
+
+No transformation is applied for Effective CSN.
+
+There is a second flavor of calculated elements, called
+[Calculated elements on-write](https://cap.cloud.sap/docs/cds/cdl#on-write).
+
+```cds
+// original CDS source
+entity E {
+  key id : Integer;
+  a : Integer;
+  b : Integer;
+  c : Integer = a + b stored;
+}
+entity V as select from E {
+  id, c
+};
+```
+
+They are implemented in CAP by using the HANA feature "GENERATED ALWAYS AS".
+<details>
+  <summary>Resulting SQL</summary>
+
+```sql
+create table E (
+  id Integer,
+  a Integer,
+  b Integer,
+  c Integer always generated as (a + b),
+  primary key (id)
+)
+```
+
+</details>
+
+<br />
+
+Calculated elements on-write are kept in Effective CSN without any change.
+Besides the definition, calculated elements on-write behave like regular (read-only) elements,
+no special treatment or representation is necessary.
+
+<details>
+  <summary>Effective CSN</summary>
+
+```json
+{
+  "definitions": {
+    "E": {
+      "kind": "entity",
+      "elements": {
+        "id": {"key": true,"type": "cds.Integer"},
+        "a": {"type": "cds.Integer"},
+        "b": {"type": "cds.Integer"},
+        "c": {
+          "@Core.Computed": true,
+          "type": "cds.Integer",
+          "value": {                   // <
+            "stored": true,
+            "xpr": [{"ref": ["a"]}, "+", {"ref": ["b"]}]
+          }
+        }
+      }
+    },
+    "V": {
+      "kind": "entity",
+      "query": {
+        "SELECT": {
+          "from": {"ref": ["E"]},
+          "columns": [
+            {"ref": ["id"]},
+            {"ref": ["c"]}
+          ]
+        }
+      },
+      "elements": {
+        "id": { "key": true, "type": "cds.Integer"},
+        "c": {"@Core.Computed": true, "type": "cds.Integer"}
+      }
+    }
+  }
+}
+```
+
+</details>
+
+
+### Draft
+
+Annotations `@odata.draft.enabled` are kept in Effective CSN, but no "draft unfolding" is done.
+I.e. Effective CSN doesn't contain any draft specific entities (DraftAdministrativeData, `.drafts` entities)
+or associations.
+
+
+### Queries
+
+CDS queries can contain a number of features that may be CAP specific and are not
+understood generally. In the following sections we define which of them stay in Effective CSN,
+and which ones are transformed.
+
+
+### Query: No assoc2join
+
+No transformation applied for Effective CSN.
+
+Paths with associations in views/projections are __not__ translated to JOINS, but
+are left untouched.
+
+
+### Query: EXISTS paths
+
+CAP CDS supports a simplified way to formulate EXISTS subqueries.
+For Effective CSN, we expand EXISTS paths to regular subqueries.
+
+Example:  
+CDS:
+```cds
+entity Books {
+  key id : Integer;
+  price : Decimal;
+  author_id : Integer;
+}
+entity Authors {
+  key id : Integer;
+  books : Association to many Books on books.author_id = id;
+}
+
+entity AuthorsWithExpensiveBooks as select from Authors {
+  id
+} where exists books[price > 100.00];
+```
+
+<details>
+  <summary>Effective CSN</summary>
+
+```json
+{
+  "definitions": {
+    "Books": {
+      "kind": "entity",
+      "elements": {
+        "id": {"key": true,"type": "cds.Integer"},
+        "price": {"type": "cds.Decimal"},
+        "author_id": {"type": "cds.Integer"}
+      }
+    },
+    "Authors": {
+      "kind": "entity",
+      "elements": {
+        "id": {"key": true,"type": "cds.Integer"},
+        "books": {
+          "type": "cds.Association",
+          "cardinality": {"max": "*"},
+          "target": "Books",
+          "on": [{"ref": ["books","author_id"]}, "=", {"ref": ["id"]}]
+        }
+      }
+    },
+    "AuthorsWithExpensiveBooks": {
+      "kind": "entity",
+      "query": {
+        "SELECT": {
+          "from": {"ref": ["Authors"]},
+          "columns": [{"ref": ["id"]}],
+          "where": [
+            "exists",
+            {
+              "SELECT": {
+                "from": {"ref": ["Books"], "as": "_books_exists"},
+                "columns": [{"val": 1, "as": "dummy"}],
+                "where": [
+                  {"ref": ["_books_exists","author_id"]}, "=", {"ref": ["Authors","id"]},
+                  "and",
+                  {"ref": ["_books_exists","price"]}, ">", {"val": "100.0", "literal": "number"}
+                ]
+              }
+            }
+          ]
+        }
+      },
+      "elements": {
+        "id": {"key": true,"type": "cds.Integer"}
+      }
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+  <summary>CDS source equivalent to Effective CSN</summary>
+
+```cds
+entity AuthorsWithExpensiveBooks as select from Authors {
+  id
+} where exists (select 1 as dummy from Books as _books_exists
+                    where _books_exists.author_id = Authors.id and _books_exists.price > 100 );
+```
+
+</details>
+
+<br />
+
+Note:
+* Exists paths can be nested, resulting in corresponding nested subqueries.
+* This step doesn't introduce table aliases for the existing data sources (`Authors`).
+* We currently generate a `SELECT 1 as dummy FROM ...` with an unnecessary alias. The alias may vanish in the future.
+
+
+
+### Query: CDL style cast
+
+No transformation applied for Effective CSN.
+
+CAP CDS doesn't compute result types for expressions. If a type is needed for an expression in a view,
+e.g. for OData exposure, it can be explicitly set via a "CDL-style cast".
+For Effective CSN, we keep these CDL style casts.
+
+Example:  
+CDS:
+```cds
+entity E {
+  key id : Integer;
+  r : Integer;
+}
+
+view V as select from E {
+  id,
+  2 * 3.1415 * r as area : Decimal(11,4)
+};
+```
+
+<details>
+  <summary>Effective CSN</summary>
+
+```json
+{
+  "definitions": {
+    "E": { ... },
+    "V": {
+      "kind": "entity",
+      "query": {
+        "SELECT": {
+          "from": {"ref": ["E"]},
+          "columns": [
+            {"ref": ["id"]},
+            {
+              "xpr": [{"val": 2}, "*", {"val": 3.1415}, "*", {"ref": ["r"]}],
+              "as": "area",
+              "cast": {
+                "type": "cds.Decimal",
+                "precision": 11,
+                "scale": 4
+              }
+            }
+          ]
+        }
+      },
+      "elements": {
+        "id": {"key": true, "type": "cds.Integer"},
+        "area": {"@Core.Computed": true, "type": "cds.Decimal", "precision": 11, "scale": 4}
+      }
+    }
+  }
+}
+```
+
+</details>
+
+
+### Query: $projection
+
+In the query of a view (or projection), CAP CDS allows to refer to elements of the view's
+own select list via `$projection` or `$self` (they are equivalent in this case).
+For Effective CSN, we do __not__ replace such references with the original expression.
+
+Example:  
+CDS:
+```cds
+entity E {
+  key id : Integer;
+  a : Integer;
+  b : Integer;
+  f : Association to F on f.id = b;
+}
+entity F {
+  key id : Integer;
+  x : Integer;
+}
+
+view V as select from E {
+  id,
+  a + b as c1,
+  a - b as c2,
+  $projection.c1 + $projection.c2 as c3,
+  f.x as p,
+  $self.p as p2
+} where $projection.c1 > 27;
+```
+
+<details>
+  <summary>Effective CSN</summary>
+
+```json
+{
+  "definitions": {
+    "E": {... },
+    "F": { ... },
+    "V": {
+      "kind": "entity",
+      "query": {
+        "SELECT": {
+          "from": {"ref": ["E"]},
+          "columns": [
+            {"ref": ["id"]},
+            {"xpr": [{"ref": ["a"]}, "+", {"ref": ["b"]}],                               "as": "c1" },
+            {"xpr": [{"ref": ["a"]}, "-",{"ref": ["b"]}],                                "as": "c2"},
+            {"xpr": [{"ref": ["$projection","c1"]}, "+", {"ref": ["$projection","c2"]}], "as": "c3"},
+            {"ref": ["f","x"],                                                           "as": "p"},
+            {"ref": ["$self","p"],                                                       "as": "p2"}
+          ],
+          "where": [{"ref": ["$projection","c1"]}, ">", {"val": 27}]
+        }
+      },
+      "elements": {
+        "id": {"key": true,"type": "cds.Integer"},
+        "c1": {"@Core.Computed": true},
+        "c2": {"@Core.Computed": true},
+        "c3": {"@Core.Computed": true},
+        "p": {"type": "cds.Integer"},
+        "p2": {"type": "cds.Integer"}
+      }
+    }
+  }
+}
+```
+
+</details>
+
+
+### Query: select *
+
+CAP CDS allows to model queries with `select *`. In Effective CSN, the `*` is expanded to an explicit column list.
+Reasoning: the `*` is a modelling feature that simplifies writing queries
+and ensures that in extension scenarios new elements are automatically selected. These benefits are not necessary in
+an Effective CSN.
+
+Example:  
+CDS:
+```cds
+entity E {
+  key id : Integer;
+  a : Integer;
+  b : Integer;
+}
+entity V1 as select from E;
+entity V2 as select from E { * };
+entity V3 as select from E { *, 7 as a};  // "smart *"
+entity V4 as select from E { * } excluding { b };
+```
+
+<details>
+  <summary>Effective CSN</summary>
+
+```json
+{
+  "definitions": {
+    "E": { ... },
+    "V1": {
+      "kind": "entity",
+      "query": {
+        "SELECT": {
+          "from": {"ref": ["E"]},
+          "columns": [
+            {"ref": ["id"]},
+            {"ref": ["a"]},
+            {"ref": ["b"]}
+          ]
+        }
+      },
+      "elements": {
+        "id": {"key": true,"type": "cds.Integer"},
+        "a": {"type": "cds.Integer"},
+        "b": {"type": "cds.Integer"}
+      }
+    },
+    "V2": {
+      "kind": "entity",
+      "query": {
+        "SELECT": {
+          "from": {"ref": ["E"]},
+          "columns": [
+            {"ref": ["id"]},
+            {"ref": ["a"]},
+            {"ref": ["b"]}
+          ]
+        }
+      },
+      "elements": {
+        "id": {"key": true,"type": "cds.Integer"},
+        "a": {"type": "cds.Integer"},
+        "b": {"type": "cds.Integer"}
+      }
+    },
+    "V3": {
+      "kind": "entity",
+      "query": {
+        "SELECT": {
+          "from": {"ref": ["E"]},
+          "columns": [
+            {"ref": ["id"]},
+            {"val": 7,"as": "a"},
+            {"ref": ["b"]}
+          ]
+        }
+      },
+      "elements": {
+        "id": {"key": true,"type": "cds.Integer"},
+        "a": {"@Core.Computed": true},
+        "b": {"type": "cds.Integer"}
+      }
+    },
+    "V4": {
+      "kind": "entity",
+      "query": {
+        "SELECT": {
+          "from": {"ref": ["E"]},
+          "columns": [
+            {"ref": ["id"]},
+            {"ref": ["a"]}
+          ]
+        }
+      },
+      "elements": {
+        "id": {"key": true,"type": "cds.Integer"},
+        "a": {"type": "cds.Integer"}
+      }
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+  <summary>CDS source equivalent to Effective CSN</summary>
+
+```cds
+entity E {...};
+entity V1 as select from E { id, a, b};
+entity V2 as select from E { id, a, b };
+entity V3 as select from E { id, 7 as a, b};
+entity V4 as select from E { id, a };
+```
+
+</details>
+
+
+### Query: filter
+
+Paths with associations may have an infix filter.
+We keep them in the Effective CSN.
+
+
+Example:  
+CDS:
+```cds
+entity Teams {
+  key id : Integer;
+  members : Association to many TeamMembers on members.team = $self;
+}
+entity TeamMembers {
+  key id : Integer;
+  team : Association to Teams;
+  name : String;
+  isLead : Boolean;
+  projects : Integer;
+}
+
+entity V as select from Teams {
+  id,
+  members[projects = 0].name as withoutProject,
+  members[1: isLead = true].name as teamLead
+};
+```
+
+<details>
+  <summary>Effective CSN</summary>
+
+```json
+{
+  "definitions": {
+    "Teams": { ... },
+    "TeamMembers": { ... },
+    "V": {
+      "kind": "entity",
+      "query": {
+        "SELECT": {
+          "from": {"ref": ["Teams"]},
+          "columns": [
+            {"ref": ["id"]},
+            {
+              "ref": [
+                {
+                  "id": "members",
+                  "where": [{"ref": ["projects"]}, "=", {"val": 0}]
+                },
+                "name"
+              ],
+              "as": "withoutProject"
+            },
+            {
+              "ref": [
+                {
+                  "id": "members",
+                  "cardinality": {"max": 1},
+                  "where": [{"ref": ["isLead"]}, "=", {"val": true}]
+                },
+                "name"
+              ],
+              "as": "teamLead"
+            }
+          ]
+        }
+      },
+      "elements": {
+        "id": {"type": "cds.Integer"},
+        "withoutProject": {"type": "cds.String"},
+        "teamLead": {"type": "cds.String"}
+      }
+    }
+  }
+}
+```
+
+</details>
+
+
+### Query: expand and inline
+
+#### Nested inline
+
+CAP CDS supports a syntax convenience feature [Nested inline](https://cap.cloud.sap/docs/cds/cql#nested-inlines).
+Paths in the select list that share a common prefix can be grouped.
+
+Example:
+```cds
+entity E {
+  key id : Integer;
+  a : Integer;
+  f : Association to F on f.id = a;
+}
+entity F {
+  key id : Integer;
+  x : Integer;
+  y : Integer;
+}
+entity V_inline as select from E {
+  id,
+  f.{ x, y }
+};
+```
+
+The view definition above is equivalent to
+```cds
+entity V_inline as select from E {
+  id,
+  f.x,
+  f.y
+};
+```
+Effective CSN contains this unfolded form.
+
+<details>
+  <summary>Effective CSN</summary>
+
+```json
+{
+  "definitions": {
+    "E": { ... },
+    "F": { ... },
+    "V_inline": {
+      "kind": "entity",
+      "query": {
+        "SELECT": {
+          "from": {"ref": ["E"]},
+          "columns": [
+            {"ref": ["id"]},
+            {"ref": ["f","x"]},
+            {"ref": ["f","y"]}
+          ]
+        }
+      },
+      "elements": {
+        "id": {"key": true,"type": "cds.Integer"},
+        "x": {"type": "cds.Integer"},
+        "y": {"type": "cds.Integer"}
+      }
+    }
+  }
+}
+```
+</details>
+
+#### Nested expand
+
+CAP CDS also supports [Nested expand](https://cap.cloud.sap/docs/cds/cql#nested-expands).
+This is not only a syntax shortcut, but allows to "create" structured result sets.
+
+Example:
+```cds
+entity V_expand as select from E {
+  id,
+  f { x, y }
+};
+```
+
+Here the resulting `V_expand` contains a structured element `f` with elements `x` and `y`,
+which is flattened in Effective CSN.
+
+<details>
+  <summary>Effective CSN</summary>
+
+```json
+{
+  "definitions": {
+    "E": { ... },
+    "F": { ... },
+    "V_expand": {
+      "kind": "entity",
+      "query": {
+        "SELECT": {
+          "from": {"ref": ["E"]},
+          "columns": [
+            {"ref": ["id"]},
+            {"ref": ["f","x"], "as": "f_x"},
+            {"ref": ["f","y"], "as": "f_y"}
+          ]
+        }
+      },
+      "elements": {
+        "id": {"key": true, "type": "cds.Integer"},
+        "f_x": {"type": "cds.Integer"},
+        "f_y": {"type": "cds.Integer"}
+      }
+    }
+  }
+}
+```
+</details>
+
+<details>
+  <summary>CDS source equivalent to Effective CSN</summary>
+
+```cds
+entity V_expand as select from E {
+  id,
+  f.x as f_x,
+  f.y as f_y
+};
+```
+</details>
+
+
+### Query: path in FROM
+
+CAP CDS supports paths in the FROM clause. For SQL, they are translated to INNER JOIN in the compiler
+or to a Subquery in the Nodejs runtime, respectively (difference between INNER JOIN and Subquery
+is that with inner join the same entry of the final target entry may be returned several times while
+with Subquery they are guaranteed to be unique).
+
+Paths in FROM are kept in Effective CSN.
+
+
+Example:
+```cds
+entity C.E {
+  key id : Integer;
+  a : Integer;
+  f : Association to C.F on f.id = a;
+}
+entity C.F {
+  key id : Integer;
+  b : Integer;
+}
+
+entity V as select from C.E:f {
+  id,
+  b
+};
+```
+
+<details>
+  <summary>Effective CSN</summary>
+
+```json
+{
+  "definitions": {
+    "C.E": { ... },
+    "C.F": { ... },
+    "V": {
+      "kind": "entity",
+      "query": {
+        "SELECT": {
+          "from": {"ref": ["C.E","f"]},
+          "columns": [
+            {"ref": ["id"]},
+            {"ref": ["b"]}
+          ]
+        }
+      },
+      "elements": {
+        "id": {"key": true,"type": "cds.Integer"},
+        "b": {"type": "cds.Integer"}
+      }
+    }
+  }
+}
+```
+</details>
+
+
+### Query: path in WHERE, GROUP BY
+
+CAP CDS supports paths in WHERE and GROUP BY.
+We keep them in the CSN.
+
+```cds
+entity V2 as select from E {
+  id,
+  f.b
+} where f.b = 1 group by f.b;
+```
+
+Note: it is not possible to translate these paths to JOINs while not translating
+paths in the select list.
+
+
+### Query: Projection vs View
+
+CAP CDS has projections and views. Semantically the difference is that in projections
+you cannot use explicit joins, unions, or subqueries.
+
+```cds
+entity E {
+  key id : Integer;
+}
+entity V as select from E { id };
+entity P as projection on E { id };
+```
+
+<details>
+  <summary>Inferred CSN</summary>
+
+```
+{
+  "definitions": {
+    "E": { ... },
+    "V": {
+      "kind": "entity",
+      "query": {
+        "SELECT": {
+          "from": {"ref": ["E"]},
+          "columns": [{"ref": ["id"]}]
+        }
+      },
+      "elements": {
+        "id": {"key": true,"type": "cds.Integer"}
+      }
+    },
+    "P": {
+      "kind": "entity",
+      "projection": {
+        "from": {"ref": ["E"]},
+        "columns": [{"ref": ["id"]}]
+      },
+      "elements": {
+        "id": {"key": true,"type": "cds.Integer"}
+      }
+    }
+  }
+}
+```
+</details>
+
+For Effective CSN, the default behavior is to convert projections to views, i.e. we replace `projection` by `query.SELECT`.
+
+<details>
+  <summary>Effective CSN</summary>
+
+```
+{
+  "definitions": {
+    "E": { ... },
+    "V": {
+      "kind": "entity",
+      "query": {
+        "SELECT": {
+          "from": {"ref": ["E"]},
+          "columns": [{"ref": ["id"]}]
+        }
+      },
+      "elements": {
+        "id": {"key": true,"type": "cds.Integer"}
+      }
+    },
+    "P": {
+      "kind": "entity",
+      "query": {
+        "SELECT": {
+          "from": {"ref": ["E"]},
+          "columns": [{"ref": ["id"]}]
+        }
+      },
+      "elements": {
+        "id": {"key": true,"type": "cds.Integer"}
+      }
+    }
+  }
+}
+```
+</details>
+
+When option `resolveProjections` is set to `false` (default is `true`), no transformation is applied,
+i.e. property `projection` is kept as is.
+
+
+### Query: Mixin associations
+
+No transformation is applied for Effective CSN.
+
+CAP CDS allows to define mixin associations. They can be used in the query or be published.
+
+```cds
+entity E {
+  key id : Integer;
+  a : Integer;
+}
+
+entity F {
+  key id : Integer;
+  x : Integer;
+}
+
+entity V1 as select from E
+mixin {
+ f : Association to F on f.id = a;
+} into {
+  a as pa,
+  f.x,
+  f
+};
+
+entity V2 as select from E
+mixin {
+  f : Association to F on f.id = $projection.pa;
+} into {
+  a as pa,
+  f.x,
+  f
+};
+```
+
+In the definition of a mixin association, you can use elements of the datasource (example: `V1`)
+or elements of the select list via `$projection` (example: `V2`).
+
+A mixin association that uses elements of the datasource in its ON condition (example: `V1`)
+can be used (in a path expression) in the query, or it can be published if all elements used
+in the ON condition are published, too.
+
+A mixin association that uses elements of the select list via `$projection` in its ON condition (example: `V2`)
+can be used (in a path expression) in the query, or it can be published.
+
+We keep mixin associations in the CSN as is. No transformation is applied
+
+<details>
+  <summary>Effective CSN</summary>
+
+```json
+{
+  "definitions": {
+    "E": { ... },
+    "F": { ... },
+    "V1": {
+      "kind": "entity",
+      "query": {
+        "SELECT": {
+          "from": {"ref": ["E"]},
+          "mixin": {
+            "f": {
+              "type": "cds.Association",
+              "target": "F",
+              "on": [{"ref": ["f","id"]}, "=", {"ref": ["a"]}]
+            }
+          },
+          "columns": [
+            {"ref": ["a"], "as": "pa"},
+            {"ref": ["f","x"]},
+            {"ref": ["f"]}
+          ]
+        }
+      },
+      "elements": {
+        "pa": {"type": "cds.Integer"},
+        "x": {"type": "cds.Integer"},
+        "f": {
+          "type": "cds.Association",
+          "target": "F",
+          "on": [{"ref": ["f","id"]}, "=", {"ref": ["pa"]}]
+        }
+      }
+    },
+    "V2": {
+      "kind": "entity",
+      "query": {
+        "SELECT": {
+          "from": {"ref": ["E"]},
+          "mixin": {
+            "f": {
+              "type": "cds.Association",
+              "target": "F",
+              "on": [{"ref": ["f","id"]}, "=", {"ref": ["$projection","pa"]}]
+            }
+          },
+          "columns": [
+            {"ref": ["a"], "as": "pa"},
+            {"ref": ["f","x"]},
+            {"ref": ["f"]}
+          ]
+        }
+      },
+      "elements": {
+        "pa": {"type": "cds.Integer"},
+        "x": {"type": "cds.Integer"},
+        "f": {
+          "type": "cds.Association",
+          "target": "F",
+          "on": [{"ref": ["f","id"]}, "=", {"ref": ["$self","pa"]}]
+        }
+      }
+    }
+  }
+}
+```
+</details>
+
+
+### Query: Redirect
+
+No transformation is applied for Effective CSN.
+
+CAP CDS allows to explicitly redirect an association that is published in a view:
+
+```cds
+entity E {
+  key id : Integer;
+  a : Integer;
+  b : Integer;
+  f : Association to F on f.x = a;
+}
+entity F {
+  key id : Integer;
+  x : Integer;
+  y : Integer;
+}
+
+view VE as select from E {
+  id, a, b,
+  f as vf1 : redirected to VF,
+  f as vf2 : redirected to VF on vf2.y = b
+};
+view VF as select from F {
+  id, x, y
+};
+```
+
+Redirects are kept in Effective CSN without change, no transformation is applied.
+The redirections are represented as attribute `cast` in the columns.
+
+<details>
+  <summary>Effective CSN</summary>
+
+```json
+{
+  "definitions": {
+    "E": { ... },
+    "F": { ... },
+    "VE": {
+      "kind": "entity",
+      "query": {
+        "SELECT": {
+          "from": {"ref": ["E"]},
+          "columns": [
+            {"ref": ["id"]},
+            {"ref": ["a"]},
+            {"ref": ["b"]},
+            {
+              "ref": ["f"],
+              "as": "vf1",
+              "cast": {
+                "target": "VF"
+              }
+            },
+            {
+              "ref": ["f"],
+              "as": "vf2",
+              "cast": {
+                "target": "VF",
+                "on": [{"ref": ["vf2","y"]}, "=", {"ref": ["b"]}]
+              }
+            }
+          ]
+        }
+      },
+      "elements": {
+        "id": {"key": true,"type": "cds.Integer"},
+        "a": {"type": "cds.Integer"},
+        "b": {"type": "cds.Integer"},
+        "vf1": {
+          "type": "cds.Association",
+          "target": "VF",
+          "on": [{"ref": ["vf1","x"]}, "=", {"ref": ["a"]}]
+        },
+        "vf2": {
+          "type": "cds.Association",
+          "target": "VF",
+          "on": [{"ref": ["vf2","y"]}, "=", {"ref": ["b"]}]
+        }
+      }
+    },
+    "VF": { ... }
+  }
+}
+```
+</details>
+
+
+### Query: Defining associations in the select list
+
+No transformation is applied for Effective CSN.
+
+CAP CDS supports an easy way to define and publish an unmanaged association in a view or projection.
+
+```cds
+entity E {
+  key id : Integer;
+  a : Integer;
+}
+entity F {
+  key id : Integer;
+}
+
+entity V as select from  E {
+  id,
+  a,
+  toF : Association to F on toF.id = a
+};
+```
+
+This is kept in Effective CSN unchanged, no transformation is applied.
+
+<details>
+  <summary>Effective CSN</summary>
+
+```json
+{
+  "definitions": {
+    "E": { ... },
+    "F": { ... },
+    "V": {
+      "kind": "entity",
+      "query": {
+        "SELECT": {
+          "from": {"ref": ["E"]},
+          "columns": [
+            {"ref": ["id"]},
+            {"ref": ["a"]},
+            {
+              "as": "toF",
+              "cast": {
+                "target": "F",
+                "type": "cds.Association",
+                "on": [{"ref": ["toF","id"]}, "=", {"ref": ["a"]}]
+              }
+            }
+          ]
+        }
+      },
+      "elements": {
+        "id": {"key": true,"type": "cds.Integer"},
+        "a": {"type": "cds.Integer"},
+        "toF": {
+          "type": "cds.Association",
+          "target": "F",
+          "on": [{"ref": ["toF","id"]}, "=", {"ref": ["a"]}]
+        }
+      }
+    }
+  }
+}
+```
+</details>
+
+
+### Query: Exposing associations
+
+Exposing managed association is covered above in section "Resolve Managed Associations".
+Exposing mixin associations is covered above in the section on mixin associations.
+
+Publishing associations that are defined in a data source of a view or projection should
+__not__ be turned into definition and publication of a mixin association.
+
+
+
+### Annotations
+
+Annotations are kept in Effective CSN as they come from Inferred CSN.
+No transformations are applied, except:
+* Annotation expressions: see section below.
+* For `@cds.persistence.exists/skip/table`, value `'if-unused'` is mapped to `false`.
+
+
+#### Annotation expressions
+
+References inside annotation expressions are consistently rewritten, when transformations
+[Flatten structured types](#flatten-structured-types) and
+[Resolve Managed Associations](#resolve-managed-associations) are applied.
+For reference-like annotation expressions, `=` is handled like in Inferred CSN:
+* For simple references (no filter, no parameters), `=` is the string representation of the reference.
+* For non-simple references, `=` is `true` (for cds-compiler v6 and lower, sometimes `=` contains the string
+  represenation of the reference).
+
+Outside of CAP, annotation expressions are not yet known, but that may change.
+Thus we keep annotation expressions in effective CSN by default, but offer an option
+to remove them. When option `stringifyAnnoXpr` is set to `true`, annotation expressions are replaced
+in the following way:
+
+* Simple references still are an object with a single property `=`
+  (like before introducing annotation expressions).
+* Enums are kept unchanged.
+* For all other expressions: the object-like annotation value is replaced by a string representation
+  of the expression.
+
+Example:
+```cds
+@X_ref_simple: (a)
+@X_ref_nonsimple: (f[id>1].id)
+@X_xpr: (a+b)
+@X_enum: (#FOOL)
+@X_val: (33)
+@X_func: (coalesce(a, 0))
+@X_list: ((1, 2, 3))
+entity E {
+  key id : Integer;
+  a : Integer;
+  b : Integer;
+  f : Association to F;
+}
+
+entity F {
+  key id : Integer;
+}
+```
+
+
+<details>
+  <summary>Effective CSN</summary>
+
+```json
+{
+  "definitions": {
+    "E": {
+      "kind": "entity",
+      "@X_ref_simple": {
+        "=": "a",
+        "ref": ["a"]
+      },
+      "@X_ref_nonsimple": {
+        "=": true,
+        "ref": [
+          {
+            "id": "f",
+            "where": [{"ref": ["id"]}, ">", {"val": 1}]
+          },
+          "id"
+        ]
+      },
+      "@X_xpr": {
+        "xpr": [{"ref": ["a"]}, "+", {"ref": ["b"]}]
+      },
+      "@X_enum": {
+        "#": "FOOL"
+      },
+      "@X_val": {
+        "=": true,
+        "val": 33
+      },
+      "@X_func": {
+        "=": true,
+        "func": "coalesce",
+        "args": [
+          {"ref": [ "a" ]},
+          {"val": 0}
+        ]
+      },
+      "@X_list": {
+        "=": true,
+        "list": [
+          {"val": 1}, {"val": 2}, {"val": 3}
+        ]
+      },
+      "elements": { /* ... */ }
+    },
+    "F": { /* ... */ }
+  }
+}
+```
+</details>
+
+Effective CSN with `stringifyAnnoXpr = true`:
+```jsonc
+{
+  "definitions": {
+    "E": {
+      "kind": "entity",
+      "@X_ref_simple": { "=": "a" },
+      "@X_ref_nonsimple": "f[id > 1].id",
+      "@X_xpr": "a + b",
+      "@X_enum": { "#": "FOOL" },
+      "@X_val": 33,
+      "@X_func": "coalesce(a, 0)",
+      "@X_list": "(1, 2, 3)",
+      "elements": { /* ... */ }
+    },
+    "F": { /* ... */ }
+  }
+}
+```
+
+
+#### Note on CAP annotations
+
+CAP has introduced some annotations as shortcuts for e.g. OData annotations. The full list can be found
+in [capire#common-annotations](https://cap.cloud.sap/docs/cds/annotations#common-annotations).
+
+We keep the following annotations in Effective CSN:
+* `@title`
+* `@description`
+* `@readonly`
+* `@mandatory`
+* `@cds.valid.from/to`
+* `@cds.on....`
+
+
+### Localized metadata
+
+Texts in metadata like `@Common.Label` usually are localized. The value of the
+annotation is a i18n key like
+```cds
+annotate schema.Airline with @title: '{i18n>Airline}';
+```
+and the actual texts are stored in i18n files.
+
+It would be possible to store localized texts in the `i18n` section of CSN, but we don't
+use this for Effective CSN. Consumers have to read the texts directly from the i18n files.
+
+
+### Reduce to one service
+
+If option `effectiveServiceName` is set, the output is filtered to contain only the
+named service definition and the artifacts contained in that service.
+All definitions outside the service are removed.
+
+Example:  
+CDS:
+```cds
+entity E {
+  key id : Integer;
+  f : Association to F;
+}
+entity F {
+  key id : Integer;
+}
+
+service S {
+  entity PE as projection on E;
+  entity PF as projection on F;
+}
+```
+
+<details>
+  <summary>Effective CSN with option "effectiveServiceName"</summary>
+
+Set `effectiveServiceName: S`:
+```json
+{
+  "definitions": {
+    "S": {
+      "kind": "service"
+    },
+    "S.PE": {
+      "kind": "entity",
+      "query": { /* ... */ },
+      "elements": {
+        "id": {"key": true, "type": "cds.Integer"},
+        "f": {
+          "type": "cds.Association",
+          "target": "S.PF",
+          "on": [{"ref": ["f","id"]}, "=", {"ref": ["f_id"]}]
+        },
+        "f_id": {"type": "cds.Integer"}
+      }
+    },
+    "S.PF": {
+      "kind": "entity",
+      "query": {
+        "SELECT": {
+          "from": {"ref": ["F"]},
+          "columns": [{"ref": ["id"]}]
+        }
+      },
+      "elements": {
+        "id": {"key": true, "type": "cds.Integer"}
+      }
+    }
+  }
+}
+```
+</details>
+
+Note:
+* If no service with the given name exists, a warning is emitted and the output contains no definitions.
+* Associations to a target outside of the service that cannot be redirected are reported as error.