allow both readOnly and required for a given property

[wking]

Since it landed in 34793ee (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.

[fenjen]

When it comes to the request, it's impossible to support a property a being readOnly and being required.

I disagree on that. All natural primary keys are readonly and required ("immutable").

Let's say, we have a list of email subscribers. The natural primary key is the email address. I'd POST an instance of this model:

Subscriber
  email (readonly, required)
  date (readonly)
  password (writeonly, nullable=false)

HTTP methods and their attributes:

Method	Attributes
GET	email, date
POST	email, password
PUT	email, password
PATCH	password

We can keep everything simple (with no need for various models for each verb), if we just embrace the combination of readonly required. I think, the standard should just remove sentences like "readOnly properties are included in responses but not in requests" or "This means that it MAY be sent as part of a response but SHOULD NOT be sent as part of the request", because these are just the result of an incomplete analysis.

Somewhere I read "readOnly would be used to mark a database-generated serial number as read-only". I wonder why the author stopped at "database-generated serial number", and did not continue thinking about natural keys, like serial numbers of physical articles, mail addresses, telephone numbers, and, well, everything that already exists uniquely before it's persisted to database.