CDS Design Time APIs
This guide is about consuming CDS design-time APIs programmatically.
Import @sap/cds-dk
The design-time APIs are provided with package @sap/cds-dk
and can be used as follows:
- Install it locally:
npm add @sap/cds-dk
npm add @sap/cds-dk
- Import it in Node.js:
const cds = require('@sap/cds-dk')
const cds = require('@sap/cds-dk')
cds.import (file, options) → csn
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)
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 followingoptions
:
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 (file, options) → csn
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)
const csn = await cds.import.from.edmx(ODATA_EDMX_file, options)
cds.import.from.openapi (file) → csn
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)
const csn = await cds.import.from.openapi(OpenAPI_JSON_file)
cds.import.from.asyncapi (file) → csn
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)
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)
}
}
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)
}
}
Special 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 |
1 only OData V2