Openapi-specification: allow both readOnly and required for a given property

[wking]

Since it landed in 34793ee1 (Added readOnly to Schema, data type clarifications, 2014-09-10), the readOnly property has the following semantics:

This means that it MAY be sent as part of a response but MUST NOT be sent as part of the request. Properties marked as readOnly being true SHOULD NOT be in the required list of the defined schema.

It seems like there's an unambiguous interpretation for properties with both settings enabled:

This means that it MAY be sent as part of a response but MUST NOT be sent as part of the request. If a property is marked as both readOnly and true, it MUST be sent as part of a response.

That's useful for a number of my own properties that report aggregate information (e.g. the amount of product in stock is always returned by requests but never set by requests to the product endpoints. Users update the stock count by updating the stock endpoints). It would also be useful for things like object IDs, which are currently complicated.

The downside to this interpretation would be that you'd need two separate schemas (one for requests and another for responses) if you wanted to validate with a non-Swagger-aware JSON Schema validator. Since it would be easy to generate the basic JSON Schema schemas, I don't think that's enough of a problem to hold this up. Folks who feel like it is would certainly be free to avoid using both readOnly and required for a given property ;).

[webron]

I normally view the required property as more relevant to the _request_ rather than the _response_. When it comes to the _request_, it's impossible to support a property a being readOnly _and_ being required.

The readOnly property was added after repeating requests to allow to describe models with properties that can only be sent by the server but never by the client, instead of duplicating the models. Obviously, there are other use cases that do not get handled by this. For example. there's no writeOnly property, which would have been useful for password fields.

We discussed the option of more fine-grained control (request only, response only, required and so on), but decided that for this version, with the numerous changes involved, that we would rather not complicate it further.

[bgrant0607]

Related question about immutability: a field that may be specified upon creation (POST) but may not be changed. We can't simply elide the field from the model used with PUT, because we require the complete resource be specified to PUT (as opposed to PATCH). We also support creation via PUT, which makes the separate-model approach infeasible, as well.

[webron]

@bgrant0607 - not sure how the original issue resolves your situation. You're basically looking to describe multiple models for a single operation (operation being path + http verb, unless you use a mime type too?).

[webron]

Tackling PR: #741

[ePaul]

I normally view the required property as more relevant to the request rather than the response.

This means an API consumer can't be sure that what he gets from the server actually contains the required attributes?

[webron]

This has been implemented in #894. Note the wording in the spec.