feat(java): publish ODP BOM

.github/workflows/ci.yml

@@ -34,12 +34,22 @@ jobs:
           java-version: ${{ matrix.java }}
           cache: maven
 
+      - name: Set up Gradle
+        if: matrix.java == '17'
+        uses: gradle/actions/setup-gradle@v6
+        with:
+          gradle-version: "9.5.1"
+
       - run: ./mvnw --batch-mode --no-transfer-progress verify
 
-      - name: Verify clean consumer
+      - name: Verify clean Maven consumers
         if: matrix.java == '17'
         run: ./scripts/verify-consumer.sh
 
+      - name: Verify clean Gradle consumer
+        if: matrix.java == '17'
+        run: ./scripts/verify-gradle-consumer.sh
+
       - name: Run shared conformance harness
         run: ./scripts/run-conformance.sh
         env:

.github/workflows/release.yml

@@ -77,6 +77,11 @@ jobs:
           server-username-env-var: CENTRAL_USERNAME
           server-password-env-var: CENTRAL_PASSWORD
 
+      - name: Set up Gradle
+        uses: gradle/actions/setup-gradle@v6
+        with:
+          gradle-version: "9.5.1"
+
       - name: Set up pnpm
         uses: pnpm/action-setup@v6
         with:
@@ -103,9 +108,15 @@ jobs:
         env:
           ODP_NODE_DIR: .conformance/odp-node
 
-      - name: Verify clean consumer
+      - name: Verify clean Maven consumers
         run: ./scripts/verify-consumer.sh
 
+      - name: Verify clean Gradle consumer
+        run: ./scripts/verify-gradle-consumer.sh
+
+      - name: Inspect release artifacts
+        run: ./scripts/verify-release-artifacts.sh
+
       - name: Publish Maven artifacts
         if: steps.release.outputs.published != 'true'
         run: ./mvnw --batch-mode --no-transfer-progress -Prelease -Dgpg.signer=bc deploy
@@ -120,15 +131,18 @@ jobs:
         with:
           subject-path: |
             odp-core/target/odp-core-${{ steps.release.outputs.version }}*.jar
+            odp-json-jackson2/target/odp-json-jackson2-${{ steps.release.outputs.version }}*.jar
+            odp-json-jackson3/target/odp-json-jackson3-${{ steps.release.outputs.version }}*.jar
             odp-directory/target/odp-directory-${{ steps.release.outputs.version }}*.jar
             odp-agent/target/odp-agent-${{ steps.release.outputs.version }}*.jar
             odp-service/target/odp-service-${{ steps.release.outputs.version }}*.jar
+            odp-bom/pom.xml
 
       - name: Wait for Maven Central availability
         env:
           VERSION: ${{ steps.release.outputs.version }}
         run: |
-          artifact="https://repo1.maven.org/maven2/org/offeringprotocol/odp-core/$VERSION/odp-core-$VERSION.pom"
+          artifact="https://repo1.maven.org/maven2/org/offeringprotocol/odp-bom/$VERSION/odp-bom-$VERSION.pom"
           for attempt in {1..60}; do
             if curl --fail --silent --show-error --head "$artifact" >/dev/null; then
               exit 0
@@ -138,11 +152,16 @@ jobs:
           echo "Maven Central did not expose $artifact within 10 minutes." >&2
           exit 1
 
-      - name: Verify Maven Central consumer
+      - name: Verify Maven Central consumers
         run: ./scripts/verify-consumer.sh
         env:
           ODP_CONSUMER_SOURCE: central
 
+      - name: Verify Maven Central Gradle consumer
+        run: ./scripts/verify-gradle-consumer.sh
+        env:
+          ODP_CONSUMER_SOURCE: central
+
       - name: Create release tag
         env:
           TAG: ${{ steps.release.outputs.tag }}
@@ -161,6 +180,7 @@ jobs:
           .conformance/reports/agent.json#odp-java-agent-conformance.json
           .conformance/reports/service.json#odp-java-service-conformance.json
           --generate-notes
+          --notes "Published artifacts include org.offeringprotocol:odp-bom for Maven and Gradle dependency alignment."
           --title "ODP Java ${{ steps.release.outputs.tag }}"
           --verify-tag
         env:

.gitignore

@@ -1,10 +1,12 @@
 .DS_Store
 .conformance/
+.gradle/
 .idea/
 .project
 .classpath
 .settings/
 .vscode/
 target/
 **/target/
+**/build/
 *.iml

README.md

@@ -25,6 +25,7 @@ Choose the module that matches the role your application implements:
 | An ODP Service                              | [`odp-service`](./odp-service/README.md)     | Service document, fixed routes, static or storage-backed operations |
 | A directory-only integration                | [`odp-directory`](./odp-directory/README.md) | Canonical production or sandbox Service search                      |
 | An ODP validator or protocol implementation | [`odp-core`](./odp-core/README.md)           | Models, bundled schemas, identity, references, and pagination       |
+| Compatible ODP dependency versions          | [`odp-bom`](./odp-bom/README.md)             | Version alignment without a parent-POM relationship                 |
 
 Every application also selects one JSON provider: `odp-json-jackson2` for applications using
 Jackson 2, or `odp-json-jackson3` for applications using Jackson 3. The role modules do not force a
@@ -39,18 +40,32 @@ directory behavior.
 
 ## Installation
 
+Import `odp-bom` once to keep every explicitly selected ODP module on a compatible release:
+
+```xml
+<dependencyManagement>
+  <dependencies>
+    <dependency>
+      <groupId>org.offeringprotocol</groupId>
+      <artifactId>odp-bom</artifactId>
+      <version>0.2.1</version>
+      <type>pom</type>
+      <scope>import</scope>
+    </dependency>
+  </dependencies>
+</dependencyManagement>
+```
+
 For an Agent application:
 
 ```xml
 <dependency>
   <groupId>org.offeringprotocol</groupId>
   <artifactId>odp-agent</artifactId>
-  <version>0.2.0</version>
 </dependency>
 <dependency>
   <groupId>org.offeringprotocol</groupId>
   <artifactId>odp-json-jackson2</artifactId>
-  <version>0.2.0</version>
 </dependency>
 ```
 
@@ -60,22 +75,28 @@ For a Service integration:
 <dependency>
   <groupId>org.offeringprotocol</groupId>
   <artifactId>odp-service</artifactId>
-  <version>0.2.0</version>
 </dependency>
 <dependency>
   <groupId>org.offeringprotocol</groupId>
   <artifactId>odp-json-jackson2</artifactId>
-  <version>0.2.0</version>
 </dependency>
 ```
 
 Gradle uses the same coordinates:
 
 ```kotlin
-implementation("org.offeringprotocol:odp-agent:0.2.0")
-implementation("org.offeringprotocol:odp-json-jackson2:0.2.0")
+implementation(platform("org.offeringprotocol:odp-bom:0.2.1"))
+implementation("org.offeringprotocol:odp-agent")
+implementation("org.offeringprotocol:odp-json-jackson2")
 ```
 
+The BOM manages ODP module versions only. It does not add modules, select a Jackson generation, or
+manage Jackson itself. Applications select the role modules they use and exactly one JSON provider.
+
+Consumers that prefer direct versions can omit the BOM and specify the same ODP release on each
+dependency, for example `org.offeringprotocol:odp-agent:0.2.1` and
+`org.offeringprotocol:odp-json-jackson2:0.2.1`.
+
 Replace `odp-json-jackson2` with `odp-json-jackson3` when the application uses Jackson 3. Exactly
 one provider must be present at runtime; `OdpJson` discovers it through Java `ServiceLoader`.
 Maven resolves the required Core and Directory modules transitively. Applications should not add
@@ -195,6 +216,7 @@ Verify the published module boundaries from an isolated consumer project with:
 
 ```sh
 ./scripts/verify-consumer.sh
