What "required" in OpenAPI really means

Question

What "required" in OpenAPI really means

Given the following OpenAPI definition, which of the below objects are valid. Just 1. or 1. and 2 ..

Person:
  required:
    - id
  type: object
  properties:
    id:
      type: string

{"id": ""}
{"id": null}
{}

It boils down to the question of whether "required = true" means "nonzero value" or "property must be present".

The JSON schema validator at https://json-schema-validator.herokuapp.com/ says 2. is invalid because it null

does not satisfy the constraint.Note type: string

that it does not complain because it id

is null, but because null

it is not a string ... BUT, how important is this for OpenAPI / Swagger?

+2

swagger openapi

Marcel Stör 08 Aug 17 at 18:24

source to share

2 answers

OpenAPI favors JSON Schema in these matters and from what I can tell in JSON Schema null is a valid string.

It should be noted that the null character (\ u0000) is valid in a JSON string.

My reading of the definition required is that having a property implies validity.

Update: I seem to be wrong. It seems that JSON Schema does not consider the value null

to be equivalent to \ u0000. This would mean that null is not a valid string value.

+1

Darrel miller 08 Aug 17 at 20:26

source to share

Helen · Accepted Answer · 2017-08-08T20:47:02+0000

Keyword required

in OpenAPI has the same meaning as in JSON Schema :

required

An object instance is valid against this keyword if its property set contains all the elements in this key array.

The wording in the latest JSON Schema specification (although not the one used by OpenAPI) is clearer:

An instance of an object is valid against this keyword if each element of the array is the name of a property in the instance .

That is, it required

means that "the property must be present", regardless of the value. Values type

, format

etc. Property values are separate constraints that are evaluated separately from required

, but together as a combined schema.

In your example:

{"id": ""}

:
- ✓ checks for required
- ✓ the value is ""
  
  checked fortype: string
{"id": null}

IMPOSSIBLE:
- ✓ checks for required
- ✗ null
  
  DOES NOT check compliancetype: string
{}

IMPOSSIBLE:
- ✗ DOES NOT check compliance required

Note that null

as the type is not supported in OpenAPI, OpenAPI 3.0 adds an attribute nullable

to indicate what the value can be null

. So {"id": null}

this OpenAPI 3.0 schema will check:

Person:
  required:
    - id
  type: object
  properties:
    id:
      type: string
      nullable: true   # <----

What "required" in OpenAPI really means

More articles: