cds-dk.md

status
released

CDS Design Time APIs

This guide is about programmatic CDS design-time APIs.

[[toc]]

Install @sap/cds-dk

The design-time APIs are provided with package @sap/cds-dk which needs to be installed locally in your project:

npm add @sap/cds-dk

That given, you can use the APIs in your project like this:

const cds = require('@sap/cds-dk')
cds.import(...)

cds.import() {.method}

As an application developer, you have the option to convert OData specification (EDMX / XML), OpenAPI specification (JSON) or AsyncAPI specification (JSON) files to CSN from JavaScript API as an alternative to the cds import command.

cds.import is available in the CDS development tool kit version 4.3.1 onwards .

The API signature looks like this:

const csn = await cds.import(file, options)

Arguments:

• file — Specify the path to a single input file to be converted for CSN.
• options — cds.import() support the following options:

options.keepNamespace

This option is only applicable for OData conversion.

Value	Description
true	Keep the original namespace from the EDMX content.
false	Take the filename as namespace.

If the option is not defined, then the CSN is generated with the namespace defined as EDMX filename.

options.includeNamespaces

This option is only applicable for OData conversion.
It accepts a list of namespaces whose attributes are to be retained in the CSN / CDS file. To include all the namespaces present in the EDMX pass "*".

For OData V2 EDMX attributes with the namespace "sap" & "m" are captured by default.

cds.import.from.edmx() {.method}

This API can be used to convert the OData specification file (EDMX / XML) into CSN. The API signature looks like this:

const csn = await cds.import.from.edmx(ODATA_EDMX_file, options)

cds.import.from.openapi() {.method}

This API can be used to convert the OpenAPI specification file (JSON) into CSN. The API signature looks like this:

const csn = await cds.import.from.openapi(OpenAPI_JSON_file)

cds.import.from.asyncapi() {.method}

This API can be used to convert the AsyncAPI specification file (JSON) into CSN. The API signature looks like this:

const csn = await cds.import.from.asyncapi(AsyncAPI_JSON_file)

Example:

const cds = require('@sap/cds-dk')
module.exports = async (srv) => {
  const csns = await Promise.all([
    // for odata
    cds.import('./odata_sample.edmx', { includeNamespaces: 'sap,c4c', keepNamespace: true }),
    // for openapi
    cds.import('./openapi_sample.json'),
    // for asyncapi
    cds.import('./asyncapi_sample.json'),
    // for odata
    cds.import.from.edmx('./odata_sample.xml', { includeNamespaces: '*', keepNamespace: false }),
    // for openapi
    cds.import.from.openapi('./openapi_sample.json')
    // for asyncapi
    cds.import.from.asyncapi('./asyncapi_sample.json')
  ]);

  for (let i = 0; i < csns.length; i++) {
    let json = cds.compile.to.json (csns[i])
    console.log (json)
  }
}

OData Type Mappings

The following mapping is used during the import of an external service API, see Using Services. In addition, the Mapping of CDS Types shows import-related mappings.

OData	CDS Type
Edm.Single	cds.Double + @odata.Type: 'Edm.Single'
Edm.Byte	cds.Integer + @odata.Type: 'Edm.Byte'
Edm.SByte	cds.Integer + @odata.Type: 'Edm.SByte'
Edm.Stream	cds.LargeBinary + @odata.Type: 'Edm.Stream'
Edm.DateTimeOffset Precision : Microsecond	cds.Timestamp + @odata.Type:'Edm.DateTimeOffset' + @odata.Precision:<>
Edm.DateTimeOffset Precision : Second	cds.DateTime + @odata.Type:'Edm.DateTimeOffset' + @odata.Precision:0
Edm.DateTime Precision : Microsecond 1	cds.Timestamp + @odata.Type:'Edm.DateTime' + @odata.Precision:<>
Edm.DateTime Precision : Second 1	cds.DateTime + @odata.Type:'Edm.DateTime' + @odata.Precision:0

¹ only OData V2