OpenAPI 3.1

2021年2月にリリースされたOpenAPI仕様のマイナーバージョン。中心的な目的はJSON Schemaとの完全互換性の実現で、公式ブログでも「OpenAPIのJSON Schema関連構造とJSON Schema自体のズレは長年、利用者・実装者双方にとっての課題だった」と説明されている。

JSON Schema Draft 2020-12への完全準拠

3.0のSchema ObjectはJSON Schema Draft 5の「サブセット」でしかなく、完全互換ではなかった。3.1ではSchema ObjectがJSON Schema Draft 2020-12ボキャブラリーに100%準拠するようになった。あわせてトップレベルフィールドjsonSchemaDialectが新設され、文書内のSchema Objectが従うデフォルトの$schema値を宣言できるようになった。

semverからの意図的な逸脱

OAS Technical Steering Committee (TSC) は、JSON Schema 2020-12との整合とOpenAPI 3.0からの学びの反映を優先し、破壊的変更を意図的にマイナーバージョン(3.0→3.1)へ含めるという判断を下した。つまり3.1は「マイナーバージョンは後方互換であるべき」というセマンティックバージョニングの慣習から意図的に逸脱している。

主な変更点

  • webhooks — トップレベルフィールドとして新設。帯域外(out-of-band)で登録されるWebhookをOpenAPI Object内で正式に記述できるようになった。3.0にはネイティブな手段がなく、callbacksの転用や仕様外での文書化で代替していた
  • nullable廃止 — 3.0.3の独自拡張だったnullableキーワードが廃止され、JSON Schema標準のunion型表現に統一された
  • $refと兄弟キーワードの共存 — 3.0.3では$refがdescriptionやexampleなど兄弟キーワードと共存できなかったが、JSON Schemaの挙動に合わせてこの制約が撤廃された
  • examples(複数形) — OpenAPI独自の単数形exampleキーワードに加え、JSON Schema標準の複数形examplesキーワードが使えるようになった
  • 再利用可能なPath Items — Components ObjectにpathItemsが追加され、Path Item Objectをコンポーネントとして再利用できるようになった
  • ライセンスのSPDX識別子表記 — APIライセンスをSPDX識別子で表記可能に

採用状況

Atlassian・Microsoft・Googleなど大手が採用。Swagger UI/Editorも3.1をサポートしている。

OpenAPIの中での位置づけ

OpenAPIのバージョン変遷における一段階。次のメジャーバージョンに向けた検討はOpenAPI Moonwalkを参照。

#openapi #json-schema

出典

🔗 リンクされているノート

作成日時: 2026-08-15 16:22 / 更新日時: 2026-08-15 16:22