Is Developing SDKs Currently Convenient?

[piotrooo]

Important

There is no clear-cut answer to this question. However, I’d like to share my perspective. I understand that the current approach to developing various SDKs is deeply embedded in the workflow, making it difficult to change.
Nevertheless, I see some downsides in the process that hinder a developer-friendly experience.

Of course, I invite discussion and constructive feedback.

Context

How do I currently develop the Java SDK?
I have the sdk-generator repository checked out. Additionally, I have the java-sdk repository checked out. To add or refactor anything, I develop directly in the java-sdk project. This allows me to take full advantage of IDE features (test running, refactoring tools, code completion, etc.).

Once I’m satisfied with my changes, I manually transfer them to sdk-generator. Not very convenient, huh?

Challenges

mustache files

The nature of mustache files makes them difficult to edit, format, or refactor in the context of the language in which the SDK is developed.
Additionally, a lack of familiarity with OpenAPI Generator may discourage developers from making changes.

Different States Between Specific SDKs and the Generator

A problematic scenario arises when someone modifies, for example, the java-sdk but does not transfer these changes to sdk-generator. Other developers working on SDKs then face discrepancies between the java-sdk and sdk-generator. In such cases, the first step is often to align the state of sdk-generator with the specific SDK. However, aligning someone else's changes could be challenging.

Different SDK Lifecycles

Various SDKs have different lifecycles and development paces, which suggests distinct release cycles. This is why they should be maintained in separate repositories, allowing for proper versioning. Otherwise, the development of new SDKs may be slowed down.

For instance, @evansims prepared an excellent PoC for php-sdk. If we had separate repositories, the new SDK could be released as unstable (alpha, beta) without impacting stable SDKs. This would allow for a broader adoption process for new users.

Solutions

Generate Model

One of the most useful features of sdk-generator is generating models from OpenAPI specifications and the OpenFgaApi class — although even that is highly customized.

Other classes, such as utils, configurations, tests, and API clients, are unrelated to the OpenAPI specification. Since they are mustache templates, maintaining them is inconvenient.

Common Files

Many shared files can be managed using GitHub’s built-in mechanisms, such as shared workflows or templates for issues and pull requests.

Project Management

Currently, issues in sdk-generator serve as a hub for feature requests and bug reports, and they are added to the SDKs and Tooling project.

If SDK repositories were separate, then issues in sdk-generator could still act as a hub for all SDKs. An alternative approach would be to use sdk-generator as a hub for larger initiatives (epics) that should be applied across all SDKs. Using sub-issues, we could link individual tasks for each SDK. Specific bugs for a given SDK would be reported in their respective repositories and linked to the SDKs and Tooling project.

---

If I missed anything, let me know. I'm very curious to hear the OpenFGA team's opinion on this process. As I mentioned, I'm open to further discussion and eager to address any gaps in the process.

[GMorris-professional]

Hi @piotrooo

I agree with everything you've said here. I follow exactly the same process as you are regarding working in the Python SDK then manually transferring my changes to the sdk-generator. I've felt the pain of this including noticing small improvements after copying across and having to repeat the cycle.

I'm posting to keep an eye on this thread. But I like your suggestion to have the sdk-generator repository be for epics/larger common changes and have the separate language sdks for better developer experience.

[dyeam0]

@rhamzeh Piotr's discussion is more open-ended than the typical issue. Should it be moved to the Discussions area, or ok to continue the conversation here? WDYT?

[piotrooo]

Gently ping on this, any thoughts? Or it is a completely insane idea? 🤔

[dyeam0]

Hi @piotrooo and @GMorris-professional, just a heads up. We haven't forgotten about this. The team has been having conversations about this topic. Trying to get some team consensus before posting, so we don't clutter this thread with all the differing opinions. 🙂

[dyeam0]

Hi @piotrooo, thank you for taking the time to write a post and start this discussion. We appreciate all feedback and engagement from the community on the current state of the OpenFGA SDKs and the developer experience. We have been discussing this topic internally, and we wanted to come back with a thoughtful and detailed response.

First, we want to acknowledge that the pain points you've raised are valid. We understand that the current approach, which relies heavily on a generator, has its limitations and that a more hand-crafted approach for each language would provide a better developer experience.

