Errors on OpenAPI 3.1 type: [string, null] schemas

[efe]

Hello Mintlify, 👋

We’re seeing local dev server errors when rendering API reference pages generated from an OpenAPI 3.1 spec that uses JSON Schema–style nullable union types (e.g. type: [string, "null"]). The pages still render correctly, but the Mintlify local server logs repeated schema conversion errors.

Environment

• Mintlify local dev server (via npm start)
• OpenAPI spec version: 3.1
• Platform: Local docs dev server (localhost)

Steps to reproduce

1. Run the local dev server:

npm start dev

2. Navigate to any Shipments API v3 endpoint page, e.g.: http://localhost:3000/api/v3/shipments/retrieve-shipments

3 Observe console output in the Mintlify local server logs.

Actual behavior

Mintlify logs errors like:

#/paths/\/shipments/announce-with-shipping-rules/post/responses/201/content/application\/json/schema/properties/data/properties/parcels/items/properties/parcel_items/items/properties/mid_code
error converting property schema Error [InvalidSchemaError]: ...
invalid schema type: string,null
#/paths/\/shipments/announce-with-shipping-rules/post/responses/201/content/application\/json/schema/properties/data/properties/parcels/items/properties/parcel_items/items/properties/material_content
error converting property schema Error [InvalidSchemaError]: ...
invalid schema type: string,null
#/paths/\/shipments/announce-with-shipping-rules/post/responses/201/content/application\/json/schema/properties/data/properties/parcels/items/properties/parcel_items/items/properties/intended_use
error converting property schema Error [InvalidSchemaError]: ...
invalid schema type: string,null

Despite these errors, the properties still appear to render correctly in the docs UI.

Expected behavior

Mintlify should accept OpenAPI 3.1 / JSON Schema union types such as:

type:
  - string
  - "null"

…without logging schema conversion errors.

Workaround

If we downgrade the nullable syntax to the OpenAPI 3.0 style, the errors disappear:

 description:
-  type:
-    - string
-    - 'null'
+  type: string
+  nullable: true
  example: Order n

However, this is not ideal because our spec is OpenAPI 3.1 and nullable: true is a legacy OpenAPI 3.0 construct.

Additional notes

This appears to be a compatibility issue in Mintlify’s schema conversion layer, which likely assumes type is always a string rather than allowing an array (valid in JSON Schema / OAS 3.1).

If you’d like, we can provide a minimal repro OpenAPI document containing one endpoint and a schema with type: [string, "null"].