From 7bcea5d5992458911c1370e925b0cd0d240376ea Mon Sep 17 00:00:00 2001 From: Ted Epstein Date: Thu, 19 Jul 2018 12:13:48 -0400 Subject: [PATCH] #1622 - Clarify spec wrt readOnly and writeOnly in referenced schemas Make it clear that `readOnly` and `writeOnly` are allowed in any Schema Object, but only effective when applied (directly or by reference) to a property subschema. Adds similar language to the `xml` property, addressing [Mike's comment](https://github.com/OAI/OpenAPI-Specification/issues/1622#issuecomment-401696524). Fixes #1622. --- versions/3.0.2.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/versions/3.0.2.md b/versions/3.0.2.md index ef26940d9b..e55470ec24 100644 --- a/versions/3.0.2.md +++ b/versions/3.0.2.md @@ -2317,9 +2317,9 @@ Field Name | Type | Description ---|:---:|--- nullable | `boolean` | Allows sending a `null` value for the defined schema. Default value is `false`. discriminator | [Discriminator Object](#discriminatorObject) | Adds support for polymorphism. The discriminator is an object name that is used to differentiate between other schemas which may satisfy the payload description. See [Composition and Inheritance](#schemaComposition) for more details. -readOnly | `boolean` | 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 | `boolean` | 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`. -xml | [XML Object](#xmlObject) | This MAY be used only on properties schemas. It has no effect on root schemas. Adds additional metadata to describe the XML representation of this property. +readOnly | `boolean` | MAY occur in any Schema Object. When used in a property subschema, either directly or [by reference](#referenceObject), a `true` value 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 | `boolean` | MAY occur in any Schema Object. When used in a property subschema, either directly or [by reference](#referenceObject), a `true` value 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`. +xml | [XML Object](#xmlObject) | MAY occur in any Schema Object. When used in a property subschema, either directly or [by reference](#referenceObject), specifies additional metadata to describe the XML representation of this property. externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this schema. example | Any | A free-form property to include an example of an instance for this schema. To represent examples that cannot be naturally represented in JSON or YAML, a string value can be used to contain the example with escaping where necessary. deprecated | `boolean` | Specifies that a schema is deprecated and SHOULD be transitioned out of usage. Default value is `false`.