Required and Default

Hi all, i need a clarification about using Required and Default properties.

Consider this definition took from OpenAPI specs “Models with Polymorphism Support” example:

type: object
properties:
  huntingSkill:
    type: string
    description: The measured skill for hunting
    default: lazy
    enum:
      - clueless
      - lazy
      - adventurous
      - aggressive
required:
  - huntingSkill

If huntingSkill property required, i’m expected to provide a value or get a validation error, so default property is useless. Otherwise, if is supposed to use default value if not provided, it’s required property to be useless.

Can you help clarify?

Thank you!

[handrews]

@hkosova default and required together is definitely odd. I was pointing out that potential use case because it’s come up in the JSON Schema spec repo. I doubt it’s common.

Modern JSON Schema has both examples (note the plural) and default. They have distinct purposes, although implementations MAY treat the default as an additional example (or as the only example if examples is not present).

examples is “here are some things you can do, some of which may be unusual which is why they are being called out” default is generally “here is the thing that happens if you don’t do anything”

All annotation keywords (including default and examples) simply provide information to applications without mandating whether or how it must be used. This is why the initial UI form value use case is valid- it’s basically an indirect form of writing it into the instance.

[oralokan]

A quick wrap-up.

I have come to agree with the OpenAPI documentation that states that required and default do not make sense together. required states that the data submitted by the user must include the property, otherwise it is invalid. So for valid data, the default value will never be used. If the default value was to be applied prior to validation, well in that case the user was not really required to include the property in the first place.

The main reason I wanted to use required and default together was due to code generation (in my case, generating TypeScript types). Setting required ensures that the property is a required property of the generated type.

However, being required in use submitted data and being required in the generated type are two separate things.

Specifically, if the JSON schema includes a default value, then deserialized objects will always include a value for that property: either the user-submitted value or the default value.

As such, I think the correct solution is to ensure that the generated type includes the property as a required property either if it is marked as required in the JSON Schema, or it has a default value.

Basically, this has to be implemented in the code-generation library.

Having said that, it would be great if OpenAPI specifies how code-generation should work so that we can have compliant code-generation libraries.