Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

What does 'required' in OpenAPI really mean

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 
  1. {"id": ""}
  2. {"id": null}
  3. {}

This boils down to the question whether "required = true" means "non-null value" or "property must be present".

The JSON schema validator at https://json-schema-validator.herokuapp.com/ says that 2. be invalid because null doesn't satisfy the type: string constraint. Note that it doesn't complain because id is null but because null is not a string. BUT how relevant is this for OpenAPI/Swagger?

like image 778
Marcel Stör Avatar asked Aug 08 '17 18:08

Marcel Stör


People also ask

What is the purpose of the OpenAPI Specification?

The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to HTTP APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection.

What are OpenAPI definitions?

An open API, also called public API, is an application programming interface made publicly available to software developers. Open APIs are published on the internet and shared freely, allowing the owner of a network-accessible service to give a universal access to consumers.

What is the OpenAPI Specification format?

OpenAPI Specification (formerly Swagger Specification) is an API description format for REST APIs. An OpenAPI file allows you to describe your entire API, including: Available endpoints ( /users ) and operations on each endpoint ( GET /users , POST /users ) Operation parameters Input and output for each operation.

What is the difference between Swagger and OpenAPI?

Although the terms once referred to the same thing, they can no longer be used interchangeably…even though some people still do. In 2021, OpenAPI refers to the industry-standard specification for RESTful API design. Swagger refers to a set of SmartBear tools.


1 Answers

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 
like image 133
Helen Avatar answered Sep 23 '22 18:09

Helen