Split OpenFeature Java SDK into API and Implementation Artifacts

[aepfli]

Problem Statement

Currently, the OpenFeature Java SDK provides a single artifact that includes both the API interfaces and the implementation. This creates challenges as we expand the ecosystem:

1. Gherkin Test Steps Dependencies: The upcoming Gherkin test steps implementation needs to reference the OpenFeature API but shouldn't depend on a specific implementation
2. java-sdk-contrib Integration: Contributors working on java-sdk-contrib need access to the API without pulling in unnecessary implementation dependencies
3. Release Coupling: API changes (which should be infrequent and stable) are coupled with implementation changes (which may be more frequent)
4. Dependency Bloat: Consumers who only need the API surface (like test frameworks or alternative implementations) currently must pull in the full SDK

Proposed Solution

Split the current single artifact into two separate artifacts:

1. openfeature-api (New)

• Contains only interfaces, annotations, and core data types
• Defines the stable API contract
• Minimal dependencies
• Follows strict semantic versioning
• Infrequent releases (only when API changes)

2. openfeature-sdk (Refactored)

• Contains the current implementation
• Depends on openfeature-api
• More frequent releases for implementation improvements
• Backward compatible implementation changes don't require API updates

3. openfeature-test-harness (Future)

• Contains Gherkin test steps
• Depends only on openfeature-api
• Can be used by any OpenFeature implementation
• Implementation-agnostic testing utilities

Benefits

1. Cleaner Dependencies: Test frameworks and alternative implementations only pull what they need
2. Independent Release Cycles: API stability doesn't block implementation improvements
3. Better SemVer Compliance: Clear separation of API breaking changes vs implementation changes
4. Ecosystem Growth: Easier for java-sdk-contrib and other implementations to integrate
5. Provider Implementation Flexibility: Feature flag providers (LaunchDarkly, Flagsmith, Split, etc.) can bind to the stable API instead of the full SDK, enabling:
   • Multiple provider versions compatible with the same API version
   • Users can mix and match provider versions independently from SDK versions
   • Providers don't need to release new versions for every SDK implementation change
   • Reduced version conflicts in user applications with multiple providers
6. Reduced Coupling: Following established patterns from SLF4J, JAX-RS, etc.

Provider Implementation Benefits

This split is particularly valuable for the OpenFeature provider ecosystem:

Current State:

<!-- Provider must depend on full SDK -->
<dependency>
    <groupId>dev.openfeature</groupId>
    <artifactId>sdk</artifactId>
    <version>1.5.0</version>
</dependency>

After API Split:

<!-- Provider only needs API contract -->
<dependency>
    <groupId>dev.openfeature</groupId>
    <artifactId>openfeature-api</artifactId>
    <version>1.2.0</version>
</dependency>

Real-world scenario:

• LaunchDarkly provider v2.1.0 targets API v1.2.0
• Flagsmith provider v1.8.0 also targets API v1.2.0
• User can use both providers with SDK v2.5.0 (which implements API v1.2.0)
• No version conflicts, no forced provider upgrades when SDK implementation improves

This mirrors successful patterns like:

• JDBC drivers targeting JDBC API versions
• SLF4J logging implementations targeting SLF4J API
• JAX-RS providers targeting JAX-RS API

Phase 1: Repository Structure Decision

Decision needed: Separate repositories vs monorepo with manifest

Option A: Separate Repositories (Recommended)

openfeature-java-api/          (API only)
openfeature-java-sdk/          (Implementation)
openfeature-java-test-harness/ (Future - Gherkin steps)

Pros with release-please:

• Clean release lifecycle per artifact
• Independent conventional commit history
• Focused issues/PRs per component
• Simpler CI/CD pipelines

Option B: Monorepo with Release-Please Manifest

/api/              (API artifact)
/sdk/              (SDK artifact)  
/test-harness/     (Future - Test artifact)
/pom.xml           (Parent aggregator)

