correctly interpret readOnly / writeOnly

[mnahkies]

so this is embarrassing, I've interpreted readOnly as being equivalent to the typescript readonly modifier.

however, the specification defines this, and it's friend writeOnly quite differently:

readOnly

Relevant only for Schema "properties" definitions. Declares the property as "read only". This means that it MAY be sent as part of a response but SHOULD NOT be sent as part of the request. If the property is marked as readOnly being true and is in the required list, the required will take effect on the response only. A property MUST NOT be marked as both readOnly and writeOnly being true. Default value is false.

writeOnly

Relevant only for Schema "properties" definitions. Declares the property as "write only". Therefore, it MAY be sent as part of a request but SHOULD NOT be sent as part of the response. If the property is marked as writeOnly being true and is in the required list, the required will take effect on the request only. A property MUST NOT be marked as both readOnly and writeOnly being true. Default value is false.

Eg: these serve to allow models to express a different interface for the different CRUD operations - without needing separate CreateUpdateX / X models as I've normally done...

fixing this will be a breaking change, and probably quite challenging to implement. It's unclear whether it's best to synthesis separate XWrite / XRead models, or use an Omit / Pick type approach.

note: 3.1 dropped these from the spec, deferring to the JSON schema definition. should consider whether we need to implement it differently for 3.1 vs 3.0, or just follow 3.1.

references

• https://swagger.io/specification/v3/#schema-object
• https://json-schema.org/understanding-json-schema/reference/annotations
• Clarify spec wrt readOnly and writeOnly in referenced schemas OAI/OpenAPI-Specification#1622