From a258ce41a4e2624c1fc3cc7082474fb6812e2c9d Mon Sep 17 00:00:00 2001 From: Phil Sturgeon Date: Mon, 28 Oct 2019 13:47:39 -0400 Subject: [PATCH 1/2] Resolved undocumented nullable behavior OpenAPI Schema Objects and JSON Schema have a few fundamental differences, and this clears up a bit of confusion about one of them. --- versions/3.0.3.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.0.3.md b/versions/3.0.3.md index 055bc9dd66..73477537f5 100644 --- a/versions/3.0.3.md +++ b/versions/3.0.3.md @@ -2326,7 +2326,7 @@ Other than the JSON Schema subset fields, the following fields MAY be used for f ##### Fixed Fields Field Name | Type | Description ---|:---:|--- -nullable | `boolean` | Allows sending a `null` value for the defined schema. Default value is `false`. +nullable | `boolean` | Allows sending a `null` value for the defined schema. Default value is `false`.

A `nullable` value of `true` allows `null` in addition to other specified `type` values only if `nullable` and `type` are both specified within the same schema object. The effect of `"nullable" : true` is limited to its expansion of the set of allowed types, within the scope of its containing schema. An `enum`, `const`, `allOf`, or other keyword can independently prohibit `null` values, effectively overriding `"nullable" : true`.

A `nullable` value of `false` leaves the specified or default `type` unmodified. It has no effect on the schema object. 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`. From 7fd23cd743ca596c9c6faaaf571a17d55d36c80a Mon Sep 17 00:00:00 2001 From: Phil Sturgeon Date: Fri, 1 Nov 2019 20:23:42 +0100 Subject: [PATCH 2/2] Added ted updates from oct 31st TSC Co-Authored-By: Ted Epstein --- versions/3.0.3.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.0.3.md b/versions/3.0.3.md index 73477537f5..c138aca3a0 100644 --- a/versions/3.0.3.md +++ b/versions/3.0.3.md @@ -2326,7 +2326,7 @@ Other than the JSON Schema subset fields, the following fields MAY be used for f ##### Fixed Fields Field Name | Type | Description ---|:---:|--- -nullable | `boolean` | Allows sending a `null` value for the defined schema. Default value is `false`.

A `nullable` value of `true` allows `null` in addition to other specified `type` values only if `nullable` and `type` are both specified within the same schema object. The effect of `"nullable" : true` is limited to its expansion of the set of allowed types, within the scope of its containing schema. An `enum`, `const`, `allOf`, or other keyword can independently prohibit `null` values, effectively overriding `"nullable" : true`.

A `nullable` value of `false` leaves the specified or default `type` unmodified. It has no effect on the schema object. +nullable | `boolean` | A `true` value adds `"null"` to the allowed type specified by the `type` keyword, only if `type` is explicitly defined within the same Schema Object. Other Schema Object constraints retain their defined behavior, and therefore may disallow the use of `null` as a value. A `false` value leaves the specified or default `type` unmodified. The 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`.