The original intent of the SDK generator was to provide broad language support with the ability to easily add support for future languages. Your feedback has highlighted the difficulty of achieving multiple goals: automated code generation, consistency across SDKs, and simplicity within a particular language’s SDK. This view is also shared by the members of the team. We want to have the discussion with the community and take feedback as input for our long-term strategy for the SDKs.

We are committed to the long-term health and usability of the SDKs. To consider a possible full-scale overhaul of the SDKs is a very large undertaking. Here is our plan moving forward:

1. Proposed Approach: To jump-start the conversation, we have a proposed approach (details to come in a follow-up post). Some of the ideas are borrowed from/built on the PHP SDK. We want to continue the discussion here on GitHub to ensure transparency for the whole community. The goal is to define a clearer, long-term strategy for SDK community contributions and maintenance. A key challenge is finding an approach with the correct balance between auto-generated and custom-built components. We would love input and feedback.
2. Build First Iteration: We are proposing to start with one of our SDKs (likely Java) and build a first iteration. Our goal is to work more closely with the community on a single SDK to learn how we can best collaborate on these efforts.
3. Re-evaluate Based on Outcome: Based on the iteration, decide on next steps to take and continue to iterate until we are comfortable with a long-term strategy for the future of the SDKs.
4. Expand Across All SDKs: Apply the common approach to all SDK languages.

Currently, the team is focused on delivering other critical product priorities. This means that while we can have the discussion, we cannot commit to building the first iteration right away, but would begin in the near future.

We want to be transparent about our current constraints while also reassuring everyone that your feedback is being taken seriously. We are very grateful for this community and its passion for OpenFGA.

[piotrooo]

Hey @dyeam0,

Thanks for taking this seriously and for sharing such a detailed perspective on OpenFGA, along with your transparent feedback 🙏

Long-Term Strategy

When I think about our long-term strategy and desired state, I envision something similar to what projects like OpenTelemetry, Sentry, or even Testcontainers have accomplished. If we look at those, they maintain separate SDKs per language:

OpenTelemetry:
Java • Python • JavaScript

Sentry:
Java • Python • JavaScript

The ideal state for our SDKs should follow a similar language-specific structure. For example, we should have a repository like openfga/java-sdk that contains all Java-related components and frameworks, including the core SDK and integrations. For instance, the spring-boot-starter should live as a separate module within this Java SDK repository. This approach makes it much easier to manage additions like support for new frameworks. It also helps with organizing ownership — making it clearer which SDKs are assigned to which teams — resulting in better maintainability, accountability, and long-term governance.

The current state only reinforces the need for this structure. If you look at the java-sdk and sdk-generator, they are not aligned. There are commits in sdk-generator that should be reflected in java-sdk, and vice versa (e.g. Dependabot updates). It's chaotic and difficult to track what's current.

sdk-generator

The sdk-generator is a fantastic concept and should definitely be retained, but it should be limited to handling the OpenAPI specification. That is its intended purpose: generating models and endpoint clients.

The relevant logic should remain isolated under:
https://github.com/openfga/sdk-generator/tree/main/config/clients/java/template/libraries/native

Ideally, the process should work as follows:

1. openfga/openfga (the server) releases a new version and publishes an updated OpenAPI specification.
2. The sdk-generator uses that spec to generate API clients (models + endpoint clients) for all supported languages.
3. These generated artifacts are published to Maven, npm, etc. If someone wants a minimal, low-level client, they can use this directly. It's highly flexible. The version of the generated artifact should match the version of OpenFGA that produced the OpenAPI spec, so users can clearly correlate API behavior with the corresponding server release.

Starting Point

Starting with a single SDK makes a lot of sense. But we also need a ubiquitous language that applies across all SDKs. Right now, there are some patterns (e.g. all exceptions end with Error), which feel a bit awkward—at least in Java. Still, if it’s a defined convention, then all languages should follow it consistently.

I suggest the following steps:

1. Define the general scope and responsibility of sdk-generator. This will establish implementation boundaries and clarify the expected structure of each SDK.
2. Build one SDK end-to-end, covering everything from development to artifact publication and issue management.
3. Retrospectively review and refactor that SDK to extract reusable standards and conventions for the rest.

