azure/azure-sdk-for-java/tsp-naming-collision

Fix TypeSpec Naming Collisions in Java Codegen

Fix parameter and implementation-model names that end with a numeric suffix (e.g. createAgentRequest1) in generated Java client code. This happens when a TypeSpec named `model` collides with the synthetic body type the Java codegen creates for an operation that spreads that model.

Root Cause

When a TypeSpec route spreads a named model into an operation's parameters (via ...ModelName), the Java codegen creates a synthetic body type to hold the body properties. It names this type {OperationName}Request (PascalCase of the operation name + Request). If a TypeSpec model already has that exact name, the codegen resolves the collision by appending 1.

Example collision:

• TypeSpec model: CreateAgentRequest
• Operation: createAgent spreads ...CreateAgentRequest
• Codegen synthetic body: wants name CreateAgentRequest → collision → CreateAgentRequest1
• Result: parameter createAgentRequest1, implementation class CreateAgentRequest1.java

Why aliases don't collide: TypeSpec alias declarations don't occupy a name in the type namespace, so there is no collision. If the upstream spec used alias CreateAgentRequest = { ... } instead of model CreateAgentRequest { ... }, no fix would be needed.

Preconditions

• You must be in the directory that contains tsp-location.yaml.
• The TypeSpec must already be synced locally into TempTypeSpecFiles/. If not, run tsp-client sync first.
• Identify the client.tsp file inside TempTypeSpecFiles/ (usually under a subdirectory like sdk-agents/). This is the customization file where fixes are applied.

Important: TempTypeSpecFiles is volatile

TempTypeSpecFiles/ is regenerated on every tsp-client sync or tsp-client update. Changes made only in `TempTypeSpecFiles/` will be lost. Always apply the same edits to the corresponding client.tsp in a local checkout of Azure/azure-rest-api-specs (if available) so the changes can be committed to a PR.

Workflow

1. Identify affected operations

Search the generated Java client classes for parameter names ending with 1:

grep -n 'Request1[,)]' src/main/java/com/azure/ai/agents/*Client.java

Also check for implementation model classes with the 1 suffix:

find . -name "*Request1.java" -path "*/implementation/models/*"

Collect the list of affected names (e.g. createAgentRequest1, updateAgentRequest1).

2. Trace back to the TypeSpec models

For each affected parameter, find the TypeSpec model that causes the collision. The model name matches the parameter name (PascalCase, without the 1).

Search the .tsp files:

grep -rn "model CreateAgentRequest\|model UpdateAgentRequest" TempTypeSpecFiles/ --include="*.tsp"

Confirm the model is used via spread (...ModelName) in the route definitions:

grep -rn "CreateAgentRequest\|UpdateAgentRequest" TempTypeSpecFiles/ --include="*.tsp"

Verify the model is a model (not an alias). Only named model types cause collisions.

3. Add @@clientName overrides

Edit the client.tsp customization file in TempTypeSpecFiles/. Add a @@clientName directive for each colliding model to give it a different client-side name. This frees the original name for the codegen's synthetic body type.

Use a consistent naming convention. Recommended: rename *Request → *Input:

// Rename request models to avoid collision with synthetic body types generated
// by the Java codegen. The codegen names synthetic bodies as {OperationName}Request,
// which clashes with the identically-named TypeSpec models, causing a "1" suffix.
@@clientName(CreateAgentRequest, "CreateAgentInput");
@@clientName(UpdateAgentRequest, "UpdateAgentInput");

Note: These models are typically not emitted as public Java classes — they only exist to be spread into operations. The rename is purely internal and does not affect the public API surface.

4. Regenerate and verify

Generate with --save-inputs to preserve the edited TypeSpec files:

tsp-client generate --save-inputs

Verify the 1 suffix is gone:

# Should return zero matches
grep -c "Request1" src/main/java/com/azure/ai/agents/*Client.java
 
# Old *Request1.java files should no longer exist
find src -name "*Request1.java" -path "*/implementation/models/*"
 
# New clean-named files should exist
find src -name "*Request.java" -path "*/implementation/models/*"

Compile to confirm no breakage:

mvn compile -Denforcer.skip=true -Dcodesnippet.skip=true -Dcheckstyle.skip=true \
  -Dspotbugs.skip=true -Dspotless.skip=true -Drevapi.skip=true -Djacoco.skip=true \
  -Dmaven.javadoc.skip=true -Dshade.skip=true -Danimal.sniffer.skip=true

5. Apply changes to the local spec repo (if available)

If the user has a local checkout of Azure/azure-rest-api-specs, apply the same `client.tsp` edits there. Derive the file path from tsp-location.yaml:

• directory field gives the relative spec path (e.g. specification/ai-foundry/data-plane/Foundry/src/sdk-agents)
• The file to edit is client.tsp inside that directory

For example, if the local repo is at <local-spec-repo>:

<local-spec-repo>/specification/ai-foundry/data-plane/Foundry/src/sdk-agents/client.tsp

Verify the file exists before editing. If it doesn't, warn the user and print the expected path.

6. Full round-trip from the remote spec (optional)

If the user wants to validate the fix end-to-end from the remote repo:

1. Commit and push the client.tsp changes in the spec repo
2. Get the new commit hash
3. Update the commit: field in tsp-location.yaml with the new hash
4. Run tsp-client update to sync and regenerate from the remote
5. Verify the 1 suffix is gone and the build compiles

Troubleshooting