Skip to content

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

SituationUse
A few server-set fields (id, timestamps) on an otherwise shared shapereadOnly
A secret that is set and never shownwriteOnly
The server must reject a client-sent id with an errora separate request schema, closed with additionalProperties: false
Create, update and read differ in several fields or in what is requiredseparate 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.

Sources

Related pages

Try it with your own API

Create a free workspace, add an OpenAPI file, and publish its documentation and a mock server from the same repository.

Free for individuals. No credit card.

$ npm install -g @apigit/cli$ apigit auth login$ apigit doc publish