Skip to main content

Added Support for Read-Only and Write-Only Properties in API Transformer

· 2 min read

We are pleased to announce support for read-only and write-only properties in API Transformer which is one of the commonly used features of OpenAPI specification documents (v2.0 and above).

Details​

OpenAPI (v2.0 and above) supports marking schema properties as read-only or write-only. This means that if a schema definition is referenced by parameters and responses, the properties marked as read-only or write-only are intended to work differently for both cases. For a parameter, the read-only properties of a schema should be ignored even if they are marked as required. Similarly, for a response, the write-only properties should be ignored even if they are marked as required.

We have added support for such properties in API Transformer. A breakdown of our support is given below:

OpenAPI v3.0 and v3.1​

Transformation from or to OpenAPI v3.x documents will preserve information of read-only and write-only properties.

OpenAPI/Swagger v2.0​

Transformation from or to OpenAPI v2.0 documents will preserve information of read-only properties. Note, that OpenAPI v2.0 standard does not support write-only properties.

Postman Collection and Insomnia​

Export of Postman Collections and Insomnia files largely involve export of sample values for request parameters and responses. The following changes have been made to the export of sample values:

  • Sample value auto-generation will not include read-only properties in parameter samples and write-only properties in response level samples.
  • Existing samples at parameter level provided in the input specification document (e.g. OpenAPI) will be exported as is. However, any examples provided globally at schema level will no longer be exported for parameter level for risk of containing any read-only properties.
  • Existing samples at response level provided in the input specification document (e.g. OpenAPI) will be exported as is. However, any examples provided globally at schema level will no longer be exported for response level for risk of containing any write-only properties.

API Specification Document Validation​

Following additional checks have been added to the validation performed during transformation as part of the read-only, write-only properties' support: