What does ‘required’ in OpenAPI really mean

by

The required keyword in OpenAPI Schema Objects is taken from JSON Schema and means:

An object instance is valid against this keyword if every item in the [required] array is the name of a property in the instance.

In other words, required means “property must be present”, regardless of its value. The type, format, etc. of the property value are separate constraints that are evaluated separately from required, but together as a combined schema.

In your example:

  1. {"id": ""} is valid:

    • ✓ validates against required
    • ✓ the value "" validates against type: string

  2. {"id": null} is NOT valid:

    • ✓ validates against required
    • ✗ null does NOT validate against type: string (see the notes about nulls below)

  3. {} is NOT valid:

    • ✗ does NOT validate against required

Note that 'null' as a type is not supported in OpenAPI 2.0 but is supported in OpenAPI 3.1, and 3.0 has nullable to handle nulls. So, {"id": null} is valid against this OpenAPI 3 schema:

Person:
  required:
    - id
  type: object
  properties:
    id:
      # OAS 3.1
      type: [string, 'null']

      # OAS 3.0
      # type: string
      # nullable: true

Leave a Comment