CLEAN CORE ARCHITECTURAL GUIDE #19

SAP Clean Core Contract C1 Release & API Governance Architecture

Author: Andrea Antonio Perrelli Scope: SAP S/4HANA (Cloud & On-Premise) & BTP ABAP Environment Standard: SAP Release Contracts & Business Object Interfaces (BOI)

Core Clean Core Principle: In classic SAP ERP, custom code called any function, read any table, or invoked any class without restriction. When SAP updated an internal function signature during an upgrade, customer code broke immediately. Clean Core eliminates this fragility through Release Contracts: custom code may only consume artifacts formally released with stability commitments.

Limited Time Deal

Master S/4HANA Clean Core Architecture & C1 Contracts

Get the Complete SAP Enterprise Architecture Suite: 40 Retina architecture diagrams, 61 production-grade code listings, and decision frameworks. Use code FLASH80 at checkout for 80% OFF.

📦 Get Enterprise Suite (€9.80 with FLASH80) 📚 Paperback on Amazon ($19.99) 📜 Launch C1 Contract Generator

1. The Official Release Contract Taxonomy

SAP defines five distinct release contracts governing who can consume an development object:

Contract Type	Official Name	Permitted Consumers	Typical Artifacts
Contract C1	Use in Cloud Development	Tier-1 ABAP Cloud (Language Version 5) & Tier-3 BTP side-by-side apps.	CDS View Entities (`I_*`), RAP BO Interfaces, Classes, Interfaces.
Contract C2	Use in System-Internal Cloud	Internal SAP cloud framework extensions within the same stack.	System utility interfaces, runtime frameworks.
Contract C3	Use in Key-User Extensibility	Fiori Custom Fields & Logic Apps (Restricted ABAP Language Version 2).	Cloud BAdI definitions, Business Context field views.
Contract C4	Use in User Interface Consumption	SAP Fiori elements, SAP Build Work Zone, and SAP Analytics Cloud.	Service Definitions, OData V4 Service Bindings.

2. The Business Object Interface (BOI) Architecture

In production enterprise systems, releasing a Root Entity (ZR_SalesOrder) directly to other development teams or external systems violates encapsulation.

Why You Must Use a BOI (ZI_*):

Field Encapsulation: The root entity ZR_* may have 120 database columns, internal calculation buffers, and technical flags. The BOI ZI_* exposes only the 25 business-relevant fields.
Behavior Control: Internal determinations (e.g. recalculate pricing margin) should not be triggered directly by external consumers. The BOI exposes clean business actions (e.g., use action ReleaseOrder;) without exposing internal mechanics.
Upgrade Independence: You can refactor the underlying ZR_* root table, split tables, or optimize queries without breaking external consumers, as long as the ZI_* interface contract remains stable.

3. Stability States Lifecycle

Stability State	Contractual Guarantee	Allowed Modifications
STABLE	Incompatible changes are strictly forbidden. Deletion is blocked by ATC.	Additive changes only (adding new optional fields or new actions).
DEPRECATED	Object will be decommissioned in a future release. ATC raises warnings.	Must provide successor object in API documentation. Minimum 12-month grace period.
NOT_RELEASED	Internal private implementation. Subject to change or removal without notice.	Any modification permitted; outside consumers are blocked at compile time in ABAP Cloud.

4. How to Release a Custom Object in Eclipse ADT

Open the target object (CDS View Entity, Class, or Interface) in Eclipse ADT.
Navigate to the Properties tab > API State.
Click Add Contract and select Use in Cloud Development (Contract C1).
Set Stability State to STABLE.
Save and activate. Eclipse ADT automatically generates the release state metadata XML (.ddls.xml or .clas.xml).

Recommended Clean Core Developer Tools

Explore free client-side interactive utilities to accelerate your S/4HANA migration:

📜 BOI & C1 Contract Generator 🔍 Released API Catalog 🛡️ Tier-2 Quarantine Generator 🧭 Decision Wizard & ADR