Modeling the domain with CDS

The domain model describes the things your app owns. For the fleet app, SAP S/4HANA remains the system of record for sales orders and customers; the app owns only what SAP S/4HANA does not have: inquiries raised by the fleet desk, the notes added to them, and a small code list of inquiry topics. Keeping that boundary clear is the first modeling decision, and the most important one: never copy SAP master data into your own tables just because it is convenient.

Entities, types and reuse aspects

The model goes in db/schema.cds:
namespace com.contoso.fleet;
using { cuid, managed, sap.common.CodeList } from '@sap/cds/common';
entity Inquiries : cuid, managed {
salesOrder : String(10) @mandatory;
customer : String(10) @mandatory;
topic : Association to Topics;
priority : Integer @assert.range: [1, 3];
status : String(12) default 'New';
notes : Composition of many Notes on notes.inquiry = $self;
}
entity Notes : cuid, managed {
inquiry : Association to Inquiries;
text : String(1000);
}
entity Topics : CodeList {
key code : String(10);
}
The CodeList aspect gives Topics a localized name and descr and marks the entity as a value list.

Two reuse aspects from @sap/cds/common do a lot of work. cuid adds a UUID primary key, which CAP fills automatically on create. managed adds createdAt, createdBy, modifiedAt and modifiedBy, filled by the runtime from the current time and user. For testers that is free audit evidence: every inquiry records who created and last changed it. The common package also offers reuse types such as Country, Currency and Language with their code lists.

Associations and compositions

An association is a relationship between independent things: an inquiry refers to a topic, but the topic exists on its own. A managed to-one association such as topic : Association to Topics gets its foreign key generated (in the database you will see a column like topic_code). A to-many association needs an on condition pointing back to the to-one side. A composition models containment: notes belong to their inquiry and make no sense without it. CAP treats compositions as documents, with deep insert and update (create an inquiry and its notes in one request) and cascaded delete.

Modeling conventions

• Names: capitalized, plural entity names (Inquiries, Notes); lowercase element names; no repeated context (name, not topicName).
• Flat models: prefer simple elements to nested structured types, which some consumers handle poorly.
• Keys: a single technical key such as cuid; do not give UUIDs meaning.
• Namespaces: reverse domain names such as com.contoso.fleet, not short-lived project code names.
• Localized texts: mark text elements as localized (for example topic names) and CAP generates the texts tables.
• Separation of concerns: put UI annotations and authorization in separate files that annotate or extend the core model.

Test data

CAP loads .csv files automatically when it bootstraps a database. Files are named after the namespace and entity, for example db/data/com.contoso.fleet-Topics.csv, and cds add data generates empty files with the right headers. Keep reference data needed in every environment (the topic list) apart from test data used only locally or in tests (sample inquiries); CAP supports a separate test/data folder for the latter. Contoso's test data uses the canonical fleet customer Great Lakes Fleet Services and product CMC-ALT-100, so local results look like what testers later see in CMQ.