If necessary, CDS automatically translates OData V4 annotations to OData V2 SAP extensions when you invoke it with `v2` as the OData version. This means you shouldn't need to deal with this at all. Nevertheless, in case you need to do so, you can add `sap:...` attribute-style annotations as follows: ```cds @sap.applicable.path: 'to_eventStatus/EditEnabled' action EditEvent(...) returns SomeType; ``` Which would render to OData EDMX as follows: ```xml ... ``` The rules are: * Only strings are supported as values. * The first dot in `@sap.` is replaced by a colon `:`. * Subsequent dots are replaced by dashes. ### Differences to ABAP In contrast to ABAP CDS, we apply a **generic, isomorphic approach** where names and positions of annotations are exactly as specified in the [OData Vocabularies](#vocabularies). This has the following advantages: * Single source of truth — users only need to consult the official OData specs * Speed — we don't need complex case-by-case mapping logic * No bottlenecks — we always support the full set of OData annotations * Bidirectional mapping — we can translate CDS to EDMX and vice versa Last but not least, it also saves us lots of effort as we don't have to write derivatives of all the OData vocabulary specs. ## Annotation Vocabularies { #vocabularies} When translating a CDS model to an OData API, by default only those annotations are considered that are part of the standard OASIS or SAP vocabularies listed below. You can add further vocabularies to the translation process [using configuration.](#additional-vocabularies) ### [OASIS Vocabularies](https://github.com/oasis-tcs/odata-vocabularies#further-description-of-this-repository) { target="_blank"} | Vocabulary | Description | |-----------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------| | [@Aggregation](https://github.com/oasis-tcs/odata-vocabularies/tree/main/vocabularies/Org.OData.Aggregation.V1.md){target="_blank"} | for describing aggregatable data | | [@Authorization](https://github.com/oasis-tcs/odata-vocabularies/tree/main/vocabularies/Org.OData.Authorization.V1.md){target="_blank"} | for authorization requirements | | [@Capabilities](https://github.com/oasis-tcs/odata-vocabularies/tree/main/vocabularies/Org.OData.Capabilities.V1.md){target="_blank"} | for restricting capabilities of a service | | [@Core](https://github.com/oasis-tcs/odata-vocabularies/tree/main/vocabularies/Org.OData.Core.V1.md){target="_blank"} | for general purpose annotations | | [@JSON](https://github.com/oasis-tcs/odata-vocabularies/tree/main/vocabularies/Org.OData.JSON.V1.md){target="_blank"} | for JSON properties | | [@Measures](https://github.com/oasis-tcs/odata-vocabularies/tree/main/vocabularies/Org.OData.Measures.V1.md){target="_blank"} | for monetary amounts and measured quantities | | [@Repeatability](https://github.com/oasis-tcs/odata-vocabularies/tree/main/vocabularies/Org.OData.Repeatability.V1.md){target="_blank"} | for repeatable requests | | [@Temporal](https://github.com/oasis-tcs/odata-vocabularies/tree/main/vocabularies/Org.OData.Temporal.V1.md){target="_blank"} | for temporal annotations | | [@Validation](https://github.com/oasis-tcs/odata-vocabularies/tree/main/vocabularies/Org.OData.Validation.V1.md){target="_blank"} | for adding validation rules | ### [SAP Vocabularies](https://github.com/SAP/odata-vocabularies#readme){target="_blank"} | Vocabulary | Description | |--------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------| | [@Analytics](https://github.com/SAP/odata-vocabularies/tree/main/vocabularies/Analytics.md){target="_blank"} | for annotating analytical resources | | [@CodeList](https://github.com/SAP/odata-vocabularies/tree/main/vocabularies/CodeList.md){target="_blank"} | for code lists | | [@Common](https://github.com/SAP/odata-vocabularies/tree/main/vocabularies/Common.md){target="_blank"} | for all SAP vocabularies | | [@Communication](https://github.com/SAP/odata-vocabularies/tree/main/vocabularies/Communication.md){target="_blank"} | for annotating communication-relevant information | | [@DataIntegration](https://github.com/SAP/odata-vocabularies/tree/main/vocabularies/DataIntegration.md){target="_blank"} | for data integration | | [@Hierarchy](https://github.com/SAP/odata-vocabularies/blob/main/vocabularies/Hierarchy.md){target="_blank"} | for hierarchies | | [@PDF](https://github.com/SAP/odata-vocabularies/tree/main/vocabularies/PDF.md){target="_blank"} | for PDF | | [@PersonalData](https://github.com/SAP/odata-vocabularies/tree/main/vocabularies/PersonalData.md){target="_blank"} | for annotating personal data | | [@Session](https://github.com/SAP/odata-vocabularies/tree/main/vocabularies/Session.md){target="_blank"} | for sticky sessions for data modification | | [@UI](https://github.com/SAP/odata-vocabularies/tree/main/vocabularies/UI.md){target="_blank"} | for presenting data in user interfaces | [Learn more about annotations in CDS and OData and how they work together](https://github.com/SAP-samples/odata-basics-handsonsapdev/blob/annotations/bookshop/README.md){.learn-more} ### Additional Vocabularies Assuming you have a vocabulary `com.MyCompany.vocabularies.MyVocabulary.v1`, you can set the configuration option cds.cdsc.odataVocabularies.MyVocabulary: {"Alias": "MyVocabulary", "Namespace": "com.sap.vocabularies.MyVocabulary.v1", "Uri": "\"}. With this configuration, all annotations prefixed with `MyVocabulary` are considered in the translation. ```cds service S { @MyVocabulary.MyAnno: 'My new Annotation' entity E { /*...*/ }; }; ``` The annotation is added to the OData API, as well as the mandatory reference to the vocabulary definition: ```xml ... ``` The compiler evaluates neither annotation values nor the URI. It is your responsibility to make the URI accessible if necessary. Unlike for the standard vocabularies listed above, the compiler has no access to the content of the vocabulary, so the values are translated generically. ## Data Aggregation Data aggregation in OData V4 is leveraged by the `$apply` system query option, which defines a pipeline of transformations that is applied to the _input set_ specified by the URI. On the _result set_ of the pipeline, the standard system query options come into effect.

### Example ```http GET /Orders(10)/books? $apply=filter(year eq 2000)/ groupby((author/name),aggregate(price with average as avg))/ orderby(title)/ top(3) ``` This request operates on the books of the order with ID 10. First, it filters out the books from the year 2000 to create an intermediate result set. The system then groups the intermediate result set by author name and averages the price. Finally, the system sorts the result set by title and retains only the top three entries. ::: warning If the `groupby` transformation only includes a subset of the entity keys, the result order might be unstable. ::: ### Transformations | Transformation | Description | Node.js | Java | |------------------------------|----------------------------------------------|:------------------:|:-----:| | `filter` | filter by filter expression | | | | `search` | filter by search term or expression | | | | `groupby` | group by dimensions and aggregates values | | | | `aggregate` | aggregate values | | | | `compute` | add computed properties to the result set | | | | `expand` | expand navigation properties | | | | `concat` | append additional aggregation to the result | | | | `skip` / `top` | paginate | | | | `orderby` | sort the input set | | | | `topcount`/`bottomcount` | retain highest/lowest _n_ values | | | | `toppercent`/`bottompercent` | retain highest/lowest _p_% values | | | | `topsum`/`bottomsum` | retain _n_ values limited by sum | | | | `TopLevels` | retain only _n_ levels of a hierarchy | ² | ^1,2 | | `ancestors/descendants` | retain ancestors/descendants of specific nodes | ² | ^1,2 | ¹ - supported on SAP HANA, H2 ad PostgreSQL only ² - only to support requests from the UI5 Tree Table #### `concat` The [`concat` transformation](https://docs.oasis-open.org/odata/odata-data-aggregation-ext/v4.0/cs02/odata-data-aggregation-ext-v4.0-cs02.html#_Toc435016581) applies additional transformation sequences to the input set and concatenates the result: ```http GET /Books?$apply= filter(author/name eq 'Bram Stroker')/ concat( aggregate($count as totalCount), groupby((year), aggregate($count as countPerYear))) ``` This request filters all books, keeping only books by Bram Stroker. From these books, `concat` calculates (1) the total count of books _and_ (2) the count of books per year. The result is heterogeneous. The `concat` transformation must be the last of the apply pipeline. If `concat` is used, then `$apply` can't be used in combination with other system query options. #### `skip`, `top`, and `orderby` Beyond the standard transformations specified by OData, CDS Java supports the transformations `skip`, `top`, and `orderby` that allow you to sort and paginate an input set: ```http GET /Order(10)/books? $apply=orderby(price desc)/ top(500)/ groupby((author/name),aggregate(price with max as maxPrice)) ``` This query groups the 500 most expensive books by author name and determines the price of the most expensive book per author. ### Aggregation Methods | Aggregation Method | Description | Node.js | Java | |--------------------|----------------------------------|:-------:|:-----:| | `min` | smallest value | | | | `max` | largest | | | | `sum` | sum of values | | | | `average` | average of values | | | | `countdistinct` | count of distinct values | | | | custom method | custom aggregation method | | | | custom aggregate | predefined custom aggregate | | | | `$count` | number of instances in input set | | | ### Custom Aggregates Instead of explicitly using an expression with an aggregation method in the `aggregate` transformation, the client can use a _custom aggregate_. A custom aggregate can be considered as a virtual property that aggregates the input set. It's calculated on the server side. The client doesn't know _How_ the custom aggregate is calculated. They can only be used for the special case when a default aggregation method can be specified declaratively on the server side for a measure. A custom aggregate is declared in the CDS model as follows: * The measure must be annotated with an `@Aggregation.default` annotation that specifies the aggregation method. * The CDS entity should be annotated with an `@Aggregation.CustomAggregate` annotation to expose the custom aggregate to the client. ```cds @Aggregation.CustomAggregate#stock : 'Edm.Decimal' entity Books as projection on bookshop.Books { ID, title, @Aggregation.default: #SUM stock }; ``` With this definition, it's now possible to use the custom aggregate `stock` in an `aggregate` transformation: ```http GET /Books?$apply=aggregate(stock) HTTP/1.1 ``` which is equivalent to: ```http GET /Books?$apply=aggregate(stock with sum as stock) HTTP/1.1 ``` #### Currencies and Units of Measure If a property represents a monetary amount, it may have a related property that indicates the amount's *currency code*. Analogously, a property representing a measured quantity can be related to a *unit of measure*. To indicate that a property is a currency code or a unit of measure, it can be annotated with the [Semantics Annotations](https://help.sap.com/docs/SAP_NETWEAVER_750/cc0c305d2fab47bd808adcad3ca7ee9d/fbcd3a59a94148f6adad80b9c97304ff.html) `@Semantics.currencyCode` or `@Semantics.unitOfMeasure`. The aggregation method (typically, sum) is specified with the `@Aggregation.default` annotation. ```cds @Aggregation.CustomAggregate#amount : 'Edm.Decimal' @Aggregation.CustomAggregate#currency : 'Edm.String' entity Sales { key id : GUID; productId : GUID; @Semantics.amount.currencyCode: 'currency' @Aggregation.default: #SUM amount : Decimal(10,2); @Semantics.currencyCode currency : String(3); } ``` All properties annotated with `@Semantics.currencyCode` or `@Semantics.unitOfMeasure` are exposed as a [custom aggregate](./odata#custom-aggregates) with the property's name that returns: * The property's value if it's unique within a group of dimensions * `null` otherwise A custom aggregate for a currency code or unit of measure should also be exposed by the `@Aggregation.CustomAggregate` annotation. Moreover, a property for a monetary amount or a measured quantity should be annotated with `@Semantics.amount.currencyCode` or `@Semantics.quantity.unitOfMeasure` to reference the corresponding property that holds the amount's currency code or the quantity's unit of measure, respectively. ### Other Features | Feature | Node.js | Java | |-----------------------------------------|:-------:|:-----:| | use path expressions in transformations | | | | chain transformations | | | | chain transformations within group by | | | | `groupby` with `rollup`/`$all` | | | | `$expand` result set of `$apply` | | | | `$filter`/`$search` result set | | | | sort result set with `$orderby` | | | | paginate result set with `$top`/`$skip` | | | ## Open Types An entity type or a complex type may be declared as _open_, which allows clients to add properties dynamically to instances of the type. Clients do this by specifying uniquely named property values in the payload used to insert or update an instance of the type. To indicate that the entity or complex type is open, annotate the corresponding type with `@open`: ```cds service CatalogService { @open // [!code focus] entity Book { // [!code focus] key id : Integer; // [!code focus] } // [!code focus] } ``` The _cds build_ for OData v4 renders the entity type `Book` in `edmx` with the [`OpenType` attribute](https://docs.oasis-open.org/odata/odata-csdl-xml/v4.01/odata-csdl-xml-v4.01.html#sec_OpenEntityType) set to `true`: ```xml // [!code focus] ``` The entity `Book` is open, which allows the client to enrich the entity with additional properties. Example 1: ```json {"id": 1, "title": "Tow Sawyer"} ``` Example 2: ```json {"title": "Tow Sawyer", "author": { "name": "Mark Twain", "age": 74 } } ``` Open types can also be referenced in non-open types and entities. This, however, doesn't make the referencing entity or type open. ```cds service CatalogService { type Order { guid: Integer; book: Book; } @open // [!code focus] type Book {} // [!code focus] } ``` The following payload for `Order` is allowed: `{"guid": 1, "book": {"id": 2, "title": "Tow Sawyer"}}` Note that type `Order` itself is not open, so it doesn't allow dynamic properties, in contrast to type `Book`. ::: warning Dynamic properties are not persisted in the underlying data source automatically and must be handled completely by custom code. ::: ### Java Type Mapping #### Simple Types The simple values of a deserialized JSON payload can be of type: `String`, `Boolean`, `Number` or simply an `Object` for `null` values. |JSON | Java Type of the `value` | |-------------------------|--------------------------------| |`{"value": "Tom Sawyer"}`| `java.lang.String` | |`{"value": true}` | `java.lang.Boolean` | |`{"value": 42}` | `java.lang.Number` (Integer) | |`{"value": 36.6}` | `java.lang.Number` (BigDecimal)| |`{"value": null}` | `java.lang.Object` | #### Structured Types The complex and structured types are deserialized to `java.util.Map`, whereas collections are deserialized to `java.util.List`. |JSON | Java Type of the `value` | |-------------------------------------------------------------------|--------------------------------------| |`{"value": {"name": "Mark Twain"}}` | `java.util.Map` | |`{"value":[{"name": "Mark Twain"}, {"name": "Charlotte Bronte"}}]}`| `java.util.List>`| ## Singletons A singleton is a special one-element entity introduced in OData V4. You can address it directly by its name from the service root without specifying the entity's keys. Annotate an entity with `@odata.singleton` or `@odata.singleton.nullable` to use it as a singleton within a service, for example: ```cds service Sue { @odata.singleton entity MySingleton { key id : String; // can be omitted in OData v4.01 prop : String; assoc : Association to myEntity; } } ``` You can also define it as an ordered `SELECT` from another entity: ```cds service Sue { @odata.singleton entity OldestEmployee as select from Employees order by birthyear; } ``` ### Requesting Singletons As mentioned earlier, you can access singletons without specifying keys in the request URL. They can contain navigation properties, and other entities can include singletons as their navigation properties as well. The `$expand` query option is also supported. ```http GET …/MySingleton GET …/MySingleton/prop GET …/MySingleton/assoc GET …/MySingleton?$expand=assoc ``` ### Updating Singletons The following request updates a _prop_ property of a singleton _MySingleton_: ```http PATCH/PUT …/MySingleton {prop: “New value”} ``` ### Deleting Singletons A `DELETE` request to a singleton is possible only if you annotate a singleton with `@odata.singleton.nullable`. An attempt to delete a singleton annotated with `@odata.singleton` results in an error. ### Creating Singletons Since singletons represent a one-element entity, the system doesn't support a `POST` request.

