Add guideline for common request/response schemas
tkrop opened this issue · 0 comments
tkrop commented
In the guild meeting we have discussed that we want to provide additional guidance on how to utilize a common schema definition for requests and responses. JSON Schema draft is providing support for readOnly
and writeOnly
flags to differentiate between properties only present in a request and properties only present in a response. The guideline has the following goals:
- It encourages the use of a common schema for requests and responses instead of writing to separate models where possible.
- It defines the default unspecified server behavior for
readOnly
that a server should ignore the field (opposing to rule #109 that suggest to reject fields unknown in the request object). APIs rejectingreadOnly
fields consequently need to specify their non-default-like behavior explicitly.