Skip to content

Commit

Permalink
Snappy answers to stupid questions.
Browse files Browse the repository at this point in the history
  • Loading branch information
tedepstein committed Oct 31, 2019
1 parent d1e3d94 commit c58f5bf
Showing 1 changed file with 28 additions and 1 deletion.
29 changes: 28 additions & 1 deletion proposals/003_Clarify-Nullable.md
Original file line number Diff line number Diff line change
Expand Up @@ -93,9 +93,10 @@ So the 3.0 spec is ambiguous about null values. It's not clear whether the spec
### Specific Questions

Questions that are not answered by the current specification include the following:

* If a schema specifies `nullable: true` and `enum: [1, 2, 3]`, does that schema allow null values? (See [#1900](https://github.com/OAI/OpenAPI-Specification/issues/1900).)

* Does an untyped schema (without a `type` keyword) allow null values by default? What effect, if any,does `nullable: true` have on an untyped schema?
* Does an untyped schema (without a `type` keyword) allow null values by default? What effect, if any, does `nullable: true` have on an untyped schema?

* Can `allOf` be used to define a nullable subtype of non-nullable base schema? (See [#1368](https://github.com/OAI/OpenAPI-Specification/issues/1368).)

Expand Down Expand Up @@ -133,6 +134,32 @@ This also solves the issues of alignment with JSON Schema:

* It is now clear that `nullable: false`, whether explicit or by default, _does not_ prohibit null values. Consistent with JSON Schema, an empty object allows all values, including `null`.

### Questions Answered

Following are answers to the questions posed above, assuming the proposed clarification is adopted:

#### If a schema specifies `nullable: true` and `enum: [1, 2, 3]`, does that schema allow null values? (See [#1900](https://github.com/OAI/OpenAPI-Specification/issues/1900).)

No. The `nullable: true` assertion folds into the `type` assertion, which presumably specifies `integer` or `number`.

While the modified `type` now allows `null`, the `enum` does not. Consistent with JSON schema, a value conforms to the schema only if it is valid against _all_ constraints. Any constraint, in this case `enum`, can cause a value to fail validation, even if that value meets all of the other constraints.

#### Does an untyped schema (without a `type` keyword) allow null values by default? What effect, if any, does `nullable: true` have on an untyped schema?

Yes, an untyped schema allows null values, in addition to all other types. `nullable: true` has no effect, because null values are already allowed. And `nullable: false` has no effect because it just leaves the `type` constraint unmodified.

#### Can `allOf` be used to define a nullable subtype of non-nullable base schema? (See [#1368](https://github.com/OAI/OpenAPI-Specification/issues/1368).)

No. Subtypes can add constraints, but not relax them.

#### Can `allOf` be used to define a non-nullable subtype of nullable base schema?

Yes. The subtype can specify a `type` without `nullable: true`, or can specify `not: {enum: [null]}`.

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

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'`.

## Backwards compatibility

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

0 comments on commit c58f5bf

Please sign in to comment.