cancel
Showing results for 
Search instead for 
Did you mean: 

Callbacks and readOnly/writeOnly

SOLVED
Highlighted
New Contributor

Callbacks and readOnly/writeOnly

I have a question about how the readOnly and writeOnly properties relate to webhook requests.

 

The spec says of readOnly "This means that it MAY be sent as part of a response but SHOULD NOT be sent as part of the request" which seems clear enough. But while a callback is a request at the network level, at the semantic level it contains response data from the API.

 

For example if I have a schema for an object which has a readOnly createdDate property, I mean that it is forbidden in the request body when creating an object but will be present in the response when fetching an object. And when it comes to a callback, I would expect the createdDate to be present in the request body of the callback when it is sent to the remote server. 

 

The Swagger UI omits readOnly properties from the schema of requests, including callbacks. I started out creating a bug report there before realising that the implemented behaviour is a valid interpretation of the OpenAPI spec. But it seems wrong to me. I can't think of a situation where this behaviour is what I would want.

 

If this issue has been debated before, could someone point me to the discussion? If not, would there be any appetite for clarifying the spec to make readOnly/writeOnly relative to the API rather than the network request?

1 ACCEPTED SOLUTION

Accepted Solutions
Highlighted
Moderator

Re: Callbacks and readOnly/writeOnly

Generally speaking, readOnly and writeOnly take effect based on the request initiator. So, readOnly means that the consumer can only receive it and writeOnly means the consumer can only write it.

 

Callbacks (as opposed to pre-registered webhooks) are simply a way to describe delayed responses to requests. In that case, I'd expect the behavior to be the same as a regular synchronous request/response. So the callback call itself is a response rather than a request to the consumer.

 

Please note that in the upcoming 3.1 release of OpenAPI, there are two changes. Webhooks are being introduced as a first-class citizen to the specification, and the above explanation is not necessarily true for that. However, the definition of readOnly/writeOnly changes slightly as well to conform with JSON Schema, so it's interesting to think what kind of an impact it may have on that.


Did my reply answer your question? Give Kudos or Accept it as a Solution to help others.↓↓↓↓↓

View solution in original post

3 REPLIES 3
Highlighted
Moderator

Re: Callbacks and readOnly/writeOnly

Generally speaking, readOnly and writeOnly take effect based on the request initiator. So, readOnly means that the consumer can only receive it and writeOnly means the consumer can only write it.

 

Callbacks (as opposed to pre-registered webhooks) are simply a way to describe delayed responses to requests. In that case, I'd expect the behavior to be the same as a regular synchronous request/response. So the callback call itself is a response rather than a request to the consumer.

 

Please note that in the upcoming 3.1 release of OpenAPI, there are two changes. Webhooks are being introduced as a first-class citizen to the specification, and the above explanation is not necessarily true for that. However, the definition of readOnly/writeOnly changes slightly as well to conform with JSON Schema, so it's interesting to think what kind of an impact it may have on that.


Did my reply answer your question? Give Kudos or Accept it as a Solution to help others.↓↓↓↓↓

View solution in original post

Highlighted
New Contributor

Re: Callbacks and readOnly/writeOnly

Thanks. So you agree that the current implementation of Swagger UI which I described goes against your understanding of the spec? I'll open a ticket there. I opened a bug report.

 

I see what you mean about webhooks and callbacks being separate but given that most of the examples of using callbacks involve registering for a webhook, it would be quite confusing if webhooks defined using the webhooks key in OAS 3.1 behaved differently to other callbacks.

 

Do you think it's worth opening an issue at https://github.com/OAI/OpenAPI-Specification/ about this? I feel that the concept of "owning authority" in JSON Schema is quite vague and it would be helpful to make reference to it on the OAS spec.

Moderator

Re: Callbacks and readOnly/writeOnly

We've had a discussion about it during one of our TSC calls. What we ended up deciding (and will be clarified in OAS 3.1) is that readOnly/writeOnly will follow the guidelines of the JSON Schema definition of those keywords. In JSON Schema, they are referred to as annotations - that means they are informative, and really up to the tooling to decide how to implement the support for them.


Did my reply answer your question? Give Kudos or Accept it as a Solution to help others.↓↓↓↓↓
New Here?
Join us and watch the welcome video:
Announcements
Top Kudoed Authors