Azure / Azure/azure-rest-api-specs
Foundry: standardize operationIds to `<Group>_<PascalCaseVerb>`
- 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
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