05 · CDS Schema Basics

Introduction to Core Data Services syntax — using, namespace, entity, type, and service keywords.

Lesson 5 — CDS Schema Basics

What you'll learn

The full CDS grammar — namespaces, entity definitions, service definitions, and the core keywords you'll use in every CAP project.

What is CDS?

CDS (Core Data Services) is CAP's domain-specific language for describing data and services. It compiles into SQL (for the database), OData (for the API), and TypeScript types (for your IDE).

One .cds file can replace hundreds of lines of boilerplate SQL, OData XML, and TypeScript declarations.

Namespaces

Namespaces prevent name collisions when your project grows or imports from other packages.

namespace com.mycompany.bookshop;

entity Books { ... }
// Full name: com.mycompany.bookshop.Books

Convention: Use reverse-domain notation like Java packages — com.companyname.project.

You can have multiple namespaces in one project. Each file can declare its own:

// db/products.cds
namespace com.mycompany.products;
entity Product { ... }

// db/orders.cds
namespace com.mycompany.orders;
entity Order { ... }

Basic entity definition

entity Books {
  key ID    : UUID;
      title : String(100);
      price : Decimal(10,2);
      stock : Integer default 0;
      active: Boolean default true;
}

Syntax rules:
- key marks the primary key field(s)
- Type comes after : (colon)
- default sets a default value
- Fields without not null are nullable by default

Built-in scalar types

CDS Type	SQL equivalent	Use for
`UUID`	NVARCHAR(36)	Primary keys
`String(n)`	NVARCHAR(n)	Short text
`LargeString`	CLOB / NCLOB	Long text, markdown
`Integer`	INTEGER	Whole numbers
`Int64`	BIGINT	Large numbers
`Decimal(p,s)`	DECIMAL(p,s)	Money, measurements
`Double`	DOUBLE	Floating point
`Boolean`	BOOLEAN	True/false
`Date`	DATE	Date only (2024-01-15)
`Time`	TIME	Time only (14:30:00)
`DateTime`	DATETIME	Date + time (no timezone)
`Timestamp`	TIMESTAMP	Date + time + timezone
`Binary(n)`	VARBINARY(n)	Raw bytes

The `using` keyword — imports

Use using to import entities from other files:

// srv/catalog-service.cds
using com.mycompany.bookshop from '../db/schema';
// Now you can reference: com.mycompany.bookshop.Books

// Or import with alias
using com.mycompany.bookshop as bookshop from '../db/schema';
// Now: bookshop.Books

Import specific entities:

using { com.mycompany.bookshop.Books, com.mycompany.bookshop.Authors } from '../db/schema';

Service definitions

A service is a CDS concept that maps to an OData service:

service CatalogService @(path: '/catalog') {
  entity Books   as projection on com.mycompany.bookshop.Books;
  entity Authors as projection on com.mycompany.bookshop.Authors;
}

Key service concepts:
- @(path: '/catalog') — sets the URL path (default is lowercase service name)
- as projection on — exposes an entity through the service
- You can expose multiple entities in one service
- You can have multiple services in one CAP project

Restricting operations

By default, a service entity supports full CRUD. You can restrict it:

service CatalogService {
  // Read-only
  @readonly entity Books as projection on db.Books;

  // Create + read only (no update/delete)
  @insertonly entity Reviews as projection on db.Reviews;

  // Explicit list
  entity Orders as projection on db.Orders
    actions { action cancel(); };
}

Comments in CDS

// Single-line comment

/*
  Multi-line comment
*/

/**
 * Doc comment — appears in OData metadata as @Core.Description
 */
entity Books { ... }

Annotations in CDS

Annotations add metadata that drives OData, Fiori UI, validation, and more:

@title: 'Book Catalog'
entity Books {
  key ID    : UUID;
      @title: 'Book Title'
      @mandatory
      title : String(100);

      @title: 'Price in USD'
      @Measures.ISOCurrency: 'USD'
      price : Decimal(10, 2);
}

We cover annotations in depth in Lesson 14. For now, remember the syntax: @AnnotationName: value placed before the field or entity.

A complete, realistic schema

namespace com.bookshop;
using { cuid, managed } from '@sap/cds/common';

entity Books : cuid, managed {
  title    : String(100) not null;
  descr    : LargeString;
  price    : Decimal(10,2);
  stock    : Integer default 0;
  author   : Association to Authors;
  genre    : Association to Genres;
}

entity Authors : cuid {
  name  : String(100) not null;
  books : Association to many Books on books.author = $self;
}

entity Genres {
  key ID   : Integer;
      name : String(50) not null;
}

Note the cuid and managed aspects — these are SAP's built-in reusable aspects. cuid adds a UUID key called ID. managed adds createdAt, createdBy, modifiedAt, modifiedBy. You'll learn about aspects in Lesson 12.

Checkpoint ✓

[ ] Can you write an entity with 5 different field types?
[ ] Can you add a namespace?
[ ] Can you import and expose an entity in a service?
[ ] Do you understand the difference between entity and service?

In Lesson 6 we go deeper into entities — calculated fields, virtual elements, and all the ways to declare data.