SAP · rpanackal · May 4, 2026 · May 11, 2026 · May 11, 2026 · May 11, 2026
diff --git a/.github/workflows/spec-update.yaml b/.github/workflows/spec-update.yaml
@@ -59,6 +59,7 @@ jobs:
       pr_url: ${{ steps.create-pr.outputs.pr_url }}
       compilation_result: ${{ steps.compile.outputs.compilation_result }}
       test_result: ${{ steps.compile.outputs.test_result }}
+      api_compat_result: ${{ steps.api_compat.outputs.api_compat_result }}
     env:
       API_BASE_URL: 'https://github.tools.sap/api/v3/repos'
       SERVICE: ${{ github.event.inputs.service }}
@@ -142,25 +143,31 @@ jobs:
             core)
               API_URL="$API_BASE_URL/cloudsdk/cloud-sdk-java-tests/contents/aicore.yaml?ref=$REF"
               FILE_PATH='core/src/main/resources/spec/aicore.yaml'
+              MODULE_PATH='core'
               ;;
             document-grounding)
               API_URL="$API_BASE_URL/AI/rage-proxy-inference/contents/docs/public/business_api_hub/api_hub_merged_spec.yaml?ref=$REF"
               FILE_PATH='core-services/document-grounding/src/main/resources/spec/grounding.yaml'
+              MODULE_PATH='core-services/document-grounding'
               ;;
             orchestration)
               API_URL="$API_BASE_URL/AI/llm-orchestration/contents/src/spec/v2.yaml?ref=$REF"
               FILE_PATH='orchestration/src/main/resources/spec/orchestration.yaml'
+              MODULE_PATH='orchestration'
               ;;
             prompt-registry)
               API_URL="$API_BASE_URL/AI/prompt-registry/contents/src/spec/generated/prompt-registry-combined.yaml?ref=$REF"
               FILE_PATH='core-services/prompt-registry/src/main/resources/spec/prompt-registry.yaml'
+              MODULE_PATH='core-services/prompt-registry'
               ;;
             sap-rpt) # https://github.tools.sap/DL-COE/sap-rpt-1-public-content
               API_URL="$API_BASE_URL/DL-COE/sap-rpt-1-public-content/contents/sap-rpt-1_openapi.json?ref=$REF"
               FILE_PATH='foundation-models/sap-rpt/src/main/resources/spec/sap-rpt-1_openapi.json'
+              MODULE_PATH='foundation-models/sap-rpt'
               ;;
           esac
 
+          echo "module_path=$MODULE_PATH" >> "$GITHUB_OUTPUT"
           echo "Downloading $SERVICE specification file from $API_URL ..."
 
           gh api "$API_URL" -H "Accept: application/vnd.github.raw" > $FILE_PATH
@@ -215,6 +222,40 @@ jobs:
             fi
           fi
 
+      - name: 'Build baseline JAR'
+        id: baseline
+        if: steps.spec_diff.outputs.spec_diff == 'true'
+        env:
+          MODULE_PATH: ${{ steps.download.outputs.module_path }}
+        run: |
+          set -euo pipefail
+
+          # Extract main branch source into a temporary directory
+          git fetch --no-tags --depth=1 origin main
+          rm -rf /tmp/main-baseline
+          mkdir -p /tmp/main-baseline
+          git archive origin/main | tar -x -C /tmp/main-baseline
+
+          # Build inside a subshell to avoid polluting the working directory
+          (
+            cd /tmp/main-baseline
+
+            mvn package -DskipTests -pl "$MODULE_PATH" -am ${{ env.MVN_MULTI_THREADED_ARGS }}
+
+            BASELINE_FINAL_NAME=$(mvn -q -pl "$MODULE_PATH" help:evaluate -Dexpression=project.build.finalName -DforceStdout)
+            BASELINE_JAR="$MODULE_PATH/target/${BASELINE_FINAL_NAME}.jar"
+
+            if [ ! -f "$BASELINE_JAR" ]; then
+              echo "::error::Baseline JAR not found: $BASELINE_JAR"
+              ls -la "$MODULE_PATH/target/" || true
+              exit 1
+            fi
+
+            cp "$BASELINE_JAR" /tmp/baseline.jar
+          )
+
+          echo "Baseline JAR ready: $(ls -lh /tmp/baseline.jar)"
+
       - name: 'Generate'
         id: generate
         if: steps.spec_diff.outputs.spec_diff == 'true'
@@ -225,6 +266,70 @@ jobs:
             echo "generation_result=failure" >> "$GITHUB_OUTPUT"
           fi
 
+      - name: 'API compatibility check'
+        id: api_compat
+        if: >
+          steps.spec_diff.outputs.spec_diff == 'true' &&
+          steps.generate.outputs.generation_result == 'success'
+        env:
+          MODULE_PATH: ${{ steps.download.outputs.module_path }}
+        run: |
+          # Diagnostic: confirm branch, commit and POM state on runner
+          echo "=== Git state ==="
+          git branch --show-current
+          git log -1 --oneline
+
+          echo "=== Effective POM japicmp section ==="
+          mvn help:effective-pom -pl "$MODULE_PATH" -Doutput=/tmp/effective-pom.xml ${{ env.MVN_MULTI_THREADED_ARGS }}
+          grep -n "japicmp-maven-plugin" /tmp/effective-pom.xml || true
+          grep -n "api-compatibility" /tmp/effective-pom.xml || true
+          grep -n "baseline.jar" /tmp/effective-pom.xml || true
+
+          echo "=== Parent POM japicmp section ==="
+          grep -n -A 40 "japicmp-maven-plugin" pom.xml | head -60 || true
+
+          echo "=== Module POM japicmp section ==="
+          grep -n -A 20 "japicmp-maven-plugin" "$MODULE_PATH/pom.xml" | head -30 || true
+
+          # Resolve the current (newly generated) JAR path
+          CURRENT_FINAL_NAME=$(mvn -q -pl "$MODULE_PATH" help:evaluate -Dexpression=project.build.finalName -DforceStdout)
+          CURRENT_JAR="$MODULE_PATH/target/${CURRENT_FINAL_NAME}.jar"
+
+          # Verify both JARs exist before running comparison
+          if [ ! -f "/tmp/baseline.jar" ]; then
+            echo "::error::Baseline JAR not found: /tmp/baseline.jar"
+            ls -la /tmp/ || true
+            exit 1
+          fi
+          if [ ! -f "$CURRENT_JAR" ]; then
+            echo "::error::Current JAR not found: $CURRENT_JAR"
+            ls -la "$MODULE_PATH/target/" || true
+            exit 1
+          fi
+          echo "Comparing: /tmp/baseline.jar vs $CURRENT_JAR"
+
+          # Run japicmp: compare baseline (main) JAR vs newly generated JAR
+          if mvn com.github.siom79.japicmp:japicmp-maven-plugin:cmp@api-compatibility \
+            -pl "$MODULE_PATH" \
+            -Djapicmp.oldVersion.file=/tmp/baseline.jar \
+            -Djapicmp.newVersion.file="$CURRENT_JAR" \
+            ${{ env.MVN_MULTI_THREADED_ARGS }} ; then
+            echo "api_compat_result=compatible" >> "$GITHUB_OUTPUT"
+          else
+            echo "api_compat_result=incompatible" >> "$GITHUB_OUTPUT"
+            echo "## ❌ API Compatibility: Breaking changes detected" >> $GITHUB_STEP_SUMMARY
+            echo "Download the **japicmp-report** artifact for details." >> $GITHUB_STEP_SUMMARY
+            exit 1
+          fi
+
+      - name: 'Upload japicmp report'
+        if: always() && steps.api_compat.outcome != 'skipped'
+        uses: actions/upload-artifact@v4
+        with:
+          name: japicmp-report
+          path: ${{ steps.download.outputs.module_path }}/target/japicmp/
+          if-no-files-found: ignore
+
       - name: 'Compile and Test'
         id: compile
         if: steps.spec_diff.outputs.spec_diff == 'true'
@@ -277,6 +382,7 @@ jobs:
 
           - Compilation outcome: ${{ steps.compile.outputs.compilation_result }}
           - Test run outcome: ${{ steps.compile.outputs.test_result }}
+          - API compatibility: ${{ steps.api_compat.outputs.api_compat_result || 'skipped' }}
 
           Before merging, make sure to update tests and release notes, if necessary.
 
@@ -313,6 +419,7 @@ jobs:
             echo "| Client Generation | ${{ steps.generate.outputs.generation_result == 'success' && '✅' || '❌' }} ${{ steps.generate.outputs.generation_result }}" >> $GITHUB_STEP_SUMMARY
             echo "| Client Compilation | ${{ steps.compile.outputs.compilation_result == 'success' && '✅' || '❌' }} ${{ steps.compile.outputs.compilation_result }}" >> $GITHUB_STEP_SUMMARY
             echo "| Client Testing | ${{ steps.compile.outputs.test_result == 'success' && '✅' || steps.compile.outputs.test_result == 'skipped' && '⏩' || '❌' }} ${{ steps.compile.outputs.test_result }}" >> $GITHUB_STEP_SUMMARY
+            echo "| API Compatibility | ${{ steps.api_compat.outputs.api_compat_result == 'compatible' && '✅' || steps.api_compat.outputs.api_compat_result == 'incompatible' && '❌' || '⏩' }} ${{ steps.api_compat.outputs.api_compat_result || 'skipped' }}" >> $GITHUB_STEP_SUMMARY
             echo "| Branch Creation | ${{ steps.push.outcome == 'success' && '✅ [Branch Link]($DIFF_URL)' || '❌ failure' }}" >> $GITHUB_STEP_SUMMARY
             echo "| Pull Request Creation | ${{ env.CREATE_PR == 'false' && '⏩ skipped' || '' }}${{ env.CREATE_PR == 'true' && steps.push.outcome == 'success' && '✅ [PR Link]($PR_URL)' || '' }}" >> $GITHUB_STEP_SUMMARY
           fi

diff --git a/core-services/document-grounding/pom.xml b/core-services/document-grounding/pom.xml
@@ -99,6 +99,28 @@
     </dependency>
   </dependencies>
 
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>com.github.siom79.japicmp</groupId>
+        <artifactId>japicmp-maven-plugin</artifactId>
+        <executions>
+          <execution>
+            <id>api-compatibility</id>
+            <configuration>
+              <parameter>
+                <includes combine.children="append">
+                  <include>com.sap.ai.sdk.grounding.client</include>
+                  <include>com.sap.ai.sdk.grounding.model</include>
+                </includes>
+              </parameter>
+            </configuration>
+          </execution>
+        </executions>
+      </plugin>
+    </plugins>
+  </build>
+
   <profiles>
     <profile>
       <id>generate</id>

diff --git a/core-services/prompt-registry/pom.xml b/core-services/prompt-registry/pom.xml
@@ -109,6 +109,28 @@
     </dependency>
   </dependencies>
 
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>com.github.siom79.japicmp</groupId>
+        <artifactId>japicmp-maven-plugin</artifactId>
+        <executions>
+          <execution>
+            <id>api-compatibility</id>
+            <configuration>
+              <parameter>
+                <includes combine.children="append">
+                  <include>com.sap.ai.sdk.prompt.registry.client</include>
+                  <include>com.sap.ai.sdk.prompt.registry.model</include>
+                </includes>
+              </parameter>
+            </configuration>
+          </execution>
+        </executions>
+      </plugin>
+    </plugins>
+  </build>
+
   <profiles>
     <profile>
       <id>generate</id>

diff --git a/core/pom.xml b/core/pom.xml
@@ -140,6 +140,28 @@
     </dependency>
   </dependencies>
 
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>com.github.siom79.japicmp</groupId>
+        <artifactId>japicmp-maven-plugin</artifactId>
+        <executions>
+          <execution>
+            <id>api-compatibility</id>
+            <configuration>
+              <parameter>
+                <includes combine.children="append">
+                  <include>com.sap.ai.sdk.core.client</include>
+                  <include>com.sap.ai.sdk.core.model</include>
+                </includes>
+              </parameter>
+            </configuration>
+          </execution>
+        </executions>
+      </plugin>
+    </plugins>
+  </build>
+
   <profiles>
     <profile>
       <id>generate</id>

diff --git a/foundation-models/sap-rpt/pom.xml b/foundation-models/sap-rpt/pom.xml
@@ -181,6 +181,22 @@
           </ignoredUnusedDeclaredDependencies>
         </configuration>
       </plugin>
+      <plugin>
+        <groupId>com.github.siom79.japicmp</groupId>
+        <artifactId>japicmp-maven-plugin</artifactId>
+        <executions>
+          <execution>
+            <id>api-compatibility</id>
+            <configuration>
+              <parameter>
+                <includes combine.children="append">
+                  <include>com.sap.ai.sdk.foundationmodels.rpt.generated</include>
+                </includes>
+              </parameter>
+            </configuration>
+          </execution>
+        </executions>
+      </plugin>
     </plugins>
   </build>
   <profiles>

diff --git a/orchestration/pom.xml b/orchestration/pom.xml
@@ -168,6 +168,27 @@
     </dependency>
   </dependencies>
 
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>com.github.siom79.japicmp</groupId>
+        <artifactId>japicmp-maven-plugin</artifactId>
+        <executions>
+          <execution>
+            <id>api-compatibility</id>
+            <configuration>
+              <parameter>
+                <includes combine.children="append">
+                  <include>com.sap.ai.sdk.orchestration.model</include>
+                </includes>
+              </parameter>
+            </configuration>
+          </execution>
+        </executions>
+      </plugin>
+    </plugins>
+  </build>
+
   <profiles>
     <profile>
       <id>generate</id>

diff --git a/pom.xml b/pom.xml
@@ -73,6 +73,7 @@
     <jackson.version>2.21.3</jackson.version>
     <logback.version>1.5.32</logback.version>
     <commons-codec.version>1.22.0</commons-codec.version>
+    <japicmp.version>0.25.7</japicmp.version>
     <!-- conflicts resolution -->
     <micrometer.version>1.16.5</micrometer.version>
     <json.version>20251224</json.version>
@@ -94,6 +95,9 @@
     <coverage.branch>100%</coverage.branch>
     <coverage.method>100%</coverage.method>
     <coverage.class>100%</coverage.class>
+    <!--  Binary compatibility check old/new version file -->
+    <japicmp.oldVersion.file>/tmp/baseline.jar</japicmp.oldVersion.file>
+    <japicmp.newVersion.file>${project.build.directory}/${project.build.finalName}.jar</japicmp.newVersion.file>
   </properties>
 
   <dependencyManagement>
@@ -300,6 +304,40 @@
           <artifactId>openapi-generator-maven-plugin</artifactId>
           <version>7.22.0</version>
         </plugin>
+        <plugin>
+          <groupId>com.github.siom79.japicmp</groupId>
+          <artifactId>japicmp-maven-plugin</artifactId>
+          <version>${japicmp.version}</version>
+          <executions>
+            <execution>
+              <id>api-compatibility</id>
+              <goals>
+                <goal>cmp</goal>
+              </goals>
+              <phase>none</phase>
+              <configuration>
+                <oldVersion>
+                  <file>
+                    <path>${japicmp.oldVersion.file}</path>
+                  </file>
+                </oldVersion>
+                <newVersion>
+                  <file>
+                    <path>${japicmp.newVersion.file}</path>
+                  </file>
+                </newVersion>
+                <parameter>
+                  <breakBuildOnBinaryIncompatibleModifications>true</breakBuildOnBinaryIncompatibleModifications>
+                  <breakBuildOnSourceIncompatibleModifications>true</breakBuildOnSourceIncompatibleModifications>
+                  <onlyModified>true</onlyModified>
+                  <accessModifier>public</accessModifier>
+                  <onlyBinaryIncompatible>false</onlyBinaryIncompatible>
+                  <ignoreMissingOldVersion>false</ignoreMissingOldVersion>
+                </parameter>
+              </configuration>
+            </execution>
+          </executions>
+        </plugin>
       </plugins>
     </pluginManagement>
     <plugins>