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

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?

Solution

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.