zod由来のnullable JSON Schemaはtype配列になり、外部のスキーマ検査器に「型未指定」と誤認識される
TypeScript
MCP
JSON Schema
知識
運用
zodの.nullable()をzod-to-json-schema等でJSON Schemaに変換すると、多くの実装は{"type": ["string", "null"]}のような、JSON Schema仕様上は正当な「typeを文字列配列で指定する」形式を出力する。この形式は仕様上は合法だが、外部のツール(LLMプラットフォームのスキーマ自動レビューや一部のJSON Schemaバリデーターなど)がtypeに単一の文字列しか想定していない場合、このフィールドを「型情報がない(任意の型)」と誤認識し、自動レビューで指摘されることがある。
判断基準
- 日付・タイムスタンプなど、形式制約を伴う文字列フィールドは、zodの形式付き文字列バリデータ(日付のみ、日時など)を使うと、変換後のJSON Schemaに
formatキーワードが付与され、かつnullableとの組み合わせでanyOf形式({"anyOf": [{"type": "string", "format": "..."}, {"type": "null"}]})に自動的に変わることがある。単なる文字列制約なしのnullableフィールド(形式制約のない文字列や数値など)はtype配列のままになりやすい。 - この問題を固定的に回避したい場合は、生成後のJSON Schemaを再帰的に走査し、
typeプロパティが配列であればanyOf形式に正規化する後処理を入れると、個々のフィールドごとに形式制約を付与しなくても一括で対応できる。
検証方法
実際にツールが公開するJSON Schema(ランタイムで生成された完全な形を、単体テストではなく実際の登録パス経由で)を取得し、nullableなフィールドのtypeが配列ではなくanyOfや単一の文字列になっているかを確認する。