C0 Developer Extensibility for CDS Data Models

AndreaUS · ‎08-18-2022

This blog post explains how to enable CDS data models for C0 developer extensibility, how to find extensible models, and how to extend such a model by means of developer extensibility.
It answers the following questions:

What is developer extensibility?
What is the C0 release contract?
How do you design a CDS data model as C0 released API?
How can you find C0 released APIs in ADT?
How do you extend a C0 released CDS view?

Ready? Let’s go.

1. What is developer extensibility?

Developer Extensibility is the new extensibility option on ABAP Platform, available since ABAP Platform 2021. It enables cloud-ready and upgrade-stable custom ABAP code in cloud projects, combining the benefits of custom ABAP code with the required restrictions for cloud readiness. It delivers flexibility beyond key user extensibility patterns, with debugging, rich developer IDE, custom applications, and packaged solutions.
One use case for developer extensibility is the ABAP RESTful Application Programming Model (RAP). It allows you to extend your RAP application from the database to the service definition directly in ADT with custom ABAP code.
This blog post explains developer extensibility on CDS level.
For further details on developer extensibility, visit SAP Extensibility Explorer for SAP S/4HANA Cloud (ondemand.com)

2. What is the C0 release contract?

A release contract is a classification of a repository object as released API and it ensures a certain stability of the repository object in question. There are currently four different release contracts at SAP:

C0 release contract for extensibility.
C1 release contract for system-internal use.
C2 release contract for use as remote API.
C3 release contract, manage configuration content.

The C0 release contract ensures stability of a repository object at dedicated extension points. The C0 contract is a prerequisite for developer extensibility in cloud development.

3. How do you design a CDS data model as C0 released API?

The following CDS entities can be released under the C0 stability contract: CDS view entities, CDS projection views, CDS abstract entities, and CDS custom entities.
As a prerequisite for C0 release, your entity requires certain extensibility annotations.
The following annotations are mandatory:

@AbapCatalog.extensibility.extensible must be set to true.
@AbapCatalog.extensibility.elementSuffix must define a 3-character long element suffix.
@AbapCatalog.extensibility.quota.maximumFields defines the maximum number of fields that can be added to the CDS entity in question via extensions. It must be an integer between 0 and 1000.
@AbapCatalog.extensibility.quota.maximumBytes defines the maximum number of bytes that can be added to the CDS entity in question via extensions. It must be an integer between 0 and 10.000.
Only for views (CDS view entity and CDS projection view): @AbapCatalog.extensibility.dataSources defines stable alias names for data sources and associations that can be used by extensions. The data sources and associations which are allowlisted in this way must themselves be released, either under the C0 contract, or under the C1 contract.

The following annotations are optional:

@AbapCatalog.extensibility.allowNewDatasources: Possible values are true or false, but true is allowed only in CDS projection views. When set to true, consumers of the released API are allowed to use new data sources. This means that a consumer can use a newly defined association in a path expression to include a field from a new data source in the extension.
@AbapCatalog.extensibility.allowNewCompositions: Possible values are true or The value true is a prerequisite for node extensibility. It explicitly allows consumers of the released API to add new child nodes to a CDS data model.

Example
The following CDS view entity DEMO_CDS_PRODUCTTP_E is based on the DDIC database table DEMO_PRODUCT and it fulfills all requirements for C0 release:

It defines the necessary extensibility annotations.
It is part of a transactional RAP application (indicated by the ROOT characteristic).
It defines the stable data source Persistence which fulfills all requirements necessary for C0 release.

@EndUserText.label: 'Demo for C0 released API'
@AccessControl.authorizationCheck: #NOT_REQUIRED
@Metadata.ignorePropagatedAnnotations: true
@AbapCatalog.extensibility: {
  extensible: true,
  elementSuffix: 'DMO',
  allowNewDatasources: false,
  dataSources: ['Persistence'],
  quota: {
    maximumFields: 250,
    maximumBytes: 2500
  }
}
define view entity DEMO_CDS_PRODUCTTP_E
  as select from demo_product as Persistence
{
  key product_id
}

This example is taken from the ABAP Keyword Documentation and it is part of the package SABAPDEMOS.
When your CDS entity meets all requirements, go to Properties > API State and add the C0 release contract for Use in Cloud Development.
Step 1:

Step 2:

Step 3:

The tool immediately checks whether your entity fulfills all requirements and release is only possible if all tests are passed.

4. How can you find C0 released APIs in ADT?

Where can you find C0-released APIs shipped by SAP for developer extensibility? How do you find out whether you can extend a certain application?
1) ABAP Keyword Documentation
A list of all released APIs delivered by SAP Basis can be found in topic Released APIs.

2) ADT folder
You can configure your ADT to display a folder with C0 released APIs as follows:

Right-click the respective project and click New > ABAP Repository Tree.

On the Create Tree screen, choose Blank and click Next.

On the next screen, enter a tree name in field Tree Name and insert the following property filter: api: Extend_in_cloud_development.Click Finish.

Result: Your ADT project now has a folder which lists C0 released APIs for the selected project:

3) Check the API state of an object
You find the API state of an individual repository object in the Properties tab in section called API State.

5. How do you extend a C0 released CDS view?

As a prerequisite, the view you want to extend must be released under the C0 stability contract.
There are a few rules to obey if you want to extend a C0 released API, most importantly naming conventions:

Prefix: Elements and associations need an alias name which uses the correct namespace prefix, such as ZZ or YY. Associations must start with an underscore (_).
Suffix: All elements and associations defined in the extension must have the element suffix that is defined in the released API by means of the annotation @AbapCatalog.extensibility.elementSuffix.
Data source prefix: In extensions to CDS view entities and CDS projection views, all elements and associations defined in the extension must have the alias name of a stable data source, defined by the annotation @AbapCatalog.extensibility.dataSources, as prefix.

Example
The following extension extends the CDS view entity DEMO_CDS_PRODUCTTP_E displayed above. It fulfills all requirements for consuming a C0 released API from the restricted ABAP language version ABAP for Cloud Development:

The extension fields are derived from the stable data source Persistence and use the alias name of the stable data source as prefix.
The newly defined association _zz_ToUnit_DMO uses the mandatory element suffix DMO.
The association target DEMO_CDS_UNIT of the newly defined association _zz_ToUnit_DMO is C1 released.

extend view entity DEMO_CDS_PRODUCTTP_E with
association [0..1] to DEMO_CDS_UNIT as _zz_ToUnitDMO 
  on $projection.zz_unit_dmo = _zz_ToUnitDMO.UnitOfMeasure
{
  @Semantics.quantity.unitOfMeasure: 'zz_unit_dmo'
  Persistence.zz_quantity_dmo,
  Persistence.zz_unit_dmo,
  _zz_ToUnitDMO
}

This example is taken from the ABAP Keyword Documentation and it is part of the package SABAPDEMOS.

Release Info

C0 developer extensibility for CDS entities has been available since release 2108, ABAP release 7.85, on premise 7.56. However, there's one restriction: currently, only CDS entities that are part of a RAP BO are available for C0 release. General availability is planned for release 2302.
CDS custom entity extensions were added a bit later, with release 2208, ABAP release 7.89, next big on premise shipment.

Further information

ABAP Keyword Documentation on SAP Help Portal: C0 Contract Rules.

Questions are welcome.