OpenAPI 3.1の新機能とJSON Schemaとの整合
JSON Schema 2020-12の完全サポート、webhooksセクション、nullableの型配列への置き換え、constキーワード、if/then/elseスキーマを含むOpenAPI 3.1の3.0からの改善を探索。
Advanced Features
詳細な説明
OpenAPI 3.1の新機能
OpenAPI 3.1はJSON Schema 2020-12と仕様を整合させる重要なアップデートです。強力なスキーマ機能をもたらし、OpenAPIとJSON Schemaの関係を簡素化します。
JSON Schema完全互換
最大の変更：OpenAPI 3.1のスキーマは有効なJSON Schema 2020-12です：
# OpenAPI 3.0（カスタムnullable）
name:
type: string
nullable: true
# OpenAPI 3.1（JSON Schema標準）
name:
type: [string, "null"]
型配列
nullable を型配列で置き換え：
# 3.1
age:
type: [integer, "null"]
# 複数の型
value:
type: [string, integer]
constキーワード
enumなしの固定値：
# 3.1
type:
const: user
Webhooksセクション
Webhook定義のための新しいトップレベルセクション。
条件付きスキーマ（if/then/else）
Address:
type: object
if:
properties:
country:
const: US
then:
required: [state]
else:
required: [province]
3.0からの移行
主な変更点：
openapi: "3.0.x"をopenapi: "3.1.0"に変更nullable: trueをtype: [original_type, "null"]に置き換え- 単一値の
enumをconstに置き換え - Webhookコールバックを新しい
webhooksセクションに移動 - 必要に応じて
$refの兄弟キーワードを追加
ユースケース
OpenAPI 3.0から3.1にアップグレードするチームは、JSON Schemaの完全互換性の恩恵を受け、変換なしでバリデーション、ドキュメント、コード生成間でスキーマの再利用が可能になります。webhooksセクションはイベント駆動アーキテクチャにとって重要であり、条件付きスキーマ（if/then/else）は3.0では不可能だった複雑なビジネスルールのドキュメント化を可能にします。