Azure / Azure/azure-rest-api-specs

Foundry: standardize operationIds to `<Group>_<PascalCaseVerb>`

Open
#42,929 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
TypeSpec
Stars
3.1k
Forks
5.9k
Avg merge
2d 22h
Merged PRs (30d)
444

Description

Tracking a follow-up spec cleanup spotted in [PR #42881 (review)](https://github.com/Azure/azure-rest-api-specs/pull/42881#discussion_r3189222750).

### Context
The OpenAPI emitter currently produces operationIds like Agents_createAgent — _ — for every operation in the Foundry spec.

- 101/101 op IDs in specification/ai-foundry/data-plane/Foundry/openapi3/v1/microsoft-foundry-openapi3.json follow this pattern.
- 122/122 op IDs in …/openapi3/virtual-public-preview/microsoft-foundry-openapi3.json follow this pattern.
- 0 operations use the conventional _ form.

This is the default behavior of @typespec/openapi3 over TypeSpec's camelCase operation names. operationId drives reference-docs TOC and (in some emitters) SDK method names, so the Azure-standard form is Agents_CreateAgent.

### Proposed fix
Use the [@operationId](https://typespec.io/docs/libraries/openapi/reference/decorators/#@TypeSpec.OpenAPI.operationId) decorator on each operation (or set up a convention in client.tsp) to override the emitted value with _.

### Why a separate PR
- Touches ~100 operations across specification/ai-foundry/data-plane/Foundry/src/**/routes.tsp.
- Changes operationIds in **both** 1 and irtual-public-preview outputs — needs a heads-up to anyone who has already generated SDKs against the preview surface.
- Out of scope for PR #42881 (which only re-exposes 5 code-based-agent routes to v1).

### Acceptance
- All operationIds in both emitted microsoft-foundry-openapi3.json files match ^[A-Za-z]+_[A-Z][A-Za-z]+$.
- Stakeholders for any preview-generated SDKs are aware of the surface rename.

cc @dargilco @glecaros

Contributor guide

Open the contributing guide

Research direction

Start with the linked PR review and the TypeSpec routes under specification/ai-foundry/data-plane/Foundry/src/**/routes.tsp, then inspect client.tsp and the @operationId decorator guidance. Check both emitted microsoft-foundry-openapi3.json files and update the operation IDs so every one matches ^[A-Za-z]+_[A-Z][A-Za-z]+$. Confirm the preview SDK surface change is communicated to stakeholders.

Written by the indexing model from the issue text.

Assessment

Tech stack
openapi
Domain
api
Issue type
Refactor
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.