How to declare nullable property in OpenAPI 3.0.x that's compatible with AWS API Gateway

Question

We have been using OpenAPI 3.0.x specification, which adds feature for declaring nullable properties.

When I import this OpenAPI into AWS API Gateway, corresponding model does not honor this nullable setting.

Is there any way how to declare nullable property in OpenAPI 3.0.x so AWS API gateway recognises and configures underlying model with this setting as well?

Example OpenAPI specification

openapi: "3.0.2"
info:
  title: Test
  description: |
    API
  version: "0.1.0"
  license:
    name: Private
    url: https://fillme.one/license
servers:
  - url: /api/v1
paths:
  /accounts:
    post:
      operationId: repa
      responses:
        200:
          description: test
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                date:
                  type: string
                  format: date-time
                  nullable: true
              required:
                - date

Resulting JSON schema document for generated model

{
  "required" : [ "date" ],
  "type" : "object",
  "properties" : {
    "date" : {
      "type" : "string",
      "format" : "date-time"
    }
  }
}

Clearly, type should be union of ["string", null] but AWS API Gateway ignores OpenAPI specification.

Any help?

You might want to try `"type": ["string", "null"]` in your openapi document. Otherwise, this is probably a bug that should be filed with your implementation. — Ether, Mar 28 '22 at 17:56
This does not work. I have no means to specify type union in OpenAPI 3.0.x, because it supports `nullable` property. The JSON schema is generated by AWS API GW from OpenAPI so I would have to post-process it manually, which is undesired — Martin Macak, Mar 29 '22 at 05:35

score 6 · Accepted Answer · answered Mar 29 '22 at 14:27

AWS API Gateway expects models in the JSON Schema format rather than OpenAPI Schema format. Here's the relevant note from the documentation (emphasis mine):

API Gateway supports most of the OpenAPI 2.0 specification and the OpenAPI 3.0 specification, with the following exceptions:

...

API Gateway models are defined using JSON schema draft 4, instead of the JSON schema used by OpenAPI.

This means that AWS API Gateway expects type: [string, 'null'] instead of type: string + nullable: true.

However, type: [string, 'null'] is not valid syntax in OpenAPI 3.0 (it's valid in OAS 3.1 though). What you can do is pre-process your existing OpenAPI file before importing it to AWS API Gateway and change the nullable type definitions to the format/syntax that AWS expects. You can try using tools such as openapi-schema-to-json-schema.

How to declare nullable property in OpenAPI 3.0.x that's compatible with AWS API Gateway

1 Answers1