OpenAPI: How to mark a schema field as required

Suppose you have a POST /v1/clients endpoint that requires a JSON payload where the firstName and lastName fields are required, but email is not. You can describe this with the following OpenAPI schema:

openapi: 3.0.3
info:
  title: Client API - OpenAPI 3.0
  description: |-
    This is a sample API based on the OpenAPI 3.0 specification.
  termsOfService: http://swagger.io/terms/
  contact:
    email: apiteam@swagger.io
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.11
servers:
  - url: https://petstore3.swagger.io/api/v3
tags:
  - name: client
    description: Client operations
paths:
  /clients:
    post:
      summary: Create a new client
      tags:
        - client
      requestBody:
        description: "The new client"
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                firstName:
                  type: string
                lastName:
                  type: string
                email:
                  type: string
              required:
                - firstName
                - lastName
      responses:
        201:
          description: Client resource created
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
  
                

Now, if you use a tool like Swagger UI, you’ll see that firstName and lastName fields are marked as required, but not email.

You can paste the above YAML here to see the generated SwaggerUI docs.