CX Works

CX Works brings the most relevant leading practices to you.
It is a single portal of curated, field-tested and SAP-verified expertise for SAP Customer Experience solutions

Data Model Design with the SAP Commerce Cloud Type System

6 min read

Data Model Design with the SAP Commerce Cloud Type System

The Type System in SAP Commerce Cloud allows for both creating new types and for extending existing types with either attributes or relations to other types. The type system definition impacts the database schema, which affects how you import, maintain, and show data across your application. If you do not have a zero downtime deployment setup, then these changes to the database schema will affect the update of the system. This will result in downtime for your system. Most importantly, an incorrect configuration can lead to incorrect behavior of the system or performance issues. This article provides recommended practices for the setup of the type system.

Table of Contents

General Recommended Practices

In general, the recommendations outlined in this article for your *-items.xml files should be included and reviewed as part of your coding standards. Before going into specific rules around the type system, it is important to ensure whenever you make changes to the *-items.xml file(s), you run a Type System Update to ensure your database schema aligns with your *-items.xml definitions.

When creating and reviewing changes to your *-items.xml files, you should use the consolidated list of recommended practices for the type system, which are covered by this page.

Extending Existing Type vs Subtype

When extending an existing type to add new attributes, you can either add the attributes to the existing type:

<itemtype code="Product" autocreate="false" generate="false">
     <attribute qualifier="newAttribute" type="java.lang.String">
     <modifiers read="true" write="true" search="true" optional="true"/>
      <persistence type="property"/>

Or you can subtype:

<itemtype code="MyProduct" extends="Product" autocreate="true" generate="true">
     <attribute qualifier="newAttribute" type="java.lang.String">
     <modifiers read="true" write="true" search="true" optional="true"/>
      <persistence type="property"/>

Whether to extend the existing type or to subtype should be based on the following decisions:

Change Existing or Sub-Type Reason
Adding an attribute for all instances Existing

If all instances of the existing type could have a value for this data, then the attribute belongs on an existing type.

Creating an unnecessary subtype can create issues because a business user could create an instance of the supertype that doesn't have all the required or expected attributes, such as, a user could create instances of items that are incompatible with the business logic. For example, if you subtype category and create a new type with a mandatory attribute called "enabledForFrontend", business users can still create a standard category item that doesn't have the required attribute that the front end is expecting.

In addition, the SAP Commerce APIs expect the existing type, so the project code will be cluttered by "if instanceof then (cast)" constructs if a subtype is used.

Adding an attribute for specific instances Subtype

If only some instances have data for a particular attribute, then you should subtype. 

Re-declaring an existing attribute

For example, change mandatory to optional

Subtype Re-declaring requires subtyping.

You should redeclare only when necessary. Otherwise, potential issues can arise if business users still use the existing types that don't have the attributes required by the system. If subtyping is required, then consider redeclaring attributes, so the new subtypes are returned instead of the existing types.

Although it is typical for implementations to extend an SAP Commerce Cloud type by subclassing, it is preferable to override the type and embed the new fields into it.

For example, if a customer wants to add new fields to the Category model, the standard approach used in implementations is to subclass it. If the new fields will be shared by other subclasses or no other direct subclasses will exist, it is preferable to add the new fields directly to the Category model. This results in a simplification of the data model and the queries against the data model.

Finally, rather than extending or subclassing a type, it may be preferable use a composition approach in which you create new types with relations to the core SAP Commerce Cloud types.

Type System Cleanup

Over time, you may have made changes to your type system where attributes or types were removed from your *-items.xml and code. They are not, however, automatically removed from your database. Depending on the data type or attribute, this could be a significant amount of data with no purpose. Whenever you're making changes to the type system, we recommend to add (and test) cleanup steps in your deployment checklist.


Every change to the type system should be treated with the utmost importance, as it can have an impact on your system. Even though there are many recommended practices, ensuring you incorporate them as part of your development lifecycle, will lead to catching potential issues early on. It is easier to ensure the type system is correct from the start then fixing issues later.