---

If I missed anything, feel free to point it out. I’ll do my best to provide valuable feedback.

And if there's any way I — or others from the community — can help, please don’t hesitate to reach out.

[dyeam0]

Hello @piotrooo and all. I have created a new OpenFGA roadmap item to track long-term SDK strategy efforts: openfga/roadmap#86. @rhamzeh and team have made initial steps towards streamlining contributor workflow and evolve the SDK structure. A POC has been done in openfga/sdk-generator#638.

Please see roadmap item for details.

[piotrooo]

Great! Kudos to the team for that huge effort 🙌

One thing is a little unclear to me - what are the next steps?

I suppose we should have some kind of statement on your side, something like:
"In the sdk-generator we keep only automatically generated models from OpenAPI. These should be reflected in an artifact for a specific language e.g openfga:openfga-model:1.0.0.
This artifact should then be imported as a dependency in the corresponding SDK (e.g. java, python). The team and community can build SDK features on top of it"

Or maybe this information was already shared somewhere but I just missed it - if so, sorry 😢

[rhamzeh]

Hi @piotrooo,

Thank you for the incredibly thoughtful and detailed feedback! We sincerely appreciate the passion you have for the project and the time you took to write this up. I want to address the points you've raised and be transparent about our thinking, our constraints, and our vision for the future of the OpenFGA SDKs.

The Need for Consistency

First, I want to clarify our audience and responsibilities. Our goal is to serve not just contributors, but also end-users and the maintainers who ensure the project's longevity. These SDKs and their maintenance need to outlive all of our individual contributions.

We recognize that a workflow tailored to the idioms of a specific language might be preferred by developers familiar with it, but we must avoid solutions or patterns that apply to only one of our many SDKs. The burden of maintaining many different development and release workflows would be unsustainable for the core team. This consistency in interfaces makes everything from documentation to testing easier—not just for the maintainers, but for end-users as well.

SDK Lifecycle and Maintainability

On the topic of different lifecycles, you are correct that the generator does not strictly enforce a monolithic release process. Separate SDKs can and do have independent versions and release schedules. That was not the initial design, but as the team grew and time dedicated to the SDKs was reduced, this divergence became an unfortunate byproduct.

That said, the primary requirement for an SDK to be considered an official OpenFGA SDK is its maintainability. If a contributor develops an SDK that works perfectly for their use case but is difficult for the current and future maintainers to support, it may be best for them to release and maintain it as a community SDK—and we fully support that_ (see https://github.com/openfga/community#community-projects). This ensures that official SDKs always meet a standard of quality, maintainability and consistency that we can stand behind.

Current Changes Based on Feedback

To ease the frustration that you (and other contributors & maintainers) have voiced, we have already moved away from a heavy-handed generation model. We've shifted towards a process more like the one you suggested, where only the foundational parts of the SDK are generated, leaving more of the idiomatic implementation details to be handled manually. You can see this change reflected in this PR to the generator and its companion PR to the Java SDK.

The Long-Term Vision: More Consistency, Not Less

With that said, this is not the long-term solution. We have already seen inconsistencies and bugs arise in our current SDKs precisely because critical interfaces are defined on a per-SDK basis. This leads to divergent behavior and a higher maintenance load.

Our long-term vision is to have more auto-generation and more cross-SDK consistency, not less. The ideal state is one where the OpenFgaApi and OpenFgaClient interfaces, configuration models, and even the core test suites are all auto-generated from a single, shared source of truth, with the OpenFgaApi itself being sourced directly from the API's .proto files. This guarantees that the core logic is identical and reliable everywhere. We demonstrated an early version of this shared testing approach in last week's community meeting, and our goal is to merge that work before the next one.

Planning is Still Underway

We are moving towards this vision slowly and carefully. It's a significant undertaking, and as a team with limited time, it will take longer than we'd like. We also recognize that our previous workflow, which worked well when we had a smaller group of contributors, doesn't scale to the diverse and growing community we have today.

This long-term vision is still being formed, and there is more planning to be done. We are committed to finding a balance that serves our entire community and that includes amazing contributors like yourself, and feedback like yours is very welcome and a critical part of that process.

Thank you again for your commitment to OpenFGA!