Data Representation Objects in SAP hybris: Model, DTO and WsDTO

In the world of SAP Commerce Cloud (Hybris), developers often find themselves juggling multiple types of objects that look remarkably similar but serve very different purposes. Developers often encounter three commonly used objects: Model, DTO (Data Object), and WsDTO. We use these objects across different layers of the Hybris architecture to maintain clean code, ensure proper separation of concerns, and enable secure data exposure.

Understanding the difference between these objects is essential for every SAP Commerce developer, especially when working with Facades, Services,  OCC APIs, and Converters. Instead of directly exposing database entities, SAP Commerce follows a layered architecture. Each layer uses a different object type to maintain separation of responsibilities.

Model in SAP Hybris:

The Model is the Java Representation of a database table. You never write a Model class by hand. You define the type in *-items.xml, run the hybris build, and the platform generated the Model class automatically in the bootstrap/gensrc folder.

Example:

<itemtype code="Product" extends="GenericItem" autocreate="true" generate="true">
    <deployment table="Products" typecode="1" propertytable="ProductProps"/>
    <attributes>
        <attribute autocreate="true" qualifier="code" type="java.lang.String" generate="true">
            <persistence type="property"/>
            <modifiers read="true" write="true" search="true" initial="true" optional="false" unique="true"/>
        </attribute>
        <attribute autocreate="true" qualifier="name" type="localized:java.lang.String">
            <modifiers read="true" write="true" search="true" optional="true"/>
            <persistence type="property"/>
        </attribute>
	</attributes>
</itemtype>

After building the platform, hybris automatically generates the corresponding model class: ProductModel.java

Key Characteristics of Models:

• Directly tied to the database: each model maps to a table row via the Service layer persistence engine.
• Lazy-loading: related items are loaded only when accessed, this improves performance by avoiding unnecessary database calls.
• Session-scoped: models are tied to the hybris JaloSession/ persistence context.

DTO (Data Transfer Object):

A DTO acts as a lightweight POJO (Plain Old Java Object) that transfers data from the backend to the frontend (JSP or OCC). You can write DTOs as plain Java classes, but in Hybris, the recommended approach is to define them in -beans.xml so the platform generates them. This keeps DTOs consistent and avoid manual boilerplate.

Example:

<bean class="de.hybris.platform.cmsfacades.data.ProductData">
	<property name="code" type="String" />
	<property name="name" type="java.util.Map&lt;String,String>" />
</bean>

The platform generates a clean Java POJO:

Key Characteristics of DTOs:

• Pure POJOs: DTOs are simple java classes, only contains fields with getter and setters. No business logic included.
• DTOs do not link to database tables, so they remain decoupled from the persistence layer.
• Serializable and thread-safe: DTOs are safe to store, cache, and share across threads.
• Custom Structure: can be modify based on UI needs.
• Security and Data control: DTOs hide sensitive information from frontend. Only exposed necessary data

WsDTO (Web Service Data Transfer Object):

We use WsDTO to send data to the client (response) or receive data from the client (request). You might wonder, why not just expose the DTO directly from the facade layer via the REST API? We use separate WsDTO instead of directly exposing DTO mainly for API control, flexibility, and security.

Example:

<bean class="de.hybris.platform.cmssmarteditwebservices.dto.ProductWsDTO">
	<property name="uid" type="String" />
	<property name="code" type="String" />
</bean>

Key Characteristics of WsDTOs:

• API Contract Stability: If we expose DTO directly through APIs, any internal change can break external clients. WsDTO creates a stable API contract. Even if DTO changes, the API remain stable. This helps maintain backward compatibility.
• JSON/XML ready: Annotated for Jackson serialization, supports field filtering.
• Custom API structure: You can reshape data based on frontend needs. Combine/simplify fields for better API usability.
• Versioning support: OCC APIs often support multiple versions(v1, v2, v3). WsDTO allows creating different API responses for each version without affecting DTO.
• Support Field Filtering: WsDTO controls how much data is returned. The fields= BASIC, DEFAULT, FULL query param controls which fields are included.
• Lightweight and optimized: contains only required fields for API which reduces payload size.

Model vs DTO vs WsDTO – Full Comparison