Skip to content
Permalink
Browse files

Proposal/Clarify Nullable - Add interactions with default (#2058)

* Addressing #1389, and clearing the way for PRs #2046 and #1977. This adds a formal proposal to clarify the semantics of nullable, providing the necessary background and links to related resources.

* Corrected table formatting.

* Minor tweaks and corrections.

* Correct Change Log heading.

* Cleaned up notes about translation to JSON Schema and *Of inheritance semantics.

* Fix Change Log heading in the proposal template.

* Snappy answers to stupid questions.

* Change single-quote 'null' to double-quote "null"

Thanks, @handrews for the review.

* Clarified the proposed definition of nullable

Somehow in our collaborative editing, we neglected to state that `nullable` adds `"null"` to the set of allowed types. We just said that it "expands" the `type` value, but didn't state the obvious (to us) manner of said expansion. Correcting that oversight in this commit.

* Corrected the alternative, heavy-handed interpretation of nullable.

* Added more explicit detail about the primary use case.

* Added a more complete explanation of the problems created by disallowing nulls by default.

* Added issue #2057 - interactions between nullable and default value.
  • Loading branch information
tedepstein authored and darrelmiller committed Nov 21, 2019
1 parent 1d4e51f commit b98e8c908ac37ef1fcb09243af11e54ddf257573
Showing with 10 additions and 2 deletions.
  1. +10 −2 proposals/003_Clarify-Nullable.md
@@ -10,7 +10,7 @@
|Review Manager |TBD|
|Status |Proposal|
|Implementations |N/A|
|Issues | [1900](https://github.com/OAI/OpenAPI-Specification/issues/1900), [1368](https://github.com/OAI/OpenAPI-Specification/issues/1368), [1389](https://github.com/OAI/OpenAPI-Specification/issues/1389), [1957](https://github.com/OAI/OpenAPI-Specification/pull/1957), [2046](https://github.com/OAI/OpenAPI-Specification/pull/2046), [1977](https://github.com/OAI/OpenAPI-Specification/pull/1977#issuecomment-533333957) |
|Issues | [1900](https://github.com/OAI/OpenAPI-Specification/issues/1900), [1368](https://github.com/OAI/OpenAPI-Specification/issues/1368), [1389](https://github.com/OAI/OpenAPI-Specification/issues/1389), [1957](https://github.com/OAI/OpenAPI-Specification/pull/1957), [2046](https://github.com/OAI/OpenAPI-Specification/pull/2046), [1977](https://github.com/OAI/OpenAPI-Specification/pull/1977#issuecomment-533333957), [2057](https://github.com/OAI/OpenAPI-Specification/issues/2057)|
|Previous Revisions |N/A |

## Change Log
@@ -87,7 +87,7 @@ components:
UTCDate:
allOf:
$ref: "#/components/schemas/OptionalDate"
- $ref: "#/components/schemas/OptionalDate"
not:
type: string
pattern: "^.*Z.*$"
@@ -140,6 +140,8 @@ Questions that are not answered by the current specification include the followi

* What is the correct translation of a nullable schema from OpenAPI into an equivalent JSON Schema?

* Is `null` allowed as the `default` value of a nullable schema? (See [#2057](https://github.com/OAI/OpenAPI-Specification/issues/2057).)

## Proposed solution

We propose to clarify the 3.0 specification in the next patch release, to resolve these questions and align OpenAPI's Schema Object with JSON Schema's well-defined, constraint-based semantics.
@@ -196,6 +198,12 @@ Yes. The subtype can specify a `type` without `nullable: true`, or can specify `

A nullable type should translate into a type array with two string elements: the name of the type specified in the Schema Object, and `"null"`.

#### Is `null` allowed as the `default` value of a nullable schema? (See [#2057](https://github.com/OAI/OpenAPI-Specification/issues/2057).)

Yes. For example, a Schema Object with `"type" : "string", "nullable" : true` would translate to a JSON Schema with `"type" : ["string", "null"]`. That schema permits `"default" : null`, even with the [strict typing rule](https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.0.md#properties) specified by OpenAPI 3.0:

> default - The default value represents what would be assumed by the consumer of the input as the value of the schema if one is not provided. Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object defined at the same level. For example, if `type` is `string`, then `default` can be `"foo"` but cannot be `1`.
## Backwards compatibility

Spec revisions through 3.0.2 are ambiguous as described above, so any possible clarification has the potential to break existing implementations.

0 comments on commit b98e8c9

Please sign in to comment.
You can’t perform that action at this time.