RAP Composition: Root and Child Entities

A composition is the CDS association, marked as a composition, that links a root entity to a child entity in the behavior definition, and it is declared on the root's side as owning the child. The structural fact that explains most of the confusion: a composition child has no life of its own. It is not a separately lockable, separately authorized, separately savable object. Its lock is the root's lock, its authorization check defaults to the root's authorization object, its ETag comes from the root, and its create, update and delete are executed inside the root's save sequence, not as independent transactions. People coming from a classic table-and-BAPI mindset instinctively reach for a separate service or a separate action to touch the child, and that instinct is wrong for anything modelled as a composition child. If a child genuinely needs an independent existence, it should not be a composition child, it should be its own root reached by an ordinary association.

Use composition for header/item and header/schedule-line style structures where the child cannot meaningfully exist without the header and must always be maintained inside the same transaction: sales document and items, travel and bookings, purchase requisition and items. Use it when deleting the root should delete the children, when the same lock must cover both, and when the object page in Fiori Elements needs a header with editable sub-tables. Do not use composition when the child is master data shared across many parents, such as a business partner referenced from an order, or when the child needs to be queried and changed outside the context of any particular root. Do not use it either as a substitute for a reporting fan-out; a read-only expand for display purposes is better served by a plain to-many association, which carries none of the transactional weight.

Composition sits in the behavior definition layer, built on top of the CDS view entities that model root and child, and it is what the service definition exposes as a deep-insertable, nested OData entity set with dollar-expand. Below it sits the persistence: separate database tables for root and child, tied together by the composition's foreign key, and a draft table pair if draft handling is active. Above it sits the save sequence, which the RAP runtime orchestrates across early and late numbering phases, and the Fiori Elements object page, which renders the child as a facet table. Composition replaces what used to be hand-coded header-item consistency logic inside a BAPI or function module: manual FOR ALL ENTRIES joins, manual enqueue of both header and item lock objects, and manual cascading delete logic. In RAP those are runtime-provided once the composition is declared correctly.

Take a travel-and-booking style object: root entity for Travel, child entity for Booking, connected by a composition association exposed in the root's behavior definition as owning the booking node with create, update and delete operations. A user opens the object page for a travel, adds two bookings, and saves once. The OData deep insert sends one payload with the travel header and a nested array of bookings. The RAP runtime creates the root first, assigns a number if early numbering is used, then processes the child creates inside the same LUW, assigning booking IDs through late numbering since the parent key may not be final until the draft is activated. A determination on the root recalculates the total booking amount whenever a child is inserted or changed, triggered by the association between the nodes. When the travel is deleted, the booking rows are removed as part of the same operation because they are modelled as composition children, not as independently persisted rows with only a foreign key relationship.

Composition is a standard, clean-core-aligned building block for custom business objects on S/4HANA; it is the recommended way to model header/item structures instead of hand-rolled header-item consistency logic in a custom function module or BAPI. There is no equivalent construct in classic ECC development; the pattern it replaces there is manual enqueue of a header lock object plus a separate item lock object, and manual delete cascading written by hand. There is no automated migration path from an ECC header-item BAPI to a RAP composition; it requires a fresh behavior definition designed around the actual business rule for what must be atomic.

The developer implements the CDS composition association and the behavior definition and implementation class for both root and child. The architect decides where the composition boundary lies, which entities belong inside one business object versus being linked by a plain association, and reviews the lock and performance implications of the chosen depth. The functional consultant supplies the business rule for what must always be saved together.

Read the behavior definition and implementation page for how composition operations are actually coded, the draft handling page for how deep drafts multiply the moving parts, and the late numbering page for why composition children almost always need late key assignment. The determinations and validations page explains how child changes trigger recalculation on the root, and the CDS associations versus joins page clarifies when a plain association is the right choice instead of a composition.