Validate that the SDK Generator will behave as expected with the addition of AuthZenService

[rhamzeh]

Task for @openfga/dx team to do post merge:

• Validate if this will affect SDK generation, and if it does, either add an auto-generated AuthZenClient to handle it, or pre-process to remove AuthZEN endpoint

Originally posted by @rhamzeh in openfga/api#240 (review)

[rhamzeh]

@coderabbitai - can you clean up this issue, what we need to verify and add detailed steps for contributors to follow?

Also identify the pending decisions to be made, and label them clearly.

[coderabbitai]

Coding Plan

Summary

• Follow the established Makefile pattern of using jq del() expressions to exclude specific paths and definitions from the OpenAPI spec before generation
• Exclude all six AuthZEN paths and their associated definitions across all three build variants (build-openapi, build-openapi-streamed, build-openapi-non-streamed)
• This approach treats AuthZEN as an experimental feature that can be re-enabled in a future iteration when production-ready, potentially with a dedicated AuthZenClient
• No changes required to SDK templates, config files, or build scripts beyond the Makefile jq pipelines

Design Choices

Design Choice 1: Exclusion vs. Auto-Generated AuthZenClient Approach

Options Considered:

1. Pre-process to exclude AuthZEN endpoints — Add jq deletions in Makefile to remove all AuthZEN paths and definitions before generation, following the existing pattern used for read-tuples and streamed-list-objects
2. Auto-generate separate AuthZenClient — Modify tag normalization to preserve AuthZenService tag, potentially generating a separate API class, and handle any naming conflicts like Action

Chosen Option: 1

Rationale: Pre-process to exclude. This aligns with existing Makefile patterns, is appropriate for an experimental feature, requires minimal changes, and avoids potential naming conflicts (e.g., Action definition). A separate AuthZenClient can be added in a future iteration once AuthZEN is production-ready.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Update Makefile to Exclude AuthZEN Paths and Definitions

This phase adds pre-processing exclusions to the Makefile's jq pipelines, following the established pattern used for excluding read-tuples and streamed-list-objects endpoints. All three build variants must be updated consistently.

Task 1: Add AuthZEN Path Deletions to All Build Variants

Add jq del() expressions to remove all six AuthZEN paths from the OpenAPI spec before generation.

• Update Makefile targets build-openapi, build-openapi-streamed, and build-openapi-non-streamed to include path deletions for:
  • /.well-known/authzen-configuration/{store_id} (GetConfiguration endpoint)
  • /stores/{store_id}/access/v1/evaluation (single evaluation)
  • /stores/{store_id}/access/v1/evaluations (batch evaluations)
  • /stores/{store_id}/access/v1/search/action (ActionSearch)
  • /stores/{store_id}/access/v1/search/resource (ResourceSearch)
  • /stores/{store_id}/access/v1/search/subject (SubjectSearch)
• Follow the existing pattern: del(.paths."/<path>") chained with other deletions
• Place these deletions alongside existing read-tuples and streamed-list-objects exclusions

Task 2: Add AuthZEN Definition Deletions

Add jq del() expressions to remove all AuthZEN-specific schema definitions from the spec.

• Update the same three Makefile targets to delete definitions including:
  • Core entities: Subject, Resource, Action
  • Filters: SubjectFilter, ResourceFilter
  • Request/Response types: EvaluationRequest, EvaluationResponse, EvaluationsRequest, EvaluationsResponse, EvaluationsItemRequest, EvaluationsOptions
  • Search responses: ActionSearchResponse, ResourceSearchResponse, SubjectSearchResponse
  • Configuration: GetConfigurationResponse
  • Pagination: PageRequest (if AuthZEN-specific)
• Use pattern: del(.definitions.DefinitionName) for each definition
• Verify the complete list of AuthZEN definitions by inspecting the poc/authzen branch spec before implementation

Task 3: Document AuthZEN Exclusion and Future Considerations

Add inline documentation explaining the AuthZEN exclusions and rationale.

• Add a comment block in Makefile above the AuthZEN deletion expressions explaining:
  • These exclusions are for the experimental AuthZEN API surface from PR #240
  • The exclusions should be revisited when AuthZEN is ready for production
  • Reference to the original ticket/discussion for context
• Consider adding a note in README.md or contributing docs about the AuthZEN exclusion status

🤖 Prompt for AI agents

Update the `Makefile` to exclude all AuthZEN paths and definitions from the
OpenAPI spec pre-processing pipeline across all three build variants. The goal
is to prevent AuthZEN experimental endpoints from appearing in generated SDKs.

- In `Makefile`, locate the three targets: `build-openapi`,
`build-openapi-streamed`, and `build-openapi-non-streamed`
- In each target's `jq` pipeline, add `del()` expressions chained alongside
existing deletions (e.g., `read-tuples`, `streamed-list-objects`) to remove the
following **paths**:
  - `.paths."/.well-known/authzen-configuration/{store_id}"`
  - `.paths."/stores/{store_id}/access/v1/evaluation"`
  - `.paths."/stores/{store_id}/access/v1/evaluations"`
  - `.paths."/stores/{store_id}/access/v1/search/action"`
  - `.paths."/stores/{store_id}/access/v1/search/resource"`
  - `.paths."/stores/{store_id}/access/v1/search/subject"`
- In the same targets, add `del(.definitions.DefinitionName)` expressions to
remove the following **definitions**: `Subject`, `Resource`, `Action`,
`SubjectFilter`, `ResourceFilter`, `EvaluationRequest`, `EvaluationResponse`,
`EvaluationsRequest`, `EvaluationsResponse`, `EvaluationsItemRequest`,
`EvaluationsOptions`, `ActionSearchResponse`, `ResourceSearchResponse`,
`SubjectSearchResponse`, `GetConfigurationResponse`, and `PageRequest` (if
AuthZEN-specific — verify against the `poc/authzen` branch spec first)
- Above the new `del()` expressions, add a comment block in the `Makefile`
stating:
- These exclusions cover the experimental AuthZEN API surface introduced in PR
`#240`
  - They should be revisited when AuthZEN is production-ready
  - Include a reference to the original ticket/discussion
- Optionally add a note in `README.md` or contributing docs about the AuthZEN
exclusion status

Phase 2: Validation and Testing

Verify that the exclusions work correctly and don't break existing SDK generation.

Task 1: Test SDK Generation with AuthZEN-Enabled Spec

Validate that the updated Makefile correctly excludes AuthZEN content.

• Temporarily point OPEN_API_REF to the poc/authzen branch commit SHA
• Run make build-openapi and inspect docs/openapi/openfga.openapiv2.json to confirm:
  • No AuthZEN paths remain in the processed spec
  • No AuthZEN definitions remain
  • Tag array still correctly normalized to ["OpenFga"]
• Run make build-client-js (or another quick-to-build client) to verify generation completes without errors
• Confirm generated SDK files contain no references to AuthZEN endpoints or types

Task 2: Verify No Regression for Existing Endpoints

Ensure existing OpenFGA endpoints are unaffected by the new exclusions.

• Compare generated SDK output before and after changes using the current OPEN_API_REF (non-AuthZEN spec)
• Run existing test targets (make test-client-js, etc.) to confirm no regressions
• Verify that the streamed vs non-streamed build variants still function correctly

🤖 Prompt for AI agents

This phase focuses on validation — no new production code is written, but the
Makefile changes from Phase 1 must be verified end-to-end.

- Temporarily update `OPEN_API_REF` in the `Makefile` to the `poc/authzen`
branch commit SHA
- Run `make build-openapi` and open `docs/openapi/openfga.openapiv2.json` to
confirm:
  - None of the six AuthZEN paths are present
  - None of the AuthZEN definitions are present
  - All tags are still normalized to `["OpenFga"]`
- Run `make build-client-js` (or another fast client target) and confirm
generation completes without errors and the output contains no AuthZEN endpoint
or type references
- Restore `OPEN_API_REF` to the original (non-AuthZEN) commit SHA
- Re-run `make build-openapi` and diff the generated output against the
pre-change baseline to confirm no regressions in existing endpoints
- Run `make test-client-js` (and any other available test targets) to confirm
all existing tests still pass
- Verify that `build-openapi-streamed` and `build-openapi-non-streamed` variants
also produce correct output

Research

The SDK generator uses a Makefile-driven pipeline that fetches an OpenAPI spec from openfga/api (via OPEN_API_REF commit SHA), pre-processes it with jq to normalize tags and remove specific paths/definitions, then invokes openapi-generator-cli via scripts/build_client.sh. The pre-processing currently rewrites ALL tags to ["OpenFga"] (creating a single unified OpenFgaApi class) and already excludes certain endpoints like read-tuples and streamed-list-objects. There are three build variants: build-openapi, build-openapi-streamed, and build-openapi-non-streamed, each with slightly different path/definition deletions. The config structure under config/clients/ contains per-language overrides, templates, and ignore files.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Update the `Makefile` to exclude all AuthZEN paths and definitions from the
OpenAPI spec pre-processing pipeline across all three build variants. The goal
is to prevent AuthZEN experimental endpoints from appearing in generated SDKs.

- In `Makefile`, locate the three targets: `build-openapi`,
`build-openapi-streamed`, and `build-openapi-non-streamed`
- In each target's `jq` pipeline, add `del()` expressions chained alongside
existing deletions (e.g., `read-tuples`, `streamed-list-objects`) to remove the
following **paths**:
  - `.paths."/.well-known/authzen-configuration/{store_id}"`
  - `.paths."/stores/{store_id}/access/v1/evaluation"`
  - `.paths."/stores/{store_id}/access/v1/evaluations"`
  - `.paths."/stores/{store_id}/access/v1/search/action"`
  - `.paths."/stores/{store_id}/access/v1/search/resource"`
  - `.paths."/stores/{store_id}/access/v1/search/subject"`
- In the same targets, add `del(.definitions.DefinitionName)` expressions to
remove the following **definitions**: `Subject`, `Resource`, `Action`,
`SubjectFilter`, `ResourceFilter`, `EvaluationRequest`, `EvaluationResponse`,
`EvaluationsRequest`, `EvaluationsResponse`, `EvaluationsItemRequest`,
`EvaluationsOptions`, `ActionSearchResponse`, `ResourceSearchResponse`,
`SubjectSearchResponse`, `GetConfigurationResponse`, and `PageRequest` (if
AuthZEN-specific — verify against the `poc/authzen` branch spec first)
- Above the new `del()` expressions, add a comment block in the `Makefile`
stating:
- These exclusions cover the experimental AuthZEN API surface introduced in PR
`#240`
  - They should be revisited when AuthZEN is production-ready
  - Include a reference to the original ticket/discussion
- Optionally add a note in `README.md` or contributing docs about the AuthZEN
exclusion status
===============================================================================

Task: 2

This phase focuses on validation — no new production code is written, but the
Makefile changes from Phase 1 must be verified end-to-end.

- Temporarily update `OPEN_API_REF` in the `Makefile` to the `poc/authzen`
branch commit SHA
- Run `make build-openapi` and open `docs/openapi/openfga.openapiv2.json` to
confirm:
  - None of the six AuthZEN paths are present
  - None of the AuthZEN definitions are present
  - All tags are still normalized to `["OpenFga"]`
- Run `make build-client-js` (or another fast client target) and confirm
generation completes without errors and the output contains no AuthZEN endpoint
or type references
- Restore `OPEN_API_REF` to the original (non-AuthZEN) commit SHA
- Re-run `make build-openapi` and diff the generated output against the
pre-change baseline to confirm no regressions in existing endpoints
- Run `make test-client-js` (and any other available test targets) to confirm
all existing tests still pass
- Verify that `build-openapi-streamed` and `build-openapi-non-streamed` variants
also produce correct output

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!

[aaguiarz]

@rhamzeh we don't need to auto-generate SDKs for AuthZen endpoints