Skip to content

Commit c58f5bf

Browse files
committed
Snappy answers to stupid questions.
1 parent d1e3d94 commit c58f5bf

File tree

1 file changed

+28
-1
lines changed

1 file changed

+28
-1
lines changed

proposals/003_Clarify-Nullable.md

+28-1
Original file line numberDiff line numberDiff line change
@@ -93,9 +93,10 @@ So the 3.0 spec is ambiguous about null values. It's not clear whether the spec
9393
### Specific Questions
9494

9595
Questions that are not answered by the current specification include the following:
96+
9697
* 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).)
9798

98-
* 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?
99+
* 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?
99100

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

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

134135
* 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`.
135136

137+
### Questions Answered
138+
139+
Following are answers to the questions posed above, assuming the proposed clarification is adopted:
140+
141+
#### 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).)
142+
143+
No. The `nullable: true` assertion folds into the `type` assertion, which presumably specifies `integer` or `number`.
144+
145+
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.
146+
147+
#### 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?
148+
149+
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.
150+
151+
#### Can `allOf` be used to define a nullable subtype of non-nullable base schema? (See [#1368](https://github.com/OAI/OpenAPI-Specification/issues/1368).)
152+
153+
No. Subtypes can add constraints, but not relax them.
154+
155+
#### Can `allOf` be used to define a non-nullable subtype of nullable base schema?
156+
157+
Yes. The subtype can specify a `type` without `nullable: true`, or can specify `not: {enum: [null]}`.
158+
159+
#### What is the correct translation of a nullable schema from OpenAPI into an equivalent JSON Schema?
160+
161+
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'`.
162+
136163
## Backwards compatibility
137164

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

0 commit comments

Comments
 (0)