Phase 2: API Extraction

1. Create openfeature-api module/repo

   • Move all interfaces (FeatureProvider, Client, EvaluationContext, etc.)
   • Move core data types (FlagEvaluationDetails, ProviderMetadata, etc.)
   • Move annotations and exceptions
   • Create minimal pom.xml with only essential dependencies

2. Update openfeature-sdk module/repo

   • Add dependency on openfeature-api
   • Remove duplicated interfaces/types
   • Keep all implementation classes
   • Update imports to reference API artifact

3. Version Strategy

   • Start API at 1.0.0 (stable baseline)
   • SDK continues current versioning or resets to align with API major version
   • Use version ranges: <version>[1.0.0,2.0.0)</version>

Phase 3: Release-Please Configuration

For Separate Repositories:

Each repo gets standard release-please setup:

# .github/workflows/release-please.yml
- uses: google-github-actions/release-please-action@v3
  with:
    release-type: maven
    package-name: openfeature-api  # or openfeature-sdk
    token: ${{ secrets.GITHUB_TOKEN }}

For Monorepo:

// .release-please-manifest.json
{
  "api": "1.0.0",
  "sdk": "2.0.0"
}

Phase 4: Documentation & Communication

1. Update README.md with new artifact structure

2. Create migration guide for existing users

3. Document version compatibility matrix:

   SDK Version	Compatible API Versions	Notes
   2.x.x	1.x.x	Current

4. Update build badges and Maven Central links

Phase 5: Testing & Validation

1. Compatibility testing between API and SDK versions
2. Integration testing with existing OpenFeature providers
3. Validate Gherkin steps work with API-only dependency
4. Test java-sdk-contrib integration

Migration Path for Users

Current Usage:

<dependency>
    <groupId>dev.openfeature</groupId>
    <artifactId>sdk</artifactId>
    <version>1.x.x</version>
</dependency>

After Split:

<!-- Most users still just need the full SDK -->
<dependency>
    <groupId>dev.openfeature</groupId>
    <artifactId>openfeature-sdk</artifactId>
    <version>2.x.x</version>
</dependency>

<!-- API-only consumers (test frameworks, alternative implementations) -->
<dependency>
    <groupId>dev.openfeature</groupId>
    <artifactId>openfeature-api</artifactId>
    <version>1.x.x</version>
</dependency>

Risks & Mitigations

1. Increased Complexity: Multiple artifacts to maintain

   • Mitigation: Clear documentation and automated testing

2. Version Alignment Challenges: API/SDK compatibility matrix

   • Mitigation: Automated compatibility testing in CI

3. User Confusion: Which artifact to use?

   • Mitigation: Clear documentation with usage examples

4. Release Coordination: Breaking changes spanning API + SDK

   • Mitigation: Careful planning of breaking changes, deprecation periods

Success Criteria

1. ✅ Gherkin test steps can depend only on openfeature-api
2. ✅ java-sdk-contrib implementations work with API-only dependency
3. ✅ Existing users can migrate with minimal changes
4. ✅ Independent release cycles for API vs implementation
5. ✅ Clear version compatibility documentation

Next Steps

1. Decision: Choose repository structure (separate repos vs monorepo)
2. Create implementation plan with detailed timeline
3. Set up new repositories/modules
4. Begin API extraction following the implementation plan
5. Update CI/CD pipelines for new artifact structure

[aepfli]

used ai to generate an ai prompt based on this issue :) would love to try to vibe code this :) openfeature_refactor_prompt.md

[beeme1mr]

OpenTelemetry has a similar structure, too. It's probably worth at least considering differentiating between the SDK and API.

[aepfli]

#1582 is a little demo made with claude.code even with a list of breaking cchanges here: mostly pojo initialization and setter changes -> https://github.com/open-feature/java-sdk/blob/27ffe54e0e2a4edc1469a168ef5b7e0919a4395e/BREAKING_CHANGES.md