-
Notifications
You must be signed in to change notification settings - Fork 9.1k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Question: nullable and enum #1900
Comments
@left-rite, your first answer is correct:
I think of
... where (Please note that Using this theoretical translation, your example would translate into this JSON Schema:
This is consistent with the way nullable works in other cases. |
The docs say here that "enum" behaves as defined in JSON Schema spec. "enum" being affected by "nullable" is not consistent with JSON Schema spec. |
@epoberezkin , I would say that all assertions in JSON Schema are affected by |
@epoberezkin , looking more closely at the JSON Schema spec:
Does
JSON Schema categorizes its keywords as assertions, annotations, and applicators. A few keywords may function as more than one of these categories. I think You can easily see how this could cause a problem with Bird:
type: object
properties:
order:
type: string
genus:
type: string
species:
type: string
flightSpeed:
type: number
FlightlessBird:
allOf:
- $ref: "#/components/schemas/Bird"
properties:
flightSpeed:
type: number
nullable: true But JSON Schema allows all kinds of contradictory schemas. So using it in a subtype would not override the constraints of the supertype. An object with I'm inclined to agree that the OpenAPI spec should be clarified here, but we would need to figure out how best to do it. |
2 options:
|
@epoberezkin , I like your suggested options. They also seem to correspond to two different translations of 1.
|
Note the related discussion in #1389, which proposes replacing So I started out saying that translation 1 was the correct way to interpret And in that case, the |
Please note that a proposed clarification is now under review, hopefully to be included in a v3.0.3 patch release of the OpenAPI spec: |
@tedepstein @MikeRalphson @webron since the clarification did make it into v3.0.3 can this be closed now? |
Yup! |
I see this issue is closed, but maybe I can still get clarification on the recommended approach to define in OpenAPI 3.0.x a data type where the set of allowed values consist on an enum (e.g. of type string) and also the Would this approach be ok, for example?
|
@jdegre, that would work. But this also works: NullableEnum:
type: string
nullable: true
enum:
- one
- two
- null The combination of NullableEnum:
type: [string, "null"]
enum:
- one
- two
- null |
thanks a lot for the fast reply @tedepstein! |
For posterity, we had an issue using the python generator with this format:
But this one worked fine:
|
@tedepstein was https://github.com/OAI/OpenAPI-Specification/blob/master/proposals/003_Clarify-Nullable.md approved? |
Has anyone given any thought to such constructs as:
|
@richardwhiuk my interpretation of your spec per v3.0.3 is that nullable false has no impact on types. Type null is allowed as oneof the any types and that all three enum values should be accepted |
@richardklose During the lead-up to 3.0.3 and 3.1.0, we had a lot of discussion over the problems introduced if
So |
The example I gave has null in the enum, but nullable false? |
@richardwhiuk if you want to forbid |
Thanks for the reminder. I have opened PR #2529 to update the proposal as you've suggested.
This excerpt from the proposal may help to clarify why your schema permits
|
Boy the wording here is especially confusing and overly verbose. Can you just show with code what is allowed and not allowed.
What value? The type that contains the union of enum and null, or a null type constructor in an enum? IE, how do we model
And
What would the
|
The value of the
|
@EvanCarroll you need to add the null value into the enum options. |
Thanks a ton! That's far clearer than the RFC and conversation. |
@spacether as a side note. What is the rule of |
I don't think you're seeing the confusion here.. The term "value" there in the context of a type system is remarkably confusing.
What's the value in the above? The right answer, afaik, is there is no value. There is a type. That type has two value constructors A, and B, and Null. Values would like this:
We can also model this,
} Again there is no value there. So now we have two possible interpretations of So I need to know which of these the "nullable: True` is enabling. Is it,
Thus far @spacether's answer clearly tells me that it's not doing 1, and I have to do that. And because that's not how I'd prefer to model this, I presume 2 isn't an option. So the question then is what does |
@EvanCarroll you realize OAS is not a C++ code generation specification, right? Anything about mapping OAS to C++ code is going to be specific to your tooling. OAS says what will and won't validate as a JSON/YAML/etc. instance. That doesn't always map cleanly to every programming language, and it's up to code generators to decide what to do with those scenarios.
|
@EvanCarroll , I think you will find it easier to understand if you keep in mind that OpenAPI is entirely declarative. There are no constructors or other imperative statements.
In all of these declarative languages, maps, consisting of key-value pairs, are ubiquitous. And in that context, all of those language specs use the term "value" extensively to refer to the value in a key-value pair. These technologies are the world we live in. This is the context for most of these discussions.
|
Hey,
I am hoping to get clarification on the following:
When the nullable and enum keywords are used together, which takes precedence?
i.e.
When
propertyA
is validated against the definition. Should the result be:nullable
null
is not part of theenum
The text was updated successfully, but these errors were encountered: