microsoft / microsoft/typespec

Ability to modify response objects for supporting custom schema property names and other custom properties

Open
#9,159 3 comments 0 reactions 0 assignees View on GitHub
design:needed emitter:openapi3 mq triaged:core
Dominant language
Java
Stars
5.9k
Forks
394
Avg merge
1d 23h
Merged PRs (30d)
104

Description

### Clear and concise description of the problem

**Current behavior:**
When generating response objects, the OpenAPI emitter always uses the standard name `schema` for schema properties. Example:

```
responses:
"200":
content:
text/event-stream:
schema:
$ref: '#/components/schemas/Foo'
```
Furthermore, it's not possible to add any extra properties to a response either, as the `@extension` decorator doesn't work on response objects or their bodies. [Playground example](https://typespec.io/playground/?e=%40typespec%2Fopenapi3&c=aW1wb3J0ICJAdHlwZXNwZWMvaHR0cCI7CtIZb3BlbmFwaSI7Cgp1c2luZyBIdHRwO8cMT3BlbkFQSTsKCkBzZXJ2aWNlKCN7IHRpdGxlOiAiV2lkZ2V0IFPGGiIgfSkKbmFtZXNwYWNlIERlbW%2FHGjsKCm1vZGVsIMcxewogIEB2aXNpYmlsaXR5KExpZmVjeWNsZS5SZWFkKQogIGlkOiBzdHJpbmc7CgogIHdlaWdodDogaW50MzI7CiAgY29sb3I6ICJyZWQiIHwgImJsdWUiOwp9CgpAZXJyb3LHcEXEDMVvY29kZctAbWVzc2FnZcplfQoKLy8gdGhpcyBkb2VzIG5vdCBhcHBlYXIgaW4gb3V0cHV06AEOCkBleHRlbnNpb24oIngtY29vbCIsIHRydWUpx3hTcGVjaWFsUmVzcG9uc2U8VD7lAIUvLyBuZWl0aGVyxmXFb8Zm5AESzVZoZWxsb8lXICBAYm9keSDEBTogVOYA6uQBS29wIHJlYWQoQHBhdGjlATfmAWQuaWQpOvEAiMYcPiB85gEaOwo%3D&options=%7B%7D&vs=%7B%7D)

**Expected / desired capability:**
In some cases, it is necessary to replace the `schema` property with a custom name for that property, or add a new property altogether. This requires a modification to that response object. Example:

```
responses:
"200":
content:
text/event-stream:
x-custom-schema:
$ref: '#/components/schemas/Foo'
```

**Details & Reasoning:**
Certain tools and workflows require vendor-specific fields or an alternative schema naming for compatibility. TypeSpec currently provides no mechanism to express this pattern of needing to override or extend a response object's properties. Adding this capability would allow more flexible integration with custom or extended API formats.

**Proposed enhancement:**
Introduce a mechanism that allows users to:

- Override the emitted key name for `schema` on a per-response or per-content basis
- Emit vendor-specific fields such as `x-custom-schema` instead of `schema`
- Suppress that default schema property when a custom one is provided
- More broadly, modify/extend response objects as needed

This enhancement would support real-world scenarios where OpenAPI responses must be combined with extended or proprietary fields.

### Checklist

- [x] Follow our [Code of Conduct](https://github.com/microsoft/typespec/blob/main/CODE_OF_CONDUCT.md)
- [x] Read the [docs](https://typespec.io/docs/).
- [x] Check that there isn't already an issue that request the same feature to avoid creating a duplicate.

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.