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?

Pinochle

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. – Libb

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 – Pinochle

Answer 1

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.

Paraffinic

Coming in later to point out that in OAS 3.0.3 you can use nullable: true and it will allow you to set type: 'null', which should allow type: [string, 'null'] to work as well. spec.openapis.org/oas/v3.0.3#fixed-fields-19 – Cissie

@Cissie No, type: 'null' is not a valid keyword in OpenAPI 3.0.x. – Paraffinic

Answer 2

I was able to do it with the following syntax:

fieldName:
      title: Field name
      default: null
      oneOf:
        - type: string
        - type: "null"

Coauthor

Your answer could be improved with additional supporting information. Please edit to add further details, such as citations or documentation, so that others can confirm that your answer is correct. You can find more information on how to write good answers in the help center. – Patois

It could only be improved if the documentation or citation exists, which I believe it doesn't. It was the only place I was able to find it. A good answer is one that works, and this one does work! Only additional comment is that, as per the tests I performed, the default: null line is not needed. Thanks for sharing @Angelo Milazzo. – Serotherapy