## V2 Support While CAP defaults to OData V4, the latest protocol version, older projects may need to fall back to OData V2, for example, to keep using existing V2-based UIs. ::: warning OData V2 is deprecated. Use OData V2 only if you need to support existing UIs or if you need to use specific controls that don't work with V4 _yet_, such as tree tables (sap.ui.table.TreeTable). ::: ### Enabling OData V2 via CDS OData V2 Adapter in Node.js Apps { #odata-v2-adapter-node} CAP Node.js supports serving the OData V2 protocol through the [_OData V2 adapter for CDS_](https://www.npmjs.com/package/@cap-js-community/odata-v2-adapter), which translates between the OData V2 and V4 protocols. For Node.js projects, add the CDS OData V2 adapter as express.js middleware as follows: 1. Add the adapter package to your project: ```sh npm add @cap-js-community/odata-v2-adapter ``` 2. Access OData V2 services at [http://localhost:4004/odata/v2/${path}](http://localhost:4004/odata/v2). 3. Access OData V4 services at [http://localhost:4004/odata/v4/${path}](http://localhost:4004/odata/v4) (as before). Example: Read service metadata for `CatalogService`: - CDS: ```cds @path:'/browse' service CatalogService { ... } ``` - OData V2: `GET http://localhost:4004/odata/v2/browse/$metadata` - OData V4: `GET http://localhost:4004/odata/v4/browse/$metadata` [Find detailed instructions at **@cap-js-community/odata-v2-adapter**.](https://www.npmjs.com/package/@cap-js-community/odata-v2-adapter){.learn-more} ### Using OData V2 in Java Apps In CAP Java, serving the OData V2 protocol is supported natively by the [CDS OData V2 Adapter](../../java/migration#v2adapter). ## Miscellaneous ### Omitting Elements From APIs Add annotation `@cds.api.ignore` to suppress unwanted entity fields (for example, foreign key fields) in APIs exposed from the CDS model, that is, OData or OpenAPI. For example: ```cds entity Books { ... @cds.api.ignore author : Association to Authors; } ``` Note that `@cds.api.ignore` is effective on regular elements that are rendered as `Edm.Property` only. The annotation doesn't suppress an `Edm.NavigationProperty`, which is rendered for associations or compositions. If you annotate a managed association, the system propagates the annotations to the (generated) foreign keys. In the previous example, the system mutes the foreign keys of the managed association `author` in the API. ### Absolute Context URL { #absolute-context-url} In some scenarios, you need an absolute [context URL](https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html#sec_ContextURL). In the Node.js runtime, you can achieve this through configuration `cds.odata.contextAbsoluteUrl`. You can use your own URL (including a protocol and a service path), for example: ```js cds.odata.contextAbsoluteUrl = "https://your.domain.com/yourService" ``` to customize the annotation as follows: ```json { "@odata.context":"https://your.domain.com/yourService/$metadata#Books(title,author,ID)", "value":[ {"ID": 201,"title": "Wuthering Heights","author": "Emily Brontë"}, {"ID": 207,"title": "Jane Eyre","author": "Charlotte Brontë"}, {"ID": 251,"title": "The Raven","author": "Edgar Allan Poe"} ] } ``` If you set `contextAbsoluteUrl` to something truthy that doesn't match `http(s)://*`, the system constructs an absolute path based on the environment of the application on a best effort basis. We encourage you to stay with the default relative format, if possible, as it's proxy safe. ### Parallel Processing of Atomicity Groups in Node.js Apps ###### Atomicity Groups By default, atomicity groups in an OData `$batch` request are processed sequentially. In some specific scenarios, such as custom overview pages with multiple data sources, this may result in high roundtrip times. Hence, for `$batch` requests that exclusively contain `GET` requests, you can enable parallel processing of atomicity groups to improve throughput. cds.odata.max_batch_parallelization = 1 specifies the maximum number of atomicity groups processed concurrently. The default is `1`, which means sequential processing. ::: warning OData Specification Violation Parallel processing of atomicity groups is in conflict with the OData specification for `multipart/mixed`, which requires sequential processing. For example, the `continue-on-error` preference default can then no longer be adhered to. :::