readOnly and writeOnly in OpenAPI: one schema for requests and responses
Last checked and updated
readOnly: true marks a property that appears in responses and should not be sent in requests, such as an id or createdAt. writeOnly: true marks one that is sent in requests and should not be returned, such as a password. Their purpose is to describe a resource once, where otherwise there would be an Item and an ItemInput schema.
One schema, two directions
Item:
type: object
required: [name]
properties:
id:
type: string
readOnly: true
name:
type: string
secret:
type: string
writeOnly: true
What a mock server does with it
A mock generated from this schema, used for the request and the response of POST /items, leaves the write-only property out of what it returns:
$ curl -X POST http://127.0.0.1:4632/items -H 'content-type: application/json' \
-d '{"name":"a","secret":"s3", ...}'
HTTP/1.1 201 Created
{"id":"string","name":"string", ...}
secret was accepted and is absent from the response; id is generated.
A request that sends the read-only id is accepted as well:
$ curl -X POST http://127.0.0.1:4632/items -H 'content-type: application/json' \
-d '{"id":"x1","name":"a", ...}'
HTTP/1.1 201 Created
That is consistent with the specification, which is worth reading closely.
What the specification says
OpenAPI 3.0: a read-only property "MAY be sent as part of a response but SHOULD NOT be sent as part of the request". Should not, addressed to the client; nothing obliges a server or a validator to refuse it. The same holds for writeOnly in responses. 3.0 adds one rule with teeth: when such a property is listed in required, the requirement applies in its own direction only, so a required read-only id is not required in a request.
OpenAPI 3.1 takes both keywords from JSON Schema 2020-12, where they are annotations: information for applications, with no effect on validation. The 3.1 text says a server may either ignore a read-only field it receives or treat it as an error, and notes that this differs from 3.0.
So tools differ, and are allowed to. A validator may reject a read-only property in a request or, like the mock above, accept it; a documentation tool may hide read-only properties from request examples; a code generator may leave them out of input types. Check the ones you rely on.
When to use two schemas instead
| Situation | Use |
|---|---|
A few server-set fields (id, timestamps) on an otherwise shared shape | readOnly |
| A secret that is set and never shown | writeOnly |
The server must reject a client-sent id with an error | a separate request schema, closed with additionalProperties: false |
| Create, update and read differ in several fields or in what is required | separate schemas (ItemCreate, ItemUpdate, Item), sharing parts through allOf |
readOnly documents intent; it does not enforce it everywhere. If accepting a client's id would be a bug in your API, the description has to say so with a schema that does not have the property.