Azure / Azure/typespec-azure

Improve emitter documentation for handling version mutators in multi-version specs

Open
#1,992 7 comments 0 reactions 0 assignees View on GitHub
bug cli/psh needs-area triaged:core
Dominant language
TypeScript
Stars
27
Forks
90
Avg merge
1d 21h
Merged PRs (30d)
164

Description

### Describe the bug

The target tsp is from MongoCluster: https://github.com/Azure/azure-rest-api-specs/blob/main/specification/mongocluster/DocumentDB.MongoCluster.Management/main.tsp#L23

When we try to access the properties from metadata of @typespec/http, we cannot find the property `groupId` added in v4, while this mongoCluster is using commonTypes.v5.

The lost property is`groupId` here: https://github.com/Azure/typespec-azure/blob/79f047c60e9e614d2217d0e519e10cbf6541f865/packages/typespec-azure-resource-manager/lib/common-types/private-links.tsp#L61-L62

### Reproduction

Our emitter is `typespec-aaz` here: https://github.com/Azure/aaz-dev-tools/tree/dev/src/typespec-aaz
Please clone the emitter above, link it to local npm env and then provide the tspconfig.yaml as following:

![Image](https://github.com/user-attachments/assets/6e34d783-9eea-42dd-8f9a-1d88e0c27029)

And then, run `tsp compile ${your_workspaceFolder}/specification/mongocluster/DocumentDB.MongoCluster.Management/main.tsp -- config yourconfig.yaml` and check the output file `./tsp-output/@azure-tools/typespec-aaz/resources_operations.json` .

we can check `properties` of `privateEndpointConnections` and you'll find `privateEndpoint`, `privateLinkServiceConnectionState` and other stuff, except `groupIds`.

Emitter code line for parsing properties of common types `PrivateEndpointConnectionProperties` is here: https://github.com/Azure/aaz-dev-tools/blob/dev/src/typespec-aaz/src/convertor.ts#L655. We use metadata from `@typespec/http` and check all its properties for our aaz model generation.

### Checklist

- [x] Follow our [Code of Conduct](https://github.com/azure/typespec-azure/blob/main/CODE_OF_CONDUCT.md)
- [x] Check that this issue is about the Azure libraries for typespec. For bug in the typespec language or core libraries file it in the [TypeSpec repo](https://github.com/Microsoft/TypeSpec/issues/new/choose)
- [x] Check that there isn't already an issue that request the same bug to avoid creating a duplicate.
- [x] The provided reproduction is a [minimal reproducible example](https://stackoverflow.com/help/minimal-reproducible-example) of the bug.

Contributor guide

Open the contributing guide

Research direction

Reproduce the issue with the MongoCluster main.tsp and the provided tspconfig.yaml, then inspect src/typespec-aaz/src/convertor.ts around line 655. Compare the metadata for PrivateEndpointConnectionProperties with private-links.tsp around lines 61-62 and the generated resources_operations.json. Done means the documentation clearly explains version mutators and the expected handling of groupIds in multi-version specs.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
tooling
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.