+./scripts/verify-gradle-consumer.sh
 ```
 
 Format Java sources with:

examples/pom.xml

@@ -7,7 +7,7 @@
   <parent>
     <groupId>org.offeringprotocol</groupId>
     <artifactId>odp-java</artifactId>
-    <version>0.2.0</version>
+    <version>0.2.1</version>
   </parent>
 
   <artifactId>odp-examples</artifactId>

odp-agent/README.md

@@ -9,23 +9,8 @@ capability checks, Collections, Offerings, localization, and continuations.
 
 ## Install
 
-```xml
-<dependency>
-  <groupId>org.offeringprotocol</groupId>
-  <artifactId>odp-agent</artifactId>
-  <version>0.2.0</version>
-</dependency>
-<dependency>
-  <groupId>org.offeringprotocol</groupId>
-  <artifactId>odp-json-jackson2</artifactId>
-  <version>0.2.0</version>
-</dependency>
-```
-
-```kotlin
-implementation("org.offeringprotocol:odp-agent:0.2.0")
-implementation("org.offeringprotocol:odp-json-jackson2:0.2.0")
-```
+Follow the canonical [installation guide](../README.md#installation), selecting `odp-agent` and
+exactly one JSON provider.
 
 The Agent module brings in `odp-directory` and `odp-core` transitively. Replace
 `odp-json-jackson2` with `odp-json-jackson3` in a Jackson 3 application. Exactly one provider must

odp-agent/pom.xml

@@ -7,7 +7,7 @@
   <parent>
     <groupId>org.offeringprotocol</groupId>
     <artifactId>odp-java</artifactId>
-    <version>0.2.0</version>
+    <version>0.2.1</version>
   </parent>
 
   <artifactId>odp-agent</artifactId>

odp-bom/README.md

@@ -0,0 +1,12 @@
+# ODP Bill of Materials
+
+`odp-bom` manages compatible versions for the public ODP Java modules. It contains no runtime code
+and does not add any dependency to an application. Importing it ensures that explicitly selected
+ODP modules use one release version.
+
+Every application that uses ODP JSON must explicitly depend on exactly one of
+`odp-json-jackson2` or `odp-json-jackson3`. The BOM supplies that module's version after the
+application selects it; the BOM does not select a Jackson generation or add Jackson itself.
+
+See the root [installation guide](../README.md#installation) for Maven and Gradle usage and the
+supported direct-version alternative.

odp-bom/pom.xml

@@ -0,0 +1,52 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+
+  <parent>
+    <groupId>org.offeringprotocol</groupId>
+    <artifactId>odp-java</artifactId>
+    <version>0.2.1</version>
+  </parent>
+
+  <artifactId>odp-bom</artifactId>
+  <packaging>pom</packaging>
+  <name>ODP Bill of Materials</name>
+  <description>Compatible versions for the official ODP Java modules.</description>
+
+  <dependencyManagement>
+    <dependencies>
+      <dependency>
+        <groupId>${project.groupId}</groupId>
+        <artifactId>odp-core</artifactId>
+        <version>${project.version}</version>
+      </dependency>
+      <dependency>
+        <groupId>${project.groupId}</groupId>
+        <artifactId>odp-json-jackson2</artifactId>
+        <version>${project.version}</version>
+      </dependency>
+      <dependency>
+        <groupId>${project.groupId}</groupId>
+        <artifactId>odp-json-jackson3</artifactId>
+        <version>${project.version}</version>
+      </dependency>
+      <dependency>
+        <groupId>${project.groupId}</groupId>
+        <artifactId>odp-directory</artifactId>
+        <version>${project.version}</version>
+      </dependency>
+      <dependency>
+        <groupId>${project.groupId}</groupId>
+        <artifactId>odp-agent</artifactId>
+        <version>${project.version}</version>
+      </dependency>
+      <dependency>
+        <groupId>${project.groupId}</groupId>
+        <artifactId>odp-service</artifactId>
+        <version>${project.version}</version>
+      </dependency>
+    </dependencies>
+  </dependencyManagement>
+</project>

odp-core/README.md

@@ -9,23 +9,8 @@ ODP models without Agent or Service HTTP behavior.
 
 ## Install
 
-```xml
-<dependency>
-  <groupId>org.offeringprotocol</groupId>
-  <artifactId>odp-core</artifactId>
-  <version>0.2.0</version>
-</dependency>
-<dependency>
-  <groupId>org.offeringprotocol</groupId>
-  <artifactId>odp-json-jackson2</artifactId>
-  <version>0.2.0</version>
-</dependency>
-```
-
-```kotlin
-implementation("org.offeringprotocol:odp-core:0.2.0")
-implementation("org.offeringprotocol:odp-json-jackson2:0.2.0")
-```
+Follow the canonical [installation guide](../README.md#installation), selecting `odp-core` and
+exactly one JSON provider.
 
 Use `odp-json-jackson2` with Jackson 2 applications or replace it with `odp-json-jackson3` for
 Jackson 3. Add exactly one provider. `OdpJson` discovers the provider through Java `ServiceLoader`

odp-core/pom.xml

@@ -7,7 +7,7 @@
   <parent>
     <groupId>org.offeringprotocol</groupId>
     <artifactId>odp-java</artifactId>
-    <version>0.2.0</version>
+    <version>0.2.1</version>
   </parent>
 
   <artifactId>odp-core</artifactId>
@@ -22,6 +22,7 @@
     <dependency>
       <groupId>com.fasterxml.jackson.core</groupId>
       <artifactId>jackson-annotations</artifactId>
+      <version>${jackson-annotations.version}</version>
     </dependency>
   </dependencies>
 </project>

odp-directory/README.md

@@ -9,23 +9,8 @@ Service's Collections and Offerings with [`odp-agent`](../odp-agent/README.md).
 
 ## Install
 
-```xml
-<dependency>
-  <groupId>org.offeringprotocol</groupId>
-  <artifactId>odp-directory</artifactId>
-  <version>0.2.0</version>
-</dependency>
-<dependency>
-  <groupId>org.offeringprotocol</groupId>
-  <artifactId>odp-json-jackson2</artifactId>
-  <version>0.2.0</version>
-</dependency>
-```
-
-```kotlin
-implementation("org.offeringprotocol:odp-directory:0.2.0")
-implementation("org.offeringprotocol:odp-json-jackson2:0.2.0")
-```
+Follow the canonical [installation guide](../README.md#installation), selecting `odp-directory`
+and exactly one JSON provider.
 
 Replace `odp-json-jackson2` with `odp-json-jackson3` in a Jackson 3 application. Add exactly one
 provider; it is discovered automatically at runtime.

odp-directory/pom.xml

@@ -7,7 +7,7 @@
   <parent>
     <groupId>org.offeringprotocol</groupId>
     <artifactId>odp-java</artifactId>
-    <version>0.2.0</version>
+    <version>0.2.1</version>
   </parent>
 
   <artifactId>odp-directory</artifactId>