Make handling of empty object consistent in request/response body #2868
Assignees
Labels
Milestone
Comments
This was referenced Jan 31, 2024
markcowl
added
the
breaking-change
|
est: 13 |
timotheeguerin
added a commit
that referenced
this issue
Apr 17, 2024
fix [#2868](#2868) - Change meaning of `@body` to mean this is the body and nothing will be excluded(show warning on containing metadata) - Add new `@bodyRoot` which has the same purpose as the old `@body`( Allows changing where the body is resolved from but allows mixing with metadata. - Add new `@bodyIgnore` which allows a property to be ignored from the body - Provide a new body resolution common function for request and response also fix #2075 ## Examples from original issue 1. [Inconsitency between request and response](https://cadlplayground.z22.web.core.windows.net/prs/2945/?c=aW1wb3J0ICJAdHlwZXNwZWMvaHR0cCI7Cgp1c2luZyBUeXBlU3BlYy5IdHRwOwoKLyoqCiAqIEJhc2VsaW5lIDE6IEhhdsQqYEBoZWFkZXJgIHByb3BlcnR5IG9ubHkgaW4gcmVxdWVzdMYLc3BvbnNlxAl1bMUTbm8gYm9kecRXUscpxBA6IHZvaWTGFnPFM80WLwpAcm91dGUoIi9i5wCNIikKQGdldCBvcCDIEygg5wCWIGN1c3RvbUjFDTogc3RyaW5nKToge90hIH0g6gD0Q2Fz5QDwQWRkxBtgQHZpc2liaWxpdHlgIHRv9AEBYmVoYXZlIGRpZmZlcmVudGx5IGZvcukBEGFuZOkBES7yAQB7ff8A%2FuUA%2FmNhc2UxIikKb3AgxQso6wCYKCJub%2BQBGOkA5XjuAPvfKsUqIH3vAQMy%2BgEDbm9uIGFubm90YXRlZOoBB%2BoB7GVtcOQBF%2FUB7%2FQA78UU7wDtMuoA7TL1AO3%2FAOXMIuUA3Q%3D%3D&e=%40typespec%2Fopenapi3&options=%7B%7D) 2. [Inconsitency between different ways](https://cadlplayground.z22.web.core.windows.net/prs/2945/?c=aW1wb3J0ICJAdHlwZXNwZWMvaHR0cCI7CtIZdmVyc2lvbmluZyI7Cgp1c2luZyBUeXBlU3BlYy5IdHRwO9AVVskyOwoKQHNlcnZpY2UKQMdJZWQoxyFzKQpuYW1lc3BhY2UgTXlTxik7CmVudW0gyCQgewogIHYxLMQGMiwKfQoKQHJvdXRlKCJ0MSIpIG9wIHQxKCk6IHZvaWQ7IC8vIDIwNMUNyigyxygyxCh7fccmMM8mM8cmM8UmQGhlYWRlciBmb286IHN0cmluZ9g5NMc5NMY5dmlzaWJpbGl0eSgiZ2F0ZXdheSIp30jFSDXHSDXcSP8AmMxQNsdQNsVQ1THGFiJhYmMifco5N8c5N8U5QGFkZOsBtC52MvMAzsR6IGluIHYxykc4x0c430fFRyzpANpvdGhlcthe&e=%40typespec%2Fopenapi3&options=%7B%7D) ## Breaking changes Azure spec PR showing scale of breaking changes Azure/azure-rest-api-specs#27897 ### `@body` means this is the body This change makes it that using `@body` will mean exactly this is the body and everything underneath will be included, including metadata properties. It will log a warning explaining that. ```tsp op a1(): {@Body _: {@Header foo: string, other: string} }; ^ warning header in a body, it will not be included as a header. ``` Solution use `@bodyRoot` as the goal is only to change where to resolve the body from. ```tsp op a1(): {@bodyRoot _: {@Header foo: string, other: string} }; ``` ### Empty model after removing metadata and visibility property result in void always This means the following case have changed from returning `{}` to no body ```tsp op b1(): {}; op b2(): {@visibility("none") prop: string}; op b3(): {@added(Versions.v2) prop: string}; ``` Workaround: Use explicit `@body` ```tsp op b1(): {@Body _: {}}; op b2(): {@Body _: {@visibility("none") prop: string}}; op b3(): {@Body _: {@added(Versions.v2) prop: string}}; ``` ### Status code always 200 except if response is explicitly `void` ```tsp op c1(): {@Header foo: string}; // status code 200 (used to be 204) ``` Solution: Add explicit `@statusCode` ```tsp op c1(): {@Header foo: string, @statuscode _: 204}; op c1(): {@Header foo: string, ...NoContent}; // or spread common model ``` ### Properties are not automatically omitted if everything was removed from metadata or visibility ```tsp op d1(): {headers: {@Header foo: string}}; // body will be {headers: {}} ``` Solution: use `@bodyIgnore` ```tsp op d1(): {@bodyIgnore headers: {@Header foo: string}}; // body will be {headers: {}} ``` --------- Co-authored-by: Mark Cowlishaw <markcowl@microsoft.com>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Design #2513
@body=>@bodyRootin its current meaning@body=> now means actual body. Nothing inside of this can be metadata(header, query, etc.)@bodyIgnore=> provide a way to ignore a property from the body{}after removing all ignored properties then the body isvoidvoidthen it is 204 (Or do we want to always make it 200)Tasks
The text was updated successfully, but these errors were encountered: