microsoft / microsoft/typespec

[Bug]: Difficulty expressing optional type field for tool output submission across versions

Open
#8,533 0 comments 0 reactions 0 assignees View on GitHub
bug lib:versioning triaged:core
Dominant language
Java
Stars
5.9k
Forks
394
Avg merge
1d 23h
Merged PRs (30d)
104

Description

### Describe the bug

We recently introduced a type field in the tool output submission payload to support a new tool for computer use. This field is optional and the API implementation is fully backward compatible—if type is omitted, the backend defaults to function tool output.
However, reflecting this optional field cleanly in TypeSpec has been challenging. Specifically:

I attempted to union the non-discriminated (legacy) format with the new discriminated format using type, but ran into limitations.
As a workaround, I updated the shared type definition across all versions to include the type field, while documenting that it is still optional in the API.
This was necessary to avoid breaking the spec and to ensure both formats are accepted.
I’ve documented that type is optional and both formats are supported, but I’m open to better ways to isolate this change to newer versions or express it more cleanly.

**Ask:**
A better way to represent this optional type field without modifying stable versions and without breaking generated SDK code? Ideally, I’d like to support both formats while keeping the spec clean and version-safe.

Thanks!

### Reproduction

Please reference SubmitToolOutput in this PR for the scenario described above:
https://github.com/Azure/azure-rest-api-specs/pull/36325

### Checklist

- [x] Follow our [Code of Conduct](https://github.com/microsoft/typespec/blob/main/CODE_OF_CONDUCT.md)
- [x] Check that there isn't already an issue that request the same bug to avoid creating a duplicate.
- [x] Check that this is a concrete bug. For Q&A open a [GitHub Discussion](https://github.com/Microsoft/typespec/discussions).
- [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

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.