OpenAPI 仕様

バージョン 3.1.1

このドキュメントにおけるキーワード「MUST」、「MUST NOT」、「REQUIRED」、「SHALL」、「SHALL NOT」、「SHOULD」、「SHOULD NOT」、「RECOMMENDED」、「NOT RECOMMENDED」、「MAY」、「OPTIONAL」は、BCP 14 RFC2119 RFC8174 に記述されている通りに、かつここに示されているようにすべて大文字で表記されている場合にのみ解釈されます。

このドキュメントはApache License, Version 2.0の下でライセンスされています。

はじめに

OpenAPI Specification (OAS) は、HTTP API に対する標準的で言語に依存しないインターフェースを定義しており、人間とコンピューターの両方が、ソースコード、ドキュメントへのアクセス、またはネットワークトラフィックの検査なしに、サービスの機能を検出して理解することを可能にします。適切に定義されていれば、コンシューマーは最小限の実装ロジックでリモートサービスを理解し、操作することができます。

OpenAPI Description は、ドキュメント生成ツールで API を表示したり、コード生成ツールでさまざまなプログラミング言語のサーバーやクライアントを生成したり、テストツールなど、多くのユースケースで使用できます。

OpenAPI の使用例と追加ドキュメントについては、[[?OpenAPI-Learn]] を参照してください。

OpenAPI Initiative が公開している拡張レジストリやその他の仕様、およびこの仕様の公式なレンダリングについては、spec.openapis.org を参照してください。

定義

OpenAPI Description

OpenAPI Description (OAD) は、API の表面とそのセマンティクスを正式に記述します。これは、OpenAPI Document である必要のあるエントリドキュメントと、その参照されるすべてのドキュメントで構成されます。OAD は OpenAPI Specification を使用し、これに準拠しており、少なくとも 1 つのpathsフィールド、componentsフィールド、またはwebhooksフィールドを含まなければなりません。

OpenAPI ドキュメント

OpenAPI ドキュメントは、OpenAPI 仕様に準拠する単一の JSON または YAML ドキュメントです。OAS 3.*.* と互換性のある OpenAPI ドキュメントには、使用する OAS のバージョンを指定する必須のopenapiフィールドが含まれています。

スキーマ

「スキーマ」とは、構文と構造の形式的な記述です。このドキュメントは、OpenAPI 仕様形式のスキーマとして機能します。このドキュメントに基づく非公式な JSON Schema も、情報提供の目的でspec.openapis.orgで提供されています。この仕様は、スキーマオブジェクトの形式でスキーマを使用もしています。

オブジェクト

大文字で表記された「Object」という単語は、このドキュメントのセクション見出しで名付けられているオブジェクトのいずれかを指します。

パスのテンプレート化

パスのテンプレート化とは、波括弧 ({}) で区切られたテンプレート式を使用して、URL パスのセクションをパスパラメーターで置き換え可能としてマークすることを指します。

パス内の各テンプレート式は、パス項目自体、および/またはパス項目の各オペレーションに含まれるパスパラメーターに対応しなければなりません。例外として、パス項目が空の場合（ACL 制限などによる）、対応するパスパラメーターは不要です。

これらのパスパラメーターの値には、RFC3986で説明されているエスケープされていない「汎用構文」文字（スラッシュ (/)、疑問符 (?)、ハッシュ (#)）を含んではなりません。

メディアタイプ

メディアタイプ定義は複数のリソースにまたがっています。メディアタイプ定義はRFC6838に準拠すべきです。

可能なメディアタイプの定義の例いくつか

  text/plain; charset=utf-8
  application/json
  application/vnd.github+json
  application/vnd.github.v3+json
  application/vnd.github.v3.raw+json
  application/vnd.github.v3.text+json
  application/vnd.github.v3.html+json
  application/vnd.github.v3.full+json
  application/vnd.github.v3.diff
  application/vnd.github.v3.patch

HTTP ステータスコード

HTTP ステータスコードは、実行された操作のステータスを示すために使用されます。ステータスコードは、IANA ステータスコードレジストリに登録されている利用可能なステータスコードの中から選択されるべきです。

大文字・小文字の区別

OpenAPI 仕様のほとんどのフィールド名と値は大文字と小文字を区別するため、このドキュメントでは大文字と小文字を区別しない名前と値を明示的に示そうと努めています。ただし、HTTP の概念に直接マッピングされるフィールド名と値の大文字・小文字の区別は、このドキュメントで各概念について言及していなくても、HTTP の大文字・小文字の区別のルールに従います。

未定義および実装依存の動作

この仕様は、特定の状況を「未定義」または「実装依存」の動作と見なします。

「未定義」と記述された動作は、少なくとも一部の状況では、仕様と矛盾する結果をもたらす可能性があります。この記述は、矛盾の検出が不可能または非現実的な場合に使用されます。実装は、以前のバージョンの仕様における曖昧なテキストを含む、歴史的な理由から未定義のシナリオをサポートする場合があります。このサポートは多くの場合に正しい結果をもたらすかもしれませんが、すべてのツールや将来の仕様バージョンで機能するという保証がないため、これに依存することは**推奨されません**。たとえそれらのバージョンが本仕様と厳密に互換性がある場合でもです。

「実装定義」と記述された動作は、実装が要件に対するいくつかの異なるが準拠するアプローチのうちどれを実装するかを選択することを許可します。このドキュメントは、相互運用性を最大化するためにAPI記述の作成者が避けることを**推奨**する曖昧な要件を扱っています。未定義の動作とは異なり、関連するすべてのツールが同じ動作をサポートすることが保証できる場合に**のみ**、実装定義の動作に依存することは安全です。

仕様

バージョン

OpenAPI Specification は、major.minor.patch のバージョン管理スキームを使用しています。バージョン文字列の major.minor 部分（例：3.1）は、OAS の機能セットを指定します。.patch バージョンは、機能セットではなく、このドキュメントのエラーに対処するか、明確化を提供します。OAS 3.1 をサポートするツールは、すべての OAS 3.1.* バージョンと互換性があるべきです。パッチバージョンはツールによって考慮されるべきではなく、例えば 3.1.0 と 3.1.1 の間に区別を設けるべきではありません。

場合によっては、提供されるメリットに比べて影響が低いと考えられる場合、OAS のminorバージョンで後方互換性のない変更が行われることがあります。

フォーマット

OpenAPI 仕様に準拠する OpenAPI ドキュメント自体は JSON オブジェクトであり、JSON または YAML 形式で表現できます。

例えば、フィールドが配列値を持つ場合、JSON 配列表現が使用されます。

{
  "field": [1, 2, 3]
}

仕様内のすべてのフィールド名は**大文字と小文字を区別します**。これには、キーが**大文字と小文字を区別しない**と明示的に記載されている場合を除き、マップのキーとして使用されるすべてのフィールドが含まれます。

スキーマは、宣言された名前を持つ*固定フィールド*と、フィールド名に宣言されたパターンを持つ*パターン化されたフィールド*の2種類のフィールドを公開します。

パターンフィールドは、包含オブジェクト内で一意の名前を持つ必要があります。

YAMLとJSON形式間でのラウンドトリップ能力を維持するため、YAMLバージョン1.2にいくつかの追加の制約を加えることが推奨されます。

• タグは、YAMLのJSONスキーマルールセットで許可されているものに限定されなければなりません。これはYAML構文のサブセットを定義しており、[[JSON-Schema-2020-12|JSON Schema]]とは関係ありません。
• YAMLマップで使用されるキーは、YAML Failsafeスキーマルールセットで定義されているように、スカラ文字列に限定されなければなりません。

注: API は YAML または JSON 形式の OpenAPI Description で記述できますが、API リクエストとレスポンスのボディおよびその他のコンテンツは JSON または YAML である必要はありません。

OpenAPI Description の構造

OpenAPI Description (OAD) は、単一の JSON または YAML ドキュメントで構成される場合もあれば、作成者の裁量で複数の接続された部分に分割される場合もあります。後者の場合、参照オブジェクト、パスアイテムオブジェクト、およびスキーマオブジェクトの$refフィールド、ならびにリンクオブジェクトのoperationRefフィールド、および識別子オブジェクトのmappingフィールドのURI形式が、参照される要素を特定するために使用されます。

マルチドキュメント OAD において、解析が開始される OpenAPI Object を含むドキュメントは、その OAD の**エントリドキュメント**として知られています。

OAD のエントリドキュメントには、openapi.json または openapi.yaml という名前を付けることが推奨されます。

ドキュメントの解析

スキーマオブジェクトを適切に処理するために、OAS 3.1 は、URIにおける相対参照で指定されているように、基本 URI に関する適切な変更を加えて、JSON スキーマ仕様ドラフト 2020-12の解析要件を継承します。

これには、参照ターゲットを提供したり、適切な基本URIの決定に影響を与えたりするキーワードを検出するために、Schema Object 参照が解決不可能と見なされる前に完全なドキュメントを解析するという要件が含まれます。

実装は、以下のいずれかの方法で完全なドキュメントの解析をサポートしてもよい

• メディアタイプを用いたOpenAPIまたはJSONスキーマドキュメントの検出
• ルートのopenapiフィールドによるOpenAPIドキュメントの検出
• キーワードの検出、またはJSONスキーマ仕様に従ってドキュメントを正常に解析することによるJSONスキーマドキュメントの検出
• 参照の期待される型に基づいて、ルートに参照可能なオブジェクトを含むドキュメントを検出する
• ユーザーがルート以外のオブジェクトへの参照によってロードされる可能性のあるドキュメントのタイプを設定できるようにする

残りのコンテナドキュメントの内容を考慮せずにOpenAPIコンテンツの参照されたフラグメントを解析する実装は、参照ターゲットの意味と動作を変更するキーワードを見逃すでしょう。特に、基本URIを変更するキーワードを考慮しないことは、参照が意図しないURIに解決され、予測不能な結果をもたらすことでセキュリティリスクを導入します。一部の実装は、本仕様の過去のバージョンの要件により、この種の解析をサポートしていますが、バージョン3.1では、フラグメントを単独で解析した結果は未定義であり、本仕様の要件と矛盾する可能性が高いです。

特定の OpenAPI Description を構成して、参照が分離されたフラグメントとして解析されたときに正しく動作するようにすることは可能ですが、これに依存することは推奨されません。この仕様は、そのような動作が安全である条件を明示的に列挙しておらず、OAS の将来のバージョンにおいて継続的な安全性を保証するものでもありません。

OAS コンテンツのフラグメントを解析する特殊なケースは、そのようなフラグメントが別の形式に埋め込まれている場合で、OAS に関しては「埋め込み形式」と呼ばれます。OAS 自体は、Schema Object として埋め込まれる JSON Schema に関しては埋め込み形式であることに注意してください。埋め込みコンテンツの解析方法を定義するのは埋め込み形式の責任であり、埋め込み形式のサポートを文書化していない OAS 実装は、埋め込み OAS コンテンツを正しく解析することを期待できません。

構造的な相互運用性

OAD内のJSONまたはYAMLオブジェクトは、そのコンテキストに基づいて特定のオブジェクト（Operation Objects、Response Objects、Reference Objectsなど）として解釈されます。参照の配置方法によっては、特定のJSONまたはYAMLオブジェクトが複数の異なるコンテキストで解釈される可能性があります。

• エントリドキュメントのルートオブジェクトとして、常にOpenAPI Objectとして解釈されます。
• ドキュメント内の親オブジェクトによって示されるオブジェクトタイプとして
• 参照ターゲットとして、オブジェクト型が参照元のコンテキストと一致する

もし同じ JSON/YAML オブジェクトが複数回パースされ、それぞれのコンテキストがそれを*異なる*オブジェクト型としてパースすることを要求する場合、結果の動作は*実装定義*であり、検出された場合はエラーとして扱われる**可能性**があります。例えば、Path Item Object が期待される#/components/schemasの下で空の Schema Object を参照する場合、空のオブジェクトは両方の型で有効であるため、このようになる可能性があります。相互運用性を最大限に高めるため、OpenAPI Description の作成者はこのようなシナリオを避けることを**推奨**します。

暗黙の接続の解決

この仕様のいくつかの機能は、OpenAPI Description (OAD) の他の部分への非 URI ベースの接続の解決を必要とします。

これらの接続は、単一ドキュメント OAD では明確に解決されますが、マルチドキュメント OAD における解決プロセスは、このセクションで説明されている制約の範囲内で、実装依存です。場合によっては、明確な URI ベースの代替手段が利用可能であり、OAD 作者は常にその代替手段を使用することを推奨します。

ソース	ターゲット	代替
セキュリティ要件オブジェクト {name}	コンポーネントオブジェクト配下のセキュリティスキームオブジェクト名	該当なし
Discriminator Object mapping (暗黙的、または明示的な名前構文)	コンポーネントオブジェクトの下のスキーマオブジェクト名	mapping (明示的な URI 構文)
操作オブジェクト tags	OpenAPI Objectのtags配列内のTag Object name	該当なし
リンクオブジェクト operationId	パス項目オブジェクト operationId	operationRef

5番目の暗黙的な接続には、パスオブジェクトのテンプレート化されたURLパスを、適切なサーバーオブジェクトのurlフィールドに追加することが含まれます。これは、エントリドキュメントのパスオブジェクトのみが記述されたAPIにURLを提供するため、曖昧さはありません。

あらゆる Link Object の operationId を解決する際には、解析されたすべてのドキュメントの Operation Object をすべて考慮することが推奨されます。これには、operationId が解決不能と判断される前に、参照されているすべてのドキュメントを解析する必要があります。

Security Requirement Object および Discriminator Object における暗黙的な接続は、コンポーネント名に依存します。コンポーネント名とは、Components Object の適切な型付けされたサブオブジェクト内にコンポーネントを保持するプロパティの名前です。たとえば、#/components/schemas/Foo にある Schema Object のコンポーネント名は Foo です。Operation Object 内の tags の暗黙的な接続は、Tag Object の name フィールドを使用します。Tag Object は (Components Object と同様に) ルートの OpenAPI Object の下にあります。これは、コンポーネント名とタグ名の解決の両方が、正しい OpenAPI Object から開始することに依存することを意味します。

参照された (エントリではない) ドキュメントからコンポーネント名とタグ名を解決する際は、現在のドキュメントからではなく、エントリドキュメントから解決することをツールが推奨します。これにより、Security Scheme Object と Tag Object を API のデプロイ情報 (Server Object のトップレベル配列) の隣に定義し、参照されたドキュメントがアクセスするためのインターフェースとして扱うことができます。

インターフェースのアプローチは、Discriminator Object と Schema Object にも適用できますが、mapping の相対 URI 参照構文を使用して、Discriminator Object の動作を単一ドキュメント内に維持することも可能です。

Security Requirement Object や Operation Object の tags フィールドには、URI ベースの代替手段はありません。これらの制限は、将来のリリースで対処される予定です。

考えられる解決策の例（このセクションで推奨されるものを含む）については、付録F：参照ドキュメントにおけるセキュリティ要件の解決を参照してください。Discriminator Object の非 URI マッピングおよび Operation Object の tags フィールドの動作は、同じ原則に基づいています。

暗黙的な接続解決のいかなる側面も、URI の解決方法や、その可能なターゲットを制限するものではないことに注意してください。

データ型

OASにおけるデータ型は、JSON Schema Validation Specification Draft 2020-12で定義されている型「null」、「boolean」、「object」、「array」、「number」、「string」、「integer」に基づいています。モデルは、JSON Schema Specification Draft 2020-12 のスーパーセットであるSchema Objectを使用して定義されます。

JSON Schema のキーワードと format 値は、JSON の6つのデータ型（「null」、「boolean」、「object」、「array」、「number」、「string」）のいずれかである JSON 「インスタンス」に対して動作し、特定のキーワードとフォーマットは特定の型にのみ適用されます。例えば、pattern キーワードと date-time フォーマットは文字列にのみ適用され、他の5つの型のインスタンスは*自動的に有効*とみなされます。これは、JSON Schema のキーワードとフォーマットが**暗黙的に**期待される型を要求するわけでは**ない**ことを意味します。型を明示的に制限するには、type キーワードを使用してください。

type キーワードは便宜上 "integer" を値として許可しますが、キーワードとフォーマットの適用性においては、JSON 自体がその区別をしないため、整数が他の数値とは異なる JSON 型であるとは認識されないことに注意してください。個別の JSON 整数型がないため、JSON Schema は整数を数学的に定義します。これは、1 と 1.0 の両方が同等であり、両方とも整数とみなされることを意味します。

データ型の形式

JSON Schema Validation 仕様で定義されているように、データ型にはオプションの修飾子キーワード：format を持てます。その仕様で説明されているように、format はデフォルトでは非検証注釈として扱われます。format を検証する能力は実装によって異なります。

OpenAPI Initiative は、OAS ユーザーやその他の仕様によって定義された形式のための形式レジストリもホストしています。登録された形式のサポートは厳密に OPTIONAL であり、ある登録された形式のサポートが他の形式のサポートを意味するわけではありません。

formatキーワードを伴わない型は、JSON Schemaの型定義に従います。特定のformatを認識しないツールは、formatが指定されていないかのように、単にtypeにフォールバックしても構いません。JSON Schema検証の目的のために、各フォーマットはそれが適用されるJSONデータ型のセットを指定すべきです。このレジストリでは、これらの型は「JSONデータ型」列に表示されます。

OASで定義されている形式は以下の通りです。

フォーマット	JSON データ型	コメント
int32	数	符号付き32ビット
int64	数	符号付き64ビット（別名 long）
浮動小数点数	数
ダブル	数
パスワード	文字列	値を不明瞭にするためのヒント。

データ型で述べたように、type: number と type: integer の両方がデータモデルにおいて数値とみなされます。

バイナリデータの操作

OAS は、*生の*バイナリデータと*エンコードされた*バイナリデータの両方を記述できます。

• 生バイナリは、エンコードされていないバイナリデータが許容される場合に使用されます。例えば、HTTP メッセージボディ全体としてバイナリペイロードを送信する場合や、バイナリ部分を許可する multipart/* ペイロードの一部として送信する場合などです。
• エンコードされたバイナリは、バイナリデータがapplication/jsonやapplication/x-www-form-urlencodedなどのテキストのみの形式（メッセージボディとして、またはURLクエリ文字列として）に埋め込まれる場合に使用されます。

バイナリデータ用のスキーマオブジェクトキーワードの使用方法を示す以下の表では、例としてimage/pngバイナリメディアタイプを使用しています。application/octet-streamを含む任意のバイナリメディアタイプは、バイナリコンテンツを示すのに十分です。

キーワード	生	エンコード済み	コメント
タイプ	省略	文字列	生バイナリはtypeの外です。
contentMediaType	image/png	image/png	冗長な場合は省略されることもあります（下記参照）。
contentEncoding	省略	base64 または base64url	その他のエンコーディングは許可されています

contentEncodingによって示されるエンコーディングは、データを7ビットASCIIテキストとして表現するためにデータのサイズを増大させますが、これはHTTPのContent-Encodingヘッダーとは無関係であることに注意してください。Content-Encodingヘッダーは、メッセージボディが圧縮されたかどうか、およびその方法を示し、このセクションで説明されているすべてのコンテンツシリアライゼーションの後で適用されます。HTTPはエンコードされていないバイナリメッセージボディを許可するため、メッセージボディ全体をbase64または類似のエンコーディングで示すための標準化されたHTTPヘッダーはありません。

base64urlのcontentEncodingを使用することで、URLエンコーディング（クエリ文字列およびapplication/x-www-form-urlencodedタイプのメッセージボディで必要とされる）が、すでにエンコードされたバイナリデータの一部をさらにエンコードする必要がなくなります。

メディアタイプが既に設定されている場合、contentMediaTypeキーワードは冗長です

• メディアタイプオブジェクトのキーとして
• エンコーディングオブジェクトのcontentTypeフィールド

スキーマオブジェクトが非 OAS 対応の JSON Schema 実装によって処理される場合、冗長であっても contentMediaType を含めることが役立つ場合があります。ただし、contentMediaType が関連する Media Type Object または Encoding Object と矛盾する場合、contentMediaType は無視される**べき**です。

ストリーミングペイロードの長さの予想される上限を設定するために、maxLengthキーワードを使用してもよい。このキーワードは、エンコードされたバイナリデータを含む文字列データ、またはエンコードされていないバイナリデータのいずれにも適用できる。エンコードされていないバイナリの場合、長さはオクテット数である。

OAS 3.0からのバイナリ記述の移行

以下の表は、OAS 3.0 のバイナリデータ記述から移行する方法を示しており、引き続きimage/pngをバイナリメディアタイプの例として使用しています。

OAS < 3.1	OAS 3.1	コメント
type: string format: binary	contentMediaType: image/png	冗長な場合は省略可能で、多くの場合、空のスキーマオブジェクトになる。
type: string フォーマット: バイト	type: string contentMediaType: image/png contentEncoding: base64	URLセーフにするためにbase64文字列を再エンコードしないように、base64urlを使用できることに注意してください。

リッチテキスト形式

仕様全体でdescriptionフィールドはCommonMarkマークダウン書式をサポートすると記されています。OpenAPIツールがリッチテキストをレンダリングする場合、CommonMark 0.27で記述されているマークダウン構文を最低限サポートしなければなりません。ツールはセキュリティ上の懸念に対処するため、一部のCommonMarkまたは拡張機能を無視することを選択しても構いません。

CommonMark 0.27 を最小要件と位置づけることは、ツールがその上に拡張機能を実装してもよいことを意味しますが、そのような拡張機能は定義上、実装依存であり、相互運用性がないことに注意してください。OpenAPI Description の作成者は、そのような拡張機能を使用したテキストが、最小限のサポートしか提供しないツールによってどのようにレンダリングされるかを考慮すべきです。

API Description URIにおける相対参照

OpenAPI Description 内での参照、または外部ドキュメントやライセンスなどの補足情報への参照として使用される URI は、識別子として解決され、この仕様では**URI** として記述されます。ドキュメントの解析で述べたように、この仕様は、ドキュメントの読み込みと、現在の場所と一致しない可能性がある予期される URI との関連付けに関する JSON Schema Specification Draft 2020-12 の要件を継承しています。この機能は、URI を変更することなく開発環境やテスト環境で作業するため、また、制限されたネットワーク構成やセキュリティポリシー内で作業するために使用されます。

一部の URI フィールドは歴史的な理由で url と命名されていますが、これらのフィールドの記述テキストでは正しい「URI」という用語が使用されていることに注意してください。

特に指定のない限り、URIであるすべてのフィールドはRFC3986で定義されている相対参照であってもよい。

スキーマオブジェクト内の相対参照（$id値として現れるものを含む）は、JSONスキーマ仕様ドラフト2020-12で説明されているように、最も近い親の$idを基本URIとして使用します。

その他のオブジェクト内、および親スキーマに$idが含まれていないSchema Object内の相対URI参照は、参照ドキュメントの基本URIを使用して解決されなければなりません。基本URIは[[RFC3986]] セクション5.1.2 – 5.1.4に従って決定されます。実際には、これは通常、ドキュメントの取得URIであり、現在の実際の場所またはユーザーが指定した予期される場所に基づいて決定されてもよいです。

URIにフラグメント識別子が含まれている場合、フラグメントは参照ドキュメントのフラグメント解決メカニズムに従って解決されるべきです。参照ドキュメントの表現がJSONまたはYAMLである場合、フラグメント識別子はRFC6901に従ってJSONポインタとして解釈されるべきです。

CommonMark ハイパーリンクにおける相対参照は、API 記述のコンテキストとは異なる、レンダリングされたコンテキストで解決されます。

API URLにおける相対参照

API エンドポイントは定義上、ロケーションとしてアクセスされ、この仕様では**URL**として記述されます。

特に指定のない限り、URLであるすべてのフィールドは、RFC3986で定義されている相対参照であってもよい。特に指定のない限り、相対参照はServer Objectで定義されたURLを基本URLとして使用して解決されます。これら自体が参照ドキュメントに対して相対的であってもよいことに注意してください。

スキーマ

このセクションでは、OpenAPI Description 形式の構造について説明します。このテキストは、形式に関する唯一の規範的な記述です。JSON Schema は情報提供の目的でspec.openapis.orgで公開されています。JSON Schema がこのセクションと異なる場合、このセクションが権威あるものと見なされる**べき**です。

以下の記述において、フィールドが明示的にREQUIREDであるか、MUSTまたはSHALLで記述されていない場合、OPTIONALとみなされることがあります。

OpenAPI オブジェクト

これはOpenAPI Descriptionのルートオブジェクトです。

固定フィールド

フィールド名	タイプ	説明
openapi	文字列	必須。この文字列は、OpenAPI Document が使用する OpenAPI Specification のバージョン番号でなければなりません。openapiフィールドは、OpenAPI Document を解釈するためにツールによって使用されるべきです。これは API のinfo.version文字列とは*関係ありません*。
情報	情報オブジェクト	必須。APIに関するメタデータを提供します。メタデータは、必要に応じてツールによって使用されても構いません。
jsonSchemaDialect	文字列	この OAS ドキュメントに含まれるスキーマオブジェクト内の$schemaキーワードのデフォルト値。これは URI の形式でなければなりません。
サーバー	[サーバーオブジェクト]	ターゲットサーバーへの接続情報を提供するサーバーオブジェクトの配列。serversフィールドが提供されていない場合、または空の配列の場合、デフォルト値はServer Objectとなり、url値は/になります。
パス	パスオブジェクト	APIで利用可能なパスと操作。
ウェブフック	Map[string, Path Item Object]	このAPIの一部として受信される可能性があり、APIコンシューマーが実装を選択できる着信ウェブフック。callbacks機能に密接に関連しており、このセクションでは、APIコール以外、例えば帯域外登録によって開始されるリクエストと期待されるレスポンスを記述しています。キー名は各ウェブフックを参照するための一意の文字列であり、(オプションで参照される) Path Item ObjectはAPIプロバイダーによって開始される可能性のあるリクエストと期待されるレスポンスを記述しています。例が利用可能です。
コンポーネント	コンポーネントオブジェクト	OpenAPI Description の様々なオブジェクトを保持する要素。
セキュリティ	[セキュリティ要件オブジェクト]	API全体で使用できるセキュリティメカニズムの宣言。値のリストには、使用できる代替のSecurity Requirement Objectが含まれます。リクエストを承認するには、Security Requirement Objectのいずれか1つを満たせば十分です。個々の操作はこの定義を上書きできます。リストは不完全であってもよく、空であったり存在しなかったりすることもあります。セキュリティを明示的にオプションにするには、空のセキュリティ要件 ({}) を配列に含めることができます。
タグ	[タグオブジェクト]	追加のメタデータとともにOpenAPI Descriptionで使用されるタグのリスト。タグの順序は、解析ツールによる順序付けに反映させるために使用できます。Operation Objectで使用されるすべてのタグが宣言されている必要はありません。宣言されていないタグは、ランダムに、またはツールのロジックに基づいて整理されても構いません。リスト内の各タグ名は一意でなければなりません。
外部ドキュメント	外部ドキュメントオブジェクト	追加の外部ドキュメント。

このオブジェクトは仕様拡張で拡張されてもよい。

情報オブジェクト

このオブジェクトはAPIに関するメタデータを提供します。このメタデータは、必要に応じてクライアントによって使用されてもよく、利便性のために編集またはドキュメント生成ツールで提示されてもよいです。

固定フィールド

フィールド名	タイプ	説明
タイトル	文字列	必須。APIのタイトル。
概要	文字列	APIの簡単な概要。
説明	文字列	APIの説明。CommonMark 構文はリッチテキスト表現に使用しても構いません。
利用規約	文字列	APIの利用規約を示すURI。これはURIの形式でなければなりません。
連絡先	連絡先オブジェクト	公開されたAPIの連絡先情報。
ライセンス	ライセンスオブジェクト	公開されたAPIのライセンス情報。
バージョン	文字列	必須。OpenAPI Document のバージョン（OpenAPI Specification のバージョン、記述されている API のバージョン、OpenAPI Description のバージョンとは異なります）。

このオブジェクトは仕様拡張で拡張されてもよい。

情報オブジェクトの例

{
  "title": "Example Pet Store App",
  "summary": "A pet store manager.",
  "description": "This is an example server for a pet store.",
  "termsOfService": "https://example.com/terms/",
  "contact": {
    "name": "API Support",
    "url": "https://www.example.com/support",
    "email": "[email protected]"
  },
  "license": {
    "name": "Apache 2.0",
    "url": "https://apache.dokyumento.jp/licenses/LICENSE-2.0.html"
  },
  "version": "1.0.1"
}

title: Example Pet Store App
summary: A pet store manager.
description: This is an example server for a pet store.
termsOfService: https://example.com/terms/
contact:
  name: API Support
  url: https://www.example.com/support
  email: [email protected]
license:
  name: Apache 2.0
  url: https://apache.dokyumento.jp/licenses/LICENSE-2.0.html
version: 1.0.1

連絡先オブジェクト

公開されたAPIの連絡先情報。

固定フィールド

フィールド名	タイプ	説明
名前	文字列	担当者/組織の識別名。
URL	文字列	連絡先情報のURI。これはURIの形式でなければなりません。
メールアドレス	文字列	担当者/組織のEメールアドレス。これはEメールアドレスの形式でなければなりません。

このオブジェクトは仕様拡張で拡張されてもよい。

連絡先オブジェクトの例

{
  "name": "API Support",
  "url": "https://www.example.com/support",
  "email": "[email protected]"
}

name: API Support
url: https://www.example.com/support
email: [email protected]

ライセンスオブジェクト

公開されたAPIのライセンス情報。

固定フィールド

フィールド名	タイプ	説明
名前	文字列	必須。APIで使用されるライセンス名。
識別子	文字列	API用のSPDXライセンス式。identifierフィールドはurlフィールドと相互排他的です。
URL	文字列	APIで使用されるライセンスのURI。これはURIの形式でなければなりません。urlフィールドはidentifierフィールドと相互排他的です。

このオブジェクトは仕様拡張で拡張されてもよい。

ライセンスオブジェクトの例

{
  "name": "Apache 2.0",
  "identifier": "Apache-2.0"
}

name: Apache 2.0
identifier: Apache-2.0

サーバーオブジェクト

サーバーを表すオブジェクト。

固定フィールド

フィールド名	タイプ	説明
URL	文字列	必須。ターゲットホストへのURL。このURLはServer Variablesをサポートし、Server Objectを含むドキュメントが提供される場所に対するホストの場所が相対的であることを示すために、相対パスであってもよい。変数が{波括弧}で囲まれて指定された場合、変数置換が行われます。
説明	文字列	URLで指定されたホストを説明する任意の文字列。CommonMark構文はリッチテキスト表現に使用しても構いません。
変数	Map[string, Server Variable Object]	変数名とその値の間のマッピング。値はサーバーのURLテンプレート内の置換に使用されます。

このオブジェクトは仕様拡張で拡張されてもよい。

サーバーオブジェクトの例

単一のサーバーは次のように記述されます。

{
  "url": "https://development.gigantic-server.com/v1",
  "description": "Development server"
}

url: https://development.gigantic-server.com/v1
description: Development server

OpenAPI Object のserversでの例のように、複数のサーバーを記述する方法を以下に示します。

{
  "servers": [
    {
      "url": "https://development.gigantic-server.com/v1",
      "description": "Development server"
    },
    {
      "url": "https://staging.gigantic-server.com/v1",
      "description": "Staging server"
    },
    {
      "url": "https://api.gigantic-server.com/v1",
      "description": "Production server"
    }
  ]
}

servers:
  - url: https://development.gigantic-server.com/v1
    description: Development server
  - url: https://staging.gigantic-server.com/v1
    description: Staging server
  - url: https://api.gigantic-server.com/v1
    description: Production server

以下に、サーバー設定で変数を使用する方法を示します。

{
  "servers": [
    {
      "url": "https://{username}.gigantic-server.com:{port}/{basePath}",
      "description": "The production API server",
      "variables": {
        "username": {
          "default": "demo",
          "description": "A user-specific subdomain. Use `demo` for a free sandbox environment."
        },
        "port": {
          "enum": ["8443", "443"],
          "default": "8443"
        },
        "basePath": {
          "default": "v2"
        }
      }
    }
  ]
}

servers:
  - url: https://{username}.gigantic-server.com:{port}/{basePath}
    description: The production API server
    variables:
      username:
        # note! no enum here means it is an open value
        default: demo
        description: A user-specific subdomain. Use `demo` for a free sandbox environment.
      port:
        enum:
          - '8443'
          - '443'
        default: '8443'
      basePath:
        # open meaning there is the opportunity to use special base paths as assigned by the provider, default is `v2`
        default: v2

サーバー変数オブジェクト

サーバーURLテンプレート置換用のサーバー変数を表すオブジェクト。

固定フィールド

フィールド名	タイプ	説明
列挙型	[string]	置換オプションが限定されたセットからである場合に使用される文字列値の列挙。配列は空であってはなりません。
デフォルト	文字列	必須。置換に使用するデフォルト値であり、代替値が提供されない場合に送信される**べき**値。もしenumが定義されている場合、その値は列挙型の値に存在しなければなりません。この動作は、受信側の動作を文書化するものであって値をデータに挿入するものではないSchema Objectのdefaultキーワードとは異なることに注意してください。
説明	文字列	サーバー変数のオプションの説明。CommonMark 構文はリッチテキスト表現に使用しても構いません。

このオブジェクトは仕様拡張で拡張されてもよい。

コンポーネントオブジェクト

OASのさまざまな側面の再利用可能なオブジェクトセットを保持します。Components Object内で定義されたすべてのオブジェクトは、Components Objectの外部から明示的に参照されない限り、APIに影響を与えません。

固定フィールド

フィールド名	タイプ	説明
スキーマ	Map[string, Schema Object]	再利用可能なスキーマオブジェクトを保持するオブジェクト。
応答	Map[string, Response Object | Reference Object]	再利用可能なResponse Objectを保持するオブジェクト。
パラメーター	Map[string, Parameter Object | Reference Object]	再利用可能なParameter Objectを保持するオブジェクト。
例	Map[string, Example Object | Reference Object]	再利用可能なExample Objectを保持するオブジェクト。
リクエストボディ	Map[string, Request Body Object | Reference Object]	再利用可能なRequest Body Objectを保持するオブジェクト。
ヘッダー	Map[string, Header Object | Reference Object]	再利用可能なヘッダーオブジェクトを保持するオブジェクト。
セキュリティスキーム	Map[string, Security Scheme Object | Reference Object]	再利用可能なSecurity Scheme Objectを保持するオブジェクト。
リンク	Map[string, Link Object | Reference Object]	再利用可能なリンクオブジェクトを保持するオブジェクト。
コールバック	Map[string, Callback Object | Reference Object]	再利用可能なコールバックオブジェクトを保持するオブジェクト。
パス項目	Map[string, Path Item Object]	再利用可能なPath Item Objectを保持するオブジェクト。

このオブジェクトは仕様拡張で拡張されてもよい。

上記のすべての固定フィールドは、正規表現^[a-zA-Z0-9\.\-_]+$に一致するキーを使用しなければならないオブジェクトです。

フィールド名の例

User
User_1
User_Name
user-name
my.org.User

コンポーネントオブジェクトの例

"components": {
  "schemas": {
    "GeneralError": {
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "format": "int32"
        },
        "message": {
          "type": "string"
        }
      }
    },
    "Category": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer",
          "format": "int64"
        },
        "name": {
          "type": "string"
        }
      }
    },
    "Tag": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer",
          "format": "int64"
        },
        "name": {
          "type": "string"
        }
      }
    }
  },
  "parameters": {
    "skipParam": {
      "name": "skip",
      "in": "query",
      "description": "number of items to skip",
      "required": true,
      "schema": {
        "type": "integer",
        "format": "int32"
      }
    },
    "limitParam": {
      "name": "limit",
      "in": "query",
      "description": "max records to return",
      "required": true,
      "schema" : {
        "type": "integer",
        "format": "int32"
      }
    }
  },
  "responses": {
    "NotFound": {
      "description": "Entity not found."
    },
    "IllegalInput": {
      "description": "Illegal input for operation."
    },
    "GeneralError": {
      "description": "General Error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/GeneralError"
          }
        }
      }
    }
  },
  "securitySchemes": {
    "api_key": {
      "type": "apiKey",
      "name": "api-key",
      "in": "header"
    },
    "petstore_auth": {
      "type": "oauth2",
      "flows": {
        "implicit": {
          "authorizationUrl": "https://example.org/api/oauth/dialog",
          "scopes": {
            "write:pets": "modify pets in your account",
            "read:pets": "read your pets"
          }
        }
      }
    }
  }
}

components:
  schemas:
    GeneralError:
      type: object
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
    Category:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
    Tag:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
  parameters:
    skipParam:
      name: skip
      in: query
      description: number of items to skip
      required: true
      schema:
        type: integer
        format: int32
    limitParam:
      name: limit
      in: query
      description: max records to return
      required: true
      schema:
        type: integer
        format: int32
  responses:
    NotFound:
      description: Entity not found.
    IllegalInput:
      description: Illegal input for operation.
    GeneralError:
      description: General Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GeneralError'
  securitySchemes:
    api_key:
      type: apiKey
      name: api-key
      in: header
    petstore_auth:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: https://example.org/api/oauth/dialog
          scopes:
            write:pets: modify pets in your account
            read:pets: read your pets

パスオブジェクト

個々のエンドポイントとその操作への相対パスを保持します。完全なURLを構築するために、パスはServer ObjectからのURLに追加されます。Paths Objectは、アクセス制御リスト（ACL）の制約により、空であってもよいです。

パターンフィールド

フィールドパターン	タイプ	説明
/{パス}	パス項目オブジェクト	個々のエンドポイントへの相対パス。フィールド名はスラッシュ (/) で始まらなければなりません。完全な URL を構築するために、パスはServer Objectのurlフィールドから展開された URL に**追加**されます (相対 URL 解決は行われません)。パスのテンプレート化が許可されています。URL のマッチングでは、具体的な (テンプレート化されていない) パスがテンプレート化されたパスよりも先にマッチします。同じ階層でもテンプレート化された名前が異なるテンプレート化されたパスは、同一であるため存在してはなりません。曖昧なマッチングの場合、どちらを使用するかはツールが決定します。

このオブジェクトは仕様拡張で拡張されてもよい。

パスのテンプレートマッチング

以下のパスを想定すると、具体的な定義/pets/mineは、使用された場合、最初に一致します。

  /pets/{petId}
  /pets/mine

以下のパスは同一であり、無効とみなされます。

  /pets/{petId}
  /pets/{name}

以下は曖昧な解決につながる可能性があります

  /{entity}/me
  /books/{id}

パスオブジェクトの例

{
  "/pets": {
    "get": {
      "description": "Returns all pets from the system that the user has access to",
      "responses": {
        "200": {
          "description": "A list of pets.",
          "content": {
            "application/json": {
              "schema": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/pet"
                }
              }
            }
          }
        }
      }
    }
  }
}

/pets:
  get:
    description: Returns all pets from the system that the user has access to
    responses:
      '200':
        description: A list of pets.
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/pet'

パス項目オブジェクト

単一のパスで利用可能な操作を記述します。パス項目は、ACL 制限により空であっても構いません。パス自体はドキュメントビューアーに公開されますが、どの操作とパラメーターが利用可能かはわかりません。

固定フィールド

フィールド名	タイプ	説明
$参照	文字列	このパス項目の参照定義を許可します。値はURIの形式でなければならず、参照される構造はPath Item Objectの形式でなければなりません。Path Item Objectのフィールドが、定義されたオブジェクトと参照されたオブジェクトの両方に現れる場合、その動作は未定義です。相対参照を解決するためのルールを参照してください。 注:隣接するプロパティを持つ$refの動作は、将来のバージョンのこの仕様で変更され、参照オブジェクトの動作により厳密に合わせられる可能性があります。
概要	文字列	このパス内のすべての操作に適用されることを意図した、オプションの文字列概要。
説明	文字列	このパス内のすべての操作に適用することを意図した、オプションの文字列記述。CommonMark 構文はリッチテキスト表現に使用してもよい。
取得	操作オブジェクト	このパスでの GET 操作の定義。
入れる	操作オブジェクト	このパスでの PUT 操作の定義。
投稿	操作オブジェクト	このパスでの POST 操作の定義。
削除	操作オブジェクト	このパスでの DELETE 操作の定義。
オプション	操作オブジェクト	このパスでの OPTIONS 操作の定義。
頭	操作オブジェクト	このパスでの HEAD 操作の定義。
パッチ	操作オブジェクト	このパスでの PATCH 操作の定義。
トレース	操作オブジェクト	このパスでの TRACE 操作の定義。
サーバー	[サーバーオブジェクト]	このパス内のすべての操作を処理するための代替servers配列。OpenAPI Objectレベルでservers配列が指定されている場合、この値によって上書きされます。
パラメーター	[パラメーターオブジェクト | 参照オブジェクト]	このパスの下に記述されているすべての操作に適用されるパラメータのリスト。これらのパラメータは操作レベルで上書きできますが、そこで削除することはできません。リストには重複するパラメータを含んではなりません。一意のパラメータは、名前と場所の組み合わせによって定義されます。リストはReference Objectを使用して、OpenAPI Object のcomponents.parametersで定義されているパラメータにリンクできます。

このオブジェクトは仕様拡張で拡張されてもよい。

パス項目オブジェクトの例

{
  "get": {
    "description": "Returns pets based on ID",
    "summary": "Find pets by ID",
    "operationId": "getPetsById",
    "responses": {
      "200": {
        "description": "pet response",
        "content": {
          "*/*": {
            "schema": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/Pet"
              }
            }
          }
        }
      },
      "default": {
        "description": "error payload",
        "content": {
          "text/html": {
            "schema": {
              "$ref": "#/components/schemas/ErrorModel"
            }
          }
        }
      }
    }
  },
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "description": "ID of pet to use",
      "required": true,
      "schema": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "style": "simple"
    }
  ]
}

get:
  description: Returns pets based on ID
  summary: Find pets by ID
  operationId: getPetsById
  responses:
    '200':
      description: pet response
      content:
        '*/*':
          schema:
            type: array
            items:
              $ref: '#/components/schemas/Pet'
    default:
      description: error payload
      content:
        text/html:
          schema:
            $ref: '#/components/schemas/ErrorModel'
parameters:
  - name: id
    in: path
    description: ID of pet to use
    required: true
    schema:
      type: array
      items:
        type: string
    style: simple

操作オブジェクト

パス上の単一のAPI操作を記述します。

固定フィールド

フィールド名	タイプ	説明
タグ	[string]	APIドキュメント管理用のタグのリスト。タグは、リソースまたはその他の修飾子によって操作を論理的にグループ化するために使用できます。
概要	文字列	操作の簡単な概要。
説明	文字列	操作の動作に関する詳細な説明。CommonMark 構文はリッチテキスト表現に使用してもよい。
外部ドキュメント	外部ドキュメントオブジェクト	この操作に関する追加の外部ドキュメント。
操作ID	文字列	操作を識別するために使用される一意の文字列。IDはAPIで記述されているすべての操作の中で一意でなければなりません。operationIdの値は**大文字と小文字を区別します**。ツールやライブラリはoperationIdを一意に操作を識別するために使用してもよいため、一般的なプログラミング命名規則に従うことが**推奨されます**。
パラメーター	[パラメーターオブジェクト | 参照オブジェクト]	この操作に適用されるパラメータのリスト。パラメータがすでにPath Itemで定義されている場合、新しい定義はそれを上書きしますが、削除することはできません。リストには重複するパラメータを含んではなりません。一意のパラメータは、名前と場所の組み合わせによって定義されます。リストはReference Objectを使用して、OpenAPI Object のcomponents.parametersで定義されているパラメータにリンクできます。
リクエストボディ	リクエストボディオブジェクト | 参照オブジェクト	この操作に適用されるリクエストボディ。HTTP 1.1 仕様 RFC7231 がリクエストボディのセマンティクスを明示的に定義している HTTP メソッドでは、requestBody は完全にサポートされます。HTTP 仕様が曖昧な他のケース（GET、HEAD、DELETEなど）では、requestBody は許可されていますが、明確に定義されたセマンティクスがなく、可能であれば避けるべきです。
応答	応答オブジェクト	この操作の実行から返される可能性のある応答のリスト。
コールバック	Map[string, Callback Object | Reference Object]	親操作に関連する帯域外コールバックのマップ。キーは Callback Object の一意な識別子です。マップ内の各値は、API プロバイダーによって開始される可能性のあるリクエストと期待される応答を記述するCallback Objectです。
非推奨	ブール値	この操作を非推奨と宣言します。利用者は宣言された操作の使用を控えるべきです。デフォルト値はfalseです。
セキュリティ	[セキュリティ要件オブジェクト]	この操作で使用できるセキュリティメカニズムの宣言。値のリストには、使用できる代替のSecurity Requirement Objectが含まれます。リクエストを認証するには、Security Requirement Objectのいずれか1つを満たせば十分です。セキュリティをオプションにするには、空のセキュリティ要件 ({}) を配列に含めることができます。この定義は、宣言された最上位のsecurityを上書きします。最上位のセキュリティ宣言を削除するには、空の配列を使用できます。
サーバー	[サーバーオブジェクト]	この操作を処理するための代替servers配列。Path Item ObjectまたはOpenAPI Objectレベルでservers配列が指定されている場合、この値によって上書きされます。

このオブジェクトは仕様拡張で拡張されてもよい。

操作オブジェクトの例

{
  "tags": ["pet"],
  "summary": "Updates a pet in the store with form data",
  "operationId": "updatePetWithForm",
  "parameters": [
    {
      "name": "petId",
      "in": "path",
      "description": "ID of pet that needs to be updated",
      "required": true,
      "schema": {
        "type": "string"
      }
    }
  ],
  "requestBody": {
    "content": {
      "application/x-www-form-urlencoded": {
        "schema": {
          "type": "object",
          "properties": {
            "name": {
              "description": "Updated name of the pet",
              "type": "string"
            },
            "status": {
              "description": "Updated status of the pet",
              "type": "string"
            }
          },
          "required": ["status"]
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Pet updated.",
      "content": {
        "application/json": {},
        "application/xml": {}
      }
    },
    "405": {
      "description": "Method Not Allowed",
      "content": {
        "application/json": {},
        "application/xml": {}
      }
    }
  },
  "security": [
    {
      "petstore_auth": ["write:pets", "read:pets"]
    }
  ]
}

tags:
  - pet
summary: Updates a pet in the store with form data
operationId: updatePetWithForm
parameters:
  - name: petId
    in: path
    description: ID of pet that needs to be updated
    required: true
    schema:
      type: string
requestBody:
  content:
    application/x-www-form-urlencoded:
      schema:
        type: object
        properties:
          name:
            description: Updated name of the pet
            type: string
          status:
            description: Updated status of the pet
            type: string
        required:
          - status
responses:
  '200':
    description: Pet updated.
    content:
      application/json: {}
      application/xml: {}
  '405':
    description: Method Not Allowed
    content:
      application/json: {}
      application/xml: {}
security:
  - petstore_auth:
      - write:pets
      - read:pets

外部ドキュメントオブジェクト

拡張ドキュメントのために外部リソースを参照することを許可します。

固定フィールド

フィールド名	タイプ	説明
説明	文字列	ターゲットドキュメントの説明。CommonMark 構文はリッチテキスト表現に使用してもよい。
URL	文字列	必須。ターゲットドキュメントのURI。これはURIの形式でなければなりません。

このオブジェクトは仕様拡張で拡張されてもよい。

外部ドキュメントオブジェクトの例

{
  "description": "Find more info here",
  "url": "https://example.com"
}

description: Find more info here
url: https://example.com

パラメーターオブジェクト

単一の操作パラメーターを記述します。

一意のパラメーターは、名前と場所の組み合わせによって定義されます。

パーセントエンコーディングに関する詳細な考察（application/x-www-form-urlencodedクエリ文字列形式との相互作用を含む）については、付録Eを参照してください。

パラメーターの位置

inフィールドで指定されるパラメーターの位置は4種類あります。

• path - パスのテンプレート化と組み合わせて使用され、パラメーター値が実際に操作のURLの一部となる場合。これにはAPIのホストまたはベースパスは含まれません。例えば、/items/{itemId}では、パスパラメーターはitemIdです。
• query - URLに追加されるパラメータ。例えば、/items?id=###では、クエリパラメータはidです。
• header - リクエストの一部として期待されるカスタムヘッダー。なお、RFC7230ではヘッダー名は大文字と小文字を区別しないと規定されています。
• cookie - 特定のクッキー値をAPIに渡すために使用されます。

固定フィールド

パラメータのシリアライゼーションのルールは、contentフィールドまたはschemaフィールドのいずれかを使用して指定されますが、両方を使用することはできません。付録Bで、さまざまな型の値を文字列表現に変換する方法について考察しています。

共通固定フィールド

これらのフィールドは、contentまたはschemaのどちらでも使用できます。

フィールド名	タイプ	説明
名前	文字列	必須。パラメータの名前。パラメータ名は大文字と小文字を区別します。 inが"path"の場合、nameフィールドはPaths Objectのpathフィールド内に現れるテンプレート式に対応しなければなりません。詳細については、Path Templatingを参照してください。 inが"header"で、nameフィールドが"Accept"、"Content-Type"、または"Authorization"の場合、パラメータ定義は無視される**べき**です。 その他のすべてのケースでは、nameはinフィールドで使用されるパラメータ名に対応します。
イン	文字列	必須。パラメーターの位置。指定可能な値は、"query"、"header"、"path"、または"cookie"です。
説明	文字列	パラメーターの簡単な説明。使用例が含まれてもよい。CommonMark 構文はリッチテキスト表現に使用してもよい。
必須	ブール値	このパラメーターが必須かどうかを決定します。パラメーターの場所が"path"の場合、このフィールドは必須であり、その値はtrueでなければなりません。それ以外の場合、このフィールドは含まれてもよく、そのデフォルト値はfalseです。
非推奨	ブール値	パラメーターが非推奨であり、使用から移行されるべきであることを指定します。デフォルト値はfalseです。
空の値を許可する	ブール値	もしtrueの場合、クライアントは完全に省略されるはずのパラメーターの代わりにゼロ長の文字列値を渡してもよく、サーバーはそれをパラメーターが未使用であると解釈すべきです。デフォルト値はfalseです。もしstyleが使用され、動作がn/a（シリアライズ不可）の場合、allowEmptyValueの値は無視される**べき**です。このフィールドとパラメーターのSchema Objectとの相互作用は実装定義です。このフィールドはqueryパラメーターのみ有効です。このフィールドの使用は**推奨されず**、後の改訂で削除される可能性があります。

このオブジェクトは仕様拡張で拡張されてもよい。

inが"header"の場合にnameとして"Cookie"が禁止されていないとしても、その方法でcookieパラメータを定義する効果は未定義であることに注意してください。代わりにin: "cookie"を使用してください。

schemaで使用するための固定フィールド

より単純なシナリオでは、schemaとstyleがパラメータの構造と構文を記述できます。schemaフィールドと合わせてexampleまたはexamplesが提供される場合、例は指定されたスキーマと一致し、パラメータに規定されたシリアライゼーション戦略に従うべきです。exampleとexamplesフィールドは相互排他的であり、いずれかが存在する場合はスキーマ内のexampleを*上書き*しなければなりません。

schemaを使用したシリアライゼーションは、in: "cookie"パラメータ、値にHTTPヘッダーパラメータ（;に続く名前=値のペア）を使用するin: "header"パラメータ、または値にURLセーフでない文字が含まれる可能性があるin: "header"パラメータには**推奨されません**。詳細については付録Dを参照してください。

フィールド名	タイプ	説明
スタイル	文字列	パラメーター値の型に応じて、パラメーター値がどのようにシリアライズされるかを記述します。デフォルト値（inの値に基づく）："query"の場合は"form"、"path"の場合は"simple"、"header"の場合は"simple"、"cookie"の場合は"form"です。
爆発	ブール値	これが true の場合、array 型または object 型のパラメーター値は、配列の各値またはマップのキーと値のペアごとに個別のパラメーターを生成します。他の型のパラメーターの場合、このフィールドは効果がありません。styleが"form"の場合、デフォルト値はtrueです。他のすべてのスタイルでは、デフォルト値はfalseです。deepObjectの場合のデフォルトがfalseであるにもかかわらず、falseとdeepObjectの組み合わせは未定義であることに注意してください。
予約済みを許可する	ブール値	これが true の場合、パラメータ値はRFC6570で定義されている予約済み拡張を使用してシリアライズされます。これにより、RFC3986 の予約文字セット、およびパーセントエンコードされたトリプルが変更されずに通過し、他のすべての禁止文字（パーセントエンコードされたトリプルの外側の%を含む）はパーセントエンコードされます。アプリケーションは依然として、クエリ文字列で許可されていない予約文字（[、]、#）や、application/x-www-form-urlencodedで特別な意味を持つ文字（-、&、+）をパーセントエンコードする責任があります。詳細については、付録CとEを参照してください。このフィールドは、query の in 値を持つパラメータにのみ適用されます。デフォルト値はfalseです。
スキーマ	スキーマオブジェクト	パラメータに使用される型を定義するスキーマ。
例	任意	パラメーターの潜在的な値の例。例の扱いを参照してください。
例	Map[ string, Example Object | Reference Object]	パラメーターの潜在的な値の例。例の扱いを参照してください。

追加のガイダンスについては、付録C：RFC6570ベースのシリアライゼーションの使用も参照してください。

contentで使用するための固定フィールド

より複雑なシナリオでは、contentフィールドが、パラメータのメディアタイプとスキーマを定義し、その使用例を提供できます。schema戦略が適切でないin: "header"およびin: "cookie"パラメータには、contentとtext/plainメディアタイプの使用が推奨されます。

フィールド名	タイプ	説明
コンテンツ	Map[string, Media Type Object]	パラメーターの表現を含むマップ。キーはメディアタイプで、値はその記述です。マップはエントリを1つだけ含んでいなければなりません。

スタイル値

単純なパラメータをシリアライズする一般的な方法をサポートするために、一連のstyle値が定義されています。

スタイル	タイプ	イン	コメント
マトリックス	primitive, array, object	パス	RFC6570で定義されているパス形式のパラメーター
ラベル	primitive, array, object	パス	RFC6570で定義されたラベル形式のパラメーター
シンプル	primitive, array, object	path, header	RFC6570で定義されているシンプルな形式のパラメーター。このオプションは、OpenAPI 2.0 のcollectionFormatのcsv値を置き換えます。
フォーム	primitive, array, object	query, cookie	RFC6570で定義されたフォームスタイルパラメーター。このオプションは、OpenAPI 2.0 のcollectionFormatをcsv（explodeがfalseの場合）またはmulti（explodeがtrueの場合）の値に置き換えます。
スペース区切り	array, object	問い合わせ	スペース区切りの配列値またはオブジェクトのプロパティと値。このオプションは、OpenAPI 2.0 のcollectionFormatがssvであるものを置き換えます。
パイプ区切り	array, object	問い合わせ	パイプ区切りの配列値またはオブジェクトのプロパティと値。このオプションは、OpenAPI 2.0 のcollectionFormatがpipesであるものを置き換えます。
ディープオブジェクト	オブジェクト	問い合わせ	スカラープロパティを持つオブジェクトをフォームパラメーターを使用して表現することを許可します。配列またはオブジェクトプロパティの表現は定義されていません。

パーセントエンコーディング（区切り文字がパーセントエンコードされる必要がある場合や、パーセントエンコードされたデータとの衝突を処理するオプションを含む）の詳細な考察については、付録Eを参照してください。

スタイル例

colorという名前のパラメーターが以下のいずれかの値を持つと仮定します。

   string -> "blue"
   array -> ["blue", "black", "brown"]
   object -> { "R": 100, "G": 200, "B": 150 }

以下の表は、exampleまたはexamplesキーワードで示されるであろう、各値の異なるシリアライゼーションの例を示しています。

• 値*empty*は空文字列を示し、allowEmptyValueフィールドとは無関係です。
• n/aとマークされた組み合わせの動作は未定義です。
• undefined列は、RFC6570の用語により厳密に合わせるために、この仕様の以前のバージョンにおけるempty列を置き換えるものです。この用語では、nullを含む（ただしこれに限定されない）特定の値を特殊な処理を伴う「未定義」の値と記述しています。特に、空文字列は未定義では*ありません*。
• formおよびRFC6570以外のクエリ文字列スタイルspaceDelimited、pipeDelimited、deepObjectについては、各例は単一のクエリパラメータであるかのように?を接頭辞として示されています。複数のパラメータからクエリ文字列を構築する方法については付録Cを、formとクッキーパラメータに関する警告については付録Dを参照してください。
• ?接頭辞はapplication/x-www-form-urlencoded HTTPメッセージボディのシリアライゼーションには適切ではなく、そのコンテキストで使用する際には削除するか（文字列を手動で構築する場合は）追加してはならないことに注意してください。詳細についてはEncoding Objectを参照してください。
• 例は RFC6570 および RFC3986 で要求されるようにパーセントエンコードされています。エンコードされていない | (%7C)、[ (%5B)、および ] (%5D) が一部の環境で準拠していないにもかかわらず動作するように見える理由など、パーセントエンコーディングに関する詳細な議論については付録 Eを参照してください。

スタイル	爆発する	未定義	文字列	配列	オブジェクト
マトリックス	偽	;カラー	;color=blue	;color=青、黒、茶	;カラー=R,100,G,200,B,150
マトリックス	本当	;カラー	;color=blue	;color=blue;color=black;color=brown	;R=100;G=200;B=150
ラベル	偽	.	.ブルー	.青、黒、茶	.R,100,G,200,B,150
ラベル	本当	.	.ブルー	.青.黒.茶	.R=100.G=200.B=150
シンプル	偽	空	青	青、黒、茶	R,100,G,200,B,150
シンプル	本当	空	青	青、黒、茶	R=100,G=200,B=150
フォーム	偽	?カラー=	?カラー=青	?カラー=青、黒、茶	?カラー=R,100,G,200,B,150
フォーム	本当	?カラー=	?カラー=青	?color=青&color=黒&color=茶	?R=100&G=200&B=150
スペース区切り	偽	該当なし	該当なし	?color=青%20黒%20茶	?カラー=R%20100%20G%20200%20B%20150
スペース区切り	本当	該当なし	該当なし	該当なし	該当なし
パイプ区切り	偽	該当なし	該当なし	?カラー=R%7C100%7CG%7C200%7CB%7C150	?color=R%7C100%7CG%7C200%7CB%7C150
パイプ区切り	本当	該当なし	該当なし	該当なし	該当なし
ディープオブジェクト	偽	該当なし	該当なし	該当なし	該当なし
ディープオブジェクト	本当	該当なし	該当なし	該当なし	?color%5BR%5D=100&color%5BG%5D=200&color%5BB%5D=150

パラメータオブジェクトの例

64ビット整数配列のヘッダーパラメータ

{
  "name": "token",
  "in": "header",
  "description": "token to be passed as a header",
  "required": true,
  "schema": {
    "type": "array",
    "items": {
      "type": "integer",
      "format": "int64"
    }
  },
  "style": "simple"
}

name: token
in: header
description: token to be passed as a header
required: true
schema:
  type: array
  items:
    type: integer
    format: int64
style: simple

文字列値のパスパラメーター

{
  "name": "username",
  "in": "path",
  "description": "username to fetch",
  "required": true,
  "schema": {
    "type": "string"
  }
}

name: username
in: path
description: username to fetch
required: true
schema:
  type: string

文字列値のオプションのクエリパラメーターで、クエリパラメーターを繰り返すことで複数の値を許可する

{
  "name": "id",
  "in": "query",
  "description": "ID of the object to fetch",
  "required": false,
  "schema": {
    "type": "array",
    "items": {
      "type": "string"
    }
  },
  "style": "form",
  "explode": true
}

name: id
in: query
description: ID of the object to fetch
required: false
schema:
  type: array
  items:
    type: string
style: form
explode: true

contentを使用してシリアライゼーションを定義する複雑なパラメーター

{
  "in": "query",
  "name": "freeForm",
  "schema": {
    "type": "object",
    "additionalProperties": {
      "type": "integer"
    }
  },
  "style": "form"
}

in: query
name: freeForm
schema:
  type: object
  additionalProperties:
    type: integer
style: form

contentを使用してシリアライゼーションを定義する複雑なパラメーター

{
  "in": "query",
  "name": "coordinates",
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "required": ["lat", "long"],
        "properties": {
          "lat": {
            "type": "number"
          },
          "long": {
            "type": "number"
          }
        }
      }
    }
  }
}

in: query
name: coordinates
content:
  application/json:
    schema:
      type: object
      required:
        - lat
        - long
      properties:
        lat:
          type: number
        long:
          type: number

リクエストボディオブジェクト

単一のリクエストボディを記述します。

固定フィールド

フィールド名	タイプ	説明
説明	文字列	リクエストボディの簡単な説明。使用例が含まれてもよい。CommonMark 構文はリッチテキスト表現に使用してもよい。
コンテンツ	Map[string, Media Type Object]	必須。リクエストボディの内容。キーはメディアタイプまたはメディアタイプ範囲で、値はそれを記述します。複数のキーに一致するリクエストの場合、最も具体的なキーのみが適用されます。例えば、"text/plain"は"text/*"を上書きします。
必須	ブール値	リクエストボディがリクエストで必須かどうかを決定します。デフォルトはfalseです。

このオブジェクトは仕様拡張で拡張されてもよい。

リクエストボディの例

参照されたスキーマ定義を持つリクエストボディ。

{
  "description": "user to add to the system",
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/User"
      },
      "examples": {
        "user": {
          "summary": "User Example",
          "externalValue": "https://foo.bar/examples/user-example.json"
        }
      }
    },
    "application/xml": {
      "schema": {
        "$ref": "#/components/schemas/User"
      },
      "examples": {
        "user": {
          "summary": "User example in XML",
          "externalValue": "https://foo.bar/examples/user-example.xml"
        }
      }
    },
    "text/plain": {
      "examples": {
        "user": {
          "summary": "User example in Plain text",
          "externalValue": "https://foo.bar/examples/user-example.txt"
        }
      }
    },
    "*/*": {
      "examples": {
        "user": {
          "summary": "User example in other format",
          "externalValue": "https://foo.bar/examples/user-example.whatever"
        }
      }
    }
  }
}

description: user to add to the system
content:
  application/json:
    schema:
      $ref: '#/components/schemas/User'
    examples:
      user:
        summary: User example
        externalValue: https://foo.bar/examples/user-example.json
  application/xml:
    schema:
      $ref: '#/components/schemas/User'
    examples:
      user:
        summary: User example in XML
        externalValue: https://foo.bar/examples/user-example.xml
  text/plain:
    examples:
      user:
        summary: User example in plain text
        externalValue: https://foo.bar/examples/user-example.txt
  '*/*':
    examples:
      user:
        summary: User example in other format
        externalValue: https://foo.bar/examples/user-example.whatever

メディアタイプオブジェクト

各Media Type Objectは、そのキーで識別されるメディアタイプに対するスキーマと例を提供します。

exampleまたはexamplesが提供される場合、その例は指定されたスキーマと一致し、メディアタイプとそのエンコーディングによって指定された正しい形式であるべきです。exampleとexamplesフィールドは相互排他的であり、どちらか一方が存在する場合、スキーマ内のexampleを*上書き*しなければなりません。JSON/YAML以外の値を含む例を指定するさまざまな方法に関する詳細なガイダンスについては、例の扱いを参照してください。

固定フィールド

フィールド名	タイプ	説明
スキーマ	スキーマオブジェクト	リクエスト、レスポンス、パラメーター、またはヘッダーのコンテンツを定義するスキーマ。
例	任意	メディアタイプの例。例の扱いを参照してください。
例	Map[ string, Example Object | Reference Object]	メディアタイプの例。例の扱いを参照してください。
エンコード	Map[string, Encoding Object]	プロパティ名とエンコーディング情報の間のマップ。キーであるプロパティ名は、スキーマにプロパティとして存在しなければなりません。encodingフィールドはRequest Body Objectにのみ適用され、メディアタイプがmultipartまたはapplication/x-www-form-urlencodedの場合にのみ適用されます。プロパティに対してEncoding Objectが提供されない場合、動作はEncoding Objectのデフォルト値によって決定されます。

このオブジェクトは仕様拡張で拡張されてもよい。

メディアタイプ例

{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/Pet"
    },
    "examples": {
      "cat": {
        "summary": "An example of a cat",
        "value": {
          "name": "Fluffy",
          "petType": "Cat",
          "color": "White",
          "gender": "male",
          "breed": "Persian"
        }
      },
      "dog": {
        "summary": "An example of a dog with a cat's name",
        "value": {
          "name": "Puma",
          "petType": "Dog",
          "color": "Black",
          "gender": "Female",
          "breed": "Mixed"
        }
      },
      "frog": {
        "$ref": "#/components/examples/frog-example"
      }
    }
  }
}

application/json:
  schema:
    $ref: '#/components/schemas/Pet'
  examples:
    cat:
      summary: An example of a cat
      value:
        name: Fluffy
        petType: Cat
        color: White
        gender: male
        breed: Persian
    dog:
      summary: An example of a dog with a cat's name
      value:
        name: Puma
        petType: Dog
        color: Black
        gender: Female
        breed: Mixed
    frog:
      $ref: '#/components/examples/frog-example'

ファイルアップロードに関する考慮事項

OpenAPI 2.0とは対照的に、OAS 3.xにおけるfileの入出力コンテンツは、他のスキーマタイプと同じセマンティクスで記述されます。

OAS 3.0 とは対照的に、OAS 3.1 ではformatキーワードはスキーマのコンテンツエンコーディングに影響を与えません。代わりに、JSON Schema のcontentEncodingとcontentMediaTypeキーワードが使用されます。これらのキーワードでさまざまなシナリオをモデル化する方法、および以前のformat使用から移行する方法については、バイナリデータの操作を参照してください。

例

バイナリ（オクテットストリーム）で転送されるコンテンツはschemaを省略してもよい。

# a PNG image as a binary file:
content:
  image/png: {}

# an arbitrary binary file:
content:
  application/octet-stream: {}

# arbitrary JSON without constraints beyond being syntactically valid:
content:
  application/json: {}

これらの例は、ファイルアップロードの入力ペイロードと応答ペイロードの両方に適用されます。

POST操作でファイルを送信するためのrequestBodyは、次の例のようになる場合があります。

requestBody:
  content:
    application/octet-stream: {}

さらに、特定のメディアタイプを指定することもできます。

# multiple, specific media types may be specified:
requestBody:
  content:
    # a binary file of type png or jpeg
    image/jpeg: {}
    image/png: {}

複数のファイルをアップロードするには、例：複数ファイルを含むマルチパートフォームに示されているように、multipartメディアタイプを使用しなければなりません。

x-www-form-urlencodedリクエストボディのサポート

encodingフィールドの有無にかかわらず、ガイダンスと例については、x-www-form-urlencodedメディアタイプのエンコーディングを参照してください。

multipartコンテンツに関する特別な考慮事項

encodingフィールドの有無にかかわらず、詳細なガイダンスと例については、multipartメディアタイプのエンコーディングを参照してください。

エンコーディングオブジェクト

単一のスキーマプロパティに適用される単一のエンコーディング定義。付録Bで、さまざまな型の値を文字列表現に変換する方法について考察しています。

プロパティは、Content-Disposition: form-dataのnameパラメータを使用してmultipart部分と相関し、クエリ文字列パラメータ名を使用してapplication/x-www-form-urlencodedと相関します。どちらの場合も、その順序は実装定義です。

フォームメディアタイプのパーセントエンコーディングに関する詳細な考察については、付録Eを参照してください。

固定フィールド

共通固定フィールド

これらのフィールドは、次のセクションで定義されているRFC6570スタイルのシリアライゼーションフィールドの有無にかかわらず使用できます。

フィールド名	タイプ	説明
コンテンツタイプ	文字列	特定のプロパティをエンコードするためのContent-Type。値はコンマ区切りのリストで、各要素は特定のメディアタイプ（例：image/png）またはワイルドカードメディアタイプ（例：image/*）です。デフォルト値は、以下の表に示すようにプロパティの型によって異なります。
ヘッダー	Map[string, Header Object | Reference Object]	追加情報をヘッダーとして提供できるマップです。Content-Type は別途記述されており、このセクションでは無視されます。リクエストボディのメディアタイプが multipart でない場合、このフィールドは無視されます。

このオブジェクトは仕様拡張で拡張されてもよい。

contentType のデフォルト値は以下の通りです。contentEncoding 列の n/a は、contentEncoding の有無や値が関係ないことを意味します。

タイプ	contentEncoding	デフォルトの contentType
不在	該当なし	application/octet-stream
文字列	存在する	application/octet-stream
文字列	不在	text/plain
number、integer、または boolean	該当なし	text/plain
オブジェクト	該当なし	application/json
配列	該当なし	items スキーマの type に従って

null の type 値をどのように処理するかは、null 値がどのようにシリアル化されるかによって異なります。null 値が完全に省略される場合、contentType は関係ありません。データ型変換オプションについては、付録 B を参照してください。

RFC6570 スタイルのシリアル化のための固定フィールド

フィールド名	タイプ	説明
スタイル	文字列	特定のプロパティ値がその型に応じてどのようにシリアル化されるかを記述します。style フィールドの詳細については、パラメーターオブジェクトを参照してください。動作は、デフォルト値を含む query パラメーターと同じ値に従います。クエリ文字列で使用される最初の ? は application/x-www-form-urlencoded メッセージボディでは使用されず、削除する (RFC6570 実装を使用する場合) か、単に含めない (手動で文字列を構築する場合) 必要があります。リクエストボディのメディアタイプが application/x-www-form-urlencoded または multipart/form-data でない場合、このフィールドは無視されます。値が明示的に定義されている場合、contentType の値 (暗黙的または明示的) は無視されます。
展開	ブール値	これが true の場合、array または object 型のプロパティ値は、配列の各値、またはマップのキーと値のペアごとに個別のパラメーターを生成します。他の種類のプロパティの場合、このフィールドは効果がありません。style が "form" の場合、デフォルト値は true です。他のすべてのスタイルでは、デフォルト値は false です。deepObject のデフォルトが false であるにもかかわらず、false と deepObject の組み合わせは未定義であることに注意してください。リクエストボディのメディアタイプが application/x-www-form-urlencoded または multipart/form-data でない場合、このフィールドは無視されます。値が明示的に定義されている場合、contentType の値 (暗黙的または明示的) は無視されます。
予約許可	ブール値	これが true の場合、パラメーター値は RFC6570 で定義されているように、予約拡張を使用してシリアル化されます。これにより、RFC3986 の予約文字セット、およびパーセントエンコードされたトリプルは変更されずに通過し、他のすべての許可されていない文字 (パーセントエンコードされたトリプル以外の % を含む) はパーセントエンコードされます。アプリケーションは、クエリ文字列で許可されていない予約文字 ([、]、#) や、application/x-www-form-urlencoded で特別な意味を持つ文字 (-、&、+) をパーセントエンコードする責任があります。詳細については、付録 C および E を参照してください。デフォルト値は false です。リクエストボディのメディアタイプが application/x-www-form-urlencoded または multipart/form-data でない場合、このフィールドは無視されます。値が明示的に定義されている場合、contentType の値 (暗黙的または明示的) は無視されます。

RFC6570 のパーセントエンコーディングルールと multipart/form-data メディアタイプ間の相互作用によって引き起こされる問題を含む、追加のガイダンスについては、付録 C: RFC6570 実装の使用も参照してください。

style、explode、または allowReserved の少なくともいずれかが明示的な値で存在することは、in: "query" パラメーターオブジェクトを持つ schema を使用することと同等であることに注意してください。これら 3 つのフィールドすべてが存在しないことは、content を使用することと同等ですが、メディアタイプは Media Type Object ではなく contentType で指定されます。

x-www-form-urlencoded メディアタイプのエンコーディング

RFC1866 を介してフォームURLエンコーディングを使用してコンテンツを送信するには、リクエストボディオブジェクトの下のメディアタイプオブジェクトで application/x-www-form-urlencoded メディアタイプを使用します。この構成は、複雑なオブジェクトが文字列表現にシリアル化された後、リクエストボディがRFC1866に従ってサーバーに渡される際にエンコードされなければならないことを意味します。

フォームメディアタイプのパーセントエンコーディングに関する詳細な考察については、付録Eを参照してください。

例: JSON値を含むURLエンコードされたフォーム

encoding フィールドがない場合、シリアル化戦略は Encoding Object のデフォルト値に基づいています。

requestBody:
  content:
    application/x-www-form-urlencoded:
      schema:
        type: object
        properties:
          id:
            type: string
            format: uuid
          address:
            # complex types are stringified to support RFC 1866
            type: object
            properties: {}

この例では、id が f81d4fae-7dec-11d0-a765-00a0c91e6bf6 であり、ZIP+4 を含む米国式住所が以下のようになっているとします。

{
  "streetAddress": "123 Example Dr.",
  "city": "Somewhere",
  "state": "CA",
  "zip": "99999+1234"
}

JSON 値の最もコンパクトな表現 (不要な空白を削除) を仮定すると、スペース文字が + に置き換えられ、+、"、{、} がそれぞれ %2B、%22、%7B、%7D にパーセントエンコードされた以下のリクエストボディが表示されることが期待されます。

id=f81d4fae-7dec-11d0-a765-00a0c91e6bf6&address=%7B%22streetAddress%22:%22123+Example+Dr.%22,%22city%22:%22Somewhere%22,%22state%22:%22CA%22,%22zip%22:%2299999%2B1234%22%7D

Encoding Object のデフォルトの動作に従って、id キーワードは text/plain として扱われ、そのままシリアル化されることに注意してください。もし application/json として扱われた場合、シリアル化された値は引用符を含む JSON 文字列になり、%22 としてパーセントエンコードされます。

以下は、id パラメーター (address なし) を text/plain の代わりに application/json としてシリアル化し、その後 RFC1866 に従ってエンコードしたものです。

id=%22f81d4fae-7dec-11d0-a765-00a0c91e6bf6%22

例: バイナリ値を含むURLエンコードされたフォーム

application/x-www-form-urlencoded はテキスト形式であり、バイナリデータを Base64 エンコードする必要があることに注意してください。

requestBody:
  content:
    application/x-www-form-urlencoded:
      schema:
        type: object
        properties:
          name:
            type: string
          icon:
            # The default with "contentEncoding" is application/octet-stream,
            # so we need to set image media type(s) in the Encoding Object.
            type: string
            contentEncoding: base64url
  encoding:
    icon:
      contentType: image/png, image/jpeg

名前が example で、icon にソリッドレッドの 2x2 ピクセルの PNG が与えられた場合、これは以下のリクエストボディを生成します。

name=example&icon=iVBORw0KGgoAAAANSUhEUgAAAAIAAAACCAIAAAD91JpzAAAABGdBTUEAALGPC_xhBQAAADhlWElmTU0AKgAAAAgAAYdpAAQAAAABAAAAGgAAAAAAAqACAAQAAAABAAAAAqADAAQAAAABAAAAAgAAAADO0J6QAAAAEElEQVQIHWP8zwACTGCSAQANHQEDqtPptQAAAABJRU5ErkJggg%3D%3D

"URLセーフ"な contentEncoding: base64url であっても、末尾の = パディング文字はパーセントエンコードする必要があることに注意してください。RFC4648 に従って、一部の Base64 デコード実装はパディングなしで文字列を使用できる場合があります。ただし、これは保証されていないため、パディングを保持し、パーセントデコードに依存する方が相互運用性が高い可能性があります。

multipart メディアタイプのエンコーディング

リクエストボディとしてフォームを転送する際、multipart/form-data を Content-Type として使用することは一般的です。OpenAPI 2.0 とは異なり、multipart コンテンツを使用する場合、操作への入力パラメーターを定義するために schema が必須です。これは、複雑な構造と複数のファイルアップロードのためのサポートメカニズムをサポートします。

multipart/form-data (RFC7578) では、form-data ディスポジションとその name パラメーターが必須です。RFC7578 がフォームフィールドごとに複数の値を提供することを推奨しているように、配列プロパティは同じ name を複数のパートに適用することで処理されます。非ASCIIパート名に関するガイダンスについては、RFC7578 を参照してください。

他のさまざまな multipart タイプ、特に multipart/mixed (RFC2046) は、特定の Content-Disposition 値を要求も禁止もしません。つまり、使用されるすべての値が関連するすべてのソフトウェアでサポートされていることを確認するために注意が必要です。現在、multipart/mixed のようなメディアタイプで、名前のない、順序付けられたパートとスキーマプロパティを関連付けることはできませんが、Content-Disposition: form-data が name パラメーターと共に使用される場合、実装はそのようなタイプをサポートすることを選択しても構いません。

一般的に multipart メディアタイプ (RFC2046) および特に multi-part/form-data (RFC7578) で使用できるヘッダーには重大な制限があることに注意してください。

HTTP でバイナリデータがサポートされている multipart/form-data では、Content-Transfer-Encoding が非推奨である (RFC7578) ことにも注意してください。

+マルチパートフィールドに contentEncoding を使用することは、Content-Transfer-Encoding を含む headers フィールドを持つ Encoding Object を、contentEncoding で使用される値を要求するスキーマで指定することと同等です。 +Encoding Object の headers フィールドに Content-Transfer-Encoding が含まれており、そのスキーマが contentEncoding の値を許可しないマルチパートフィールドで contentEncoding が使用された場合、シリアル化と解析の結果は未定義です。

バイナリデータの処理に記載されているように、Encoding Object の contentType (明示的に設定されているか、デフォルト値のルールによって暗黙的に設定されているかに関わらず) が Schema Object の contentMediaType と一致しない場合、contentMediaType は無視されます。このため、また Encoding Object の contentType のデフォルトルールが Schema Object の contentMediaType を考慮しないため、Encoding Object で contentMediaType を使用することは推奨されません。

フォームメディアタイプのパーセントエンコーディングに関する詳細な考察については、付録Eを参照してください。

例: 基本的なマルチパートフォーム

encoding フィールドが使用されていない場合、エンコーディングは Encoding Object のデフォルトによって決定されます。

requestBody:
  content:
    multipart/form-data:
      schema:
        type: object
        properties:
          id:
            # default for primitives without a special format is text/plain
            type: string
            format: uuid
          profileImage:
            # default for string with binary format is `application/octet-stream`
            type: string
            format: binary
          addresses:
            # default for arrays is based on the type in the `items`
            # subschema, which is an object, so `application/json`
            type: array
            items:
              $ref: '#/components/schemas/Address'

例: エンコーディングオブジェクトを使用したマルチパートフォーム

encoding を使用すると、バイナリデータに特定の型を設定したり、複雑な値に非 JSON 形式を設定したりできます。また、各パートのヘッダーを記述することもできます。

requestBody:
  content:
    multipart/form-data:
      schema:
        type: object
        properties:
          id:
            # default is `text/plain`
            type: string
            format: uuid
          addresses:
            # default based on the `items` subschema would be
            # `application/json`, but we want these address objects
            # serialized as `application/xml` instead
            description: addresses in XML format
            type: array
            items:
              $ref: '#/components/schemas/Address'
          profileImage:
            # default is application/octet-stream, but we can declare
            # a more specific image type or types
            type: string
            format: binary
      encoding:
        addresses:
          # require XML Content-Type in utf-8 encoding
          # This is applied to each address part corresponding
          # to each address in he array
          contentType: application/xml; charset=utf-8
        profileImage:
          # only accept png or jpeg
          contentType: image/png, image/jpeg
          headers:
            X-Rate-Limit-Limit:
              description: The number of allowed requests in the current period
              schema:
                type: integer

例: 複数ファイルを含むマルチパートフォーム

RFC7578 に従って、単一のフォームフィールドに対する複数のファイルは、各ファイルのパートに同じ名前 (この例では file) を使用してアップロードされます。

requestBody:
  content:
    multipart/form-data:
      schema:
        properties:
          # The property name 'file' will be used for all files.
          file:
            type: array
            items: {}

Encoding Object の contentType フィールドのドキュメントで示されているように、items の空のスキーマは application/octet-stream のメディアタイプを示します。

応答オブジェクト

操作の予期される応答のコンテナ。コンテナは HTTP 応答コードを予期される応答にマップします。

ドキュメントは、事前にわからない可能性があるため、すべての可能なHTTP応答コードをカバーする必要があるとは限りません。ただし、ドキュメントは成功した操作応答と既知のエラーをカバーすることが期待されます。

default は、Responses Object によって個別にカバーされていないすべての HTTP コードのデフォルトの Response Object として使用される場合があります。

Responses Object は少なくとも1つの応答コードを含まなければならず、1つの応答コードのみが提供される場合は、それが成功した操作呼び出しの応答であるべきです。

固定フィールド

フィールド名	タイプ	説明
デフォルト	Response Object | Reference Object	特定の HTTP レスポンスコードのために宣言されたもの以外のレスポンスのドキュメント。このフィールドは、未宣言のレスポンスをカバーするために使用します。

パターンフィールド

フィールドパターン	タイプ	説明
HTTP ステータスコード	Response Object | Reference Object	任意のHTTPステータスコードをプロパティ名として使用できますが、そのHTTPステータスコードの予期される応答を記述するために、コードごとに1つのプロパティのみが使用されます。このフィールドは、JSONとYAMLの互換性のために引用符で囲む必要があります（例：「200」）。応答コードの範囲を定義するには、このフィールドに大文字のワイルドカード文字Xを含めることができます。たとえば、2XXは200から299までのすべての応答コードを表します。許可されている範囲定義は、1XX、2XX、3XX、4XX、および5XXのみです。応答が明示的なコードを使用して定義されている場合、そのコードの明示的なコード定義は範囲定義よりも優先されます。

このオブジェクトは仕様拡張で拡張されてもよい。

Responses Object の例

成功した操作に対する200応答と、その他の（エラーを意味する）デフォルト応答

{
  "200": {
    "description": "a pet to be returned",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/Pet"
        }
      }
    }
  },
  "default": {
    "description": "Unexpected error",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ErrorModel"
        }
      }
    }
  }
}

'200':
  description: a pet to be returned
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/Pet'
default:
  description: Unexpected error
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/ErrorModel'

Response Object

API 操作からの単一の応答を記述します。これには、設計時、応答に基づいた操作への静的な links が含まれます。

固定フィールド

フィールド名	タイプ	説明
説明	文字列	必須。応答の説明。CommonMark 構文をリッチテキスト表現に使用してもよい。
ヘッダー	Map[string, Header Object | Reference Object]	ヘッダー名をその定義にマッピングします。RFC7230 はヘッダー名が大文字と小文字を区別しないと規定しています。応答ヘッダーが "Content-Type" という名前で定義されている場合、それは無視されます。
コンテンツ	Map[string, Media Type Object]	潜在的な応答ペイロードの記述を含むマップ。キーはメディアタイプまたはメディアタイプレンジであり、値はそれを記述します。複数のキーに一致する応答の場合、最も具体的なキーのみが適用されます。例: "text/plain" は "text/*" をオーバーライドします。
リンク	Map[string, Link Object | Reference Object]	応答からたどることができる操作リンクのマップ。マップのキーは、Component Objects の命名制約に従うリンクの短い名前です。

このオブジェクトは仕様拡張で拡張されてもよい。

Response Object の例

複雑な型の配列の応答

{
  "description": "A complex object array response",
  "content": {
    "application/json": {
      "schema": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/VeryComplexType"
        }
      }
    }
  }
}

description: A complex object array response
content:
  application/json:
    schema:
      type: array
      items:
        $ref: '#/components/schemas/VeryComplexType'

文字列型を持つ応答

{
  "description": "A simple string response",
  "content": {
    "text/plain": {
      "schema": {
        "type": "string"
      }
    }
  }
}

description: A simple string response
content:
  text/plain:
    schema:
      type: string

ヘッダー付きのプレーンテキスト応答

{
  "description": "A simple string response",
  "content": {
    "text/plain": {
      "schema": {
        "type": "string"
      },
      "example": "whoa!"
    }
  },
  "headers": {
    "X-Rate-Limit-Limit": {
      "description": "The number of allowed requests in the current period",
      "schema": {
        "type": "integer"
      }
    },
    "X-Rate-Limit-Remaining": {
      "description": "The number of remaining requests in the current period",
      "schema": {
        "type": "integer"
      }
    },
    "X-Rate-Limit-Reset": {
      "description": "The number of seconds left in the current period",
      "schema": {
        "type": "integer"
      }
    }
  }
}

description: A simple string response
content:
  text/plain:
    schema:
      type: string
    example: 'whoa!'
headers:
  X-Rate-Limit-Limit:
    description: The number of allowed requests in the current period
    schema:
      type: integer
  X-Rate-Limit-Remaining:
    description: The number of remaining requests in the current period
    schema:
      type: integer
  X-Rate-Limit-Reset:
    description: The number of seconds left in the current period
    schema:
      type: integer

戻り値のない応答

{
  "description": "object created"
}

description: object created

コールバックオブジェクト

親操作に関連する帯域外コールバックの可能性のあるマップ。マップ内の各値は、API プロバイダーによって開始される可能性のあるリクエストと期待される応答のセットを記述する Path Item Object です。Path Item Object を識別するために使用されるキー値は、コールバック操作に使用する URL を識別するためにランタイムで評価される式です。

別のAPI呼び出しとは独立してAPIプロバイダーからの着信リクエストを記述するには、webhooksフィールドを使用します。

パターンフィールド

フィールドパターン	タイプ	説明
{式}	パス項目オブジェクト	コールバックリクエストと期待されるレスポンスを定義するために使用される Path Item Object。完全な例が入手可能です。

このオブジェクトは仕様拡張で拡張されてもよい。

キー式

パスアイテムオブジェクトを識別するキーは、ランタイム HTTP リクエスト/レスポンスのコンテキストで評価され、コールバックリクエストに使用される URL を識別できるランタイム式です。単純な例としては $request.body#/url が考えられます。ただし、ランタイム式を使用すると、完全な HTTP メッセージにアクセスできます。これには、JSON ポインター RFC6901 が参照できるボディの任意の部分へのアクセスが含まれます。

例えば、以下のHTTPリクエストが与えられた場合

POST /subscribe/myevent?queryUrl=https://clientdomain.com/stillrunning HTTP/1.1
Host: example.org
Content-Type: application/json
Content-Length: 188

{
  "failedUrl": "https://clientdomain.com/failed",
  "successUrls": [
    "https://clientdomain.com/fast",
    "https://clientdomain.com/medium",
    "https://clientdomain.com/slow"
  ]
}

結果として

201 Created
Location: https://example.org/subscription/1

以下の例は、コールバック操作に eventType というパスパラメーターと queryUrl というクエリパラメーターがあると仮定した場合の、さまざまな式の評価方法を示しています。

式	値
$url	https://example.org/subscribe/myevent?queryUrl=https://clientdomain.com/stillrunning
$method	POST
$request.path.eventType	myevent
$request.query.queryUrl	https://clientdomain.com/stillrunning
$request.header.content-type	application/json
$request.body#/failedUrl	https://clientdomain.com/failed
$request.body#/successUrls/1	https://clientdomain.com/medium
$response.header.Location	https://example.org/subscription/1

Callback Object の例

次の例では、ユーザーが提供した queryUrl クエリ文字列パラメーターを使用してコールバック URL を定義しています。これは webhook に似ていますが、コールバックが queryUrl を送信した最初の要求によってのみ発生するという点で異なります。

myCallback:
  '{$request.query.queryUrl}':
    post:
      requestBody:
        description: Callback payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SomePayload'
      responses:
        '200':
          description: callback successfully processed

次の例は、サーバーがハードコードされているが、クエリ文字列パラメーターがリクエストボディの id および email プロパティから入力されるコールバックを示しています。

transactionCallback:
  'http://notificationServer.com?transactionId={$request.body#/id}&email={$request.body#/email}':
    post:
      requestBody:
        description: Callback payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SomePayload'
      responses:
        '200':
          description: callback successfully processed

Example Object

基本的な summary と description メタデータを持つ内部または外部の例の値をグループ化するオブジェクト。このオブジェクトは通常、examples (複数形) という名前のフィールドで使用され、参照やメタデータをサポートしない古い example (単数形) フィールドの 参照可能な 代替手段です。

例を使用すると、OpenAPI 内のプロパティ、パラメーター、およびオブジェクトの使用方法をデモンストレーションできます。

固定フィールド

フィールド名	タイプ	説明
概要	文字列	例の短い説明。
説明	文字列	例の長い説明。CommonMark 構文をリッチテキスト表現に使用してもよい。
値	任意	埋め込みリテラル例。value フィールドと externalValue フィールドは相互に排他的です。JSON または YAML で自然に表現できないメディアタイプの例を表現するには、文字列値を使用して例を含め、必要に応じてエスケープします。
外部値	文字列	リテラル例を識別するURI。これにより、JSONまたはYAMLドキュメントに簡単に含めることができない例を参照する機能が提供されます。valueフィールドとexternalValueフィールドは相互に排他的です。相対参照を解決するためのルールを参照してください。

このオブジェクトは仕様拡張で拡張されてもよい。

すべての場合において、例の値は関連するスキーマと互換性があるべきです。ツール実装は、互換性を自動的に検証し、互換性がない場合は例の値を拒否することを選択しても構いません。

例の操作

Example Object は Parameter Objects と Media Type Objects の両方で使用できます。どちらのオブジェクトでも、これは examples (複数形) フィールドを介して行われます。ただし、例を提供する方法は他にもいくつかあります。両方のオブジェクトで examples と相互排他的な example (単数形) フィールドと、両方のオブジェクトの schema フィールドに現れる Schema Object 内の 2 つのキーワード (非推奨の単数形 example と、例の配列を受け取る現在の複数形 examples) です。これらの各フィールドには、わずかに異なる考慮事項があります。

Schema Object のフィールドは、パラメータとして、またはメディアタイプ表現内でどのようにフォーマットされるかに関わらず、例の値を示すために使用されます。examples 配列は JSON Schema の一部であり、Schema Object に例を含める推奨される方法ですが、example は OpenAPI Specification の古いバージョンとの互換性のためだけに保持されています。

Parameter または Media Type Object の相互排他的なフィールドは、スキーマに一致し、かつシリアル化されたパラメーターとして、またはメディアタイプ表現内で表示されるようにフォーマットされるべき例の値を表示するために使用されます。正確なシリアル化とエンコーディングは、Parameter Object のさまざまなフィールド、または Media Type Object の Encoding Object のフィールドによって決定されます。これらのフィールドを使用する例は、データの最終的なシリアル化された形式を表すため、対応する Schema Object の example をオーバーライドするものとします。

Parameter または Media Type Object の単数形 example フィールドは、単純な例には簡潔で便利ですが、examples 配下の Example Object を使用するよりも他の利点はありません。

一部の例は JSON または YAML で直接表現できません。例を提供するためのこれら 3 つの方法すべてについて、これらは、OpenAPI Description を構成するドキュメントの JSON または YAML 形式で文字列が有効になるために必要なエスケープを使用して、文字列値として表示できます。Example Object を使用すると、このような値は externalValue フィールドを介して処理することもできます。

Example Object の例

リクエストボディ内

requestBody:
  content:
    'application/json':
      schema:
        $ref: '#/components/schemas/Address'
      examples:
        foo:
          summary: A foo example
          value:
            foo: bar
        bar:
          summary: A bar example
          value:
            bar: baz
    application/xml:
      examples:
        xmlExample:
          summary: This is an example in XML
          externalValue: https://example.org/examples/address-example.xml
    text/plain:
      examples:
        textExample:
          summary: This is a text example
          externalValue: https://foo.bar/examples/address-example.txt

パラメータ内

parameters:
  - name: zipCode
    in: query
    schema:
      type: string
      format: zip-code
    examples:
      zip-example:
        $ref: '#/components/examples/zip-example'

応答内

responses:
  '200':
    description: your car appointment has been booked
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/SuccessResponse'
        examples:
          confirmation-success:
            $ref: '#/components/examples/confirmation-success'

JSON文字列の2つの異なる使用例

まず、JSON文字列（文字列を含むオブジェクトではない）だけのリクエストまたはレスポンスボディ

"application/json": {
  "schema": {
    "type": "string"
  },
  "examples": {
    "jsonBody": {
      "description": "A body of just the JSON string \"json\"",
      "value": "json"
    }
  }
}

application/json:
  schema:
    type: string
  examples:
    jsonBody:
      description: 'A body of just the JSON string "json"'
      value: json

上記の例では、シリアル化された JSON 値を JSON 文字列に詰め込む ("\"json\"" のように見える) のではなく、JSON 文字列 (または任意の JSON 値) をそのまま表示できます。

対照的に、URLスタイルのフォームボディ内にエンコードされたJSON文字列

"application/x-www-form-urlencoded": {
  "schema": {
    "type": "object",
    "properties": {
      "jsonValue": {
        "type": "string"
      }
    }
  },
  "encoding": {
    "jsonValue": {
      "contentType": "application/json"
    }
  },
  "examples": {
    "jsonFormValue": {
      "description": "The JSON string \"json\" as a form value",
      "value": "jsonValue=%22json%22"
    }
  }
}

application/x-www-form-urlencoded:
  schema:
    type: object
    properties:
      jsonValue:
        type: string
  encoding:
    jsonValue:
      contentType: application/json
  examples:
    jsonFormValue:
      description: 'The JSON string "json" as a form value'
      value: jsonValue=%22json%22

この例では、JSON 文字列は URL フォーム値にエンコードされる前にシリアル化する必要があったため、例には JSON シリアル化の一部である引用符が含まれており、それらは URL パーセントエンコードされています。

リンクオブジェクト

Link Object は、応答に対する設計時のリンクの可能性を表します。リンクが存在しても、呼び出し元が正常に呼び出す能力を保証するものではなく、むしろ、応答と他の操作間の既知の関係とトラバースメカニズムを提供します。

（応答ペイロード内で提供されるリンクである）動的なリンクとは異なり、OAS のリンクメカニズムはランタイム応答でのリンク情報を必要としません。

リンクを計算し、それらを実行するための指示を提供するために、ランタイム式が操作内の値にアクセスし、それらをリンクされた操作を呼び出す際のパラメーターとして使用するために使用されます。

固定フィールド

フィールド名	タイプ	説明
操作参照	文字列	OAS 操作への URI 参照。このフィールドは operationId フィールドと相互排他的であり、Operation Object を指す必要があります。相対的な operationRef 値は、OpenAPI Description に既存の Operation Object を見つけるために使用される場合があります。
操作 ID	文字列	一意の operationId で定義された、既存の、解決可能な OAS 操作の名前。このフィールドは operationRef フィールドと相互排他的です。
パラメーター	Map[string, Any | {式}]	operationIdで指定された、またはoperationRefで識別された操作に渡すパラメータを表すマップ。キーは使用されるパラメータ名（オプションでパラメータの場所で修飾、例：パス内のidパラメータの場合path.id）であり、値は定数または評価されてリンクされた操作に渡される式です。
リクエストボディ	任意 | {式}	ターゲット操作を呼び出すときにリクエストボディとして使用するリテラル値または{式}。
説明	文字列	リンクの説明。CommonMark 構文をリッチテキスト表現に使用してもよい。
サーバー	サーバーオブジェクト	ターゲット操作によって使用されるサーバーオブジェクト。

このオブジェクトは仕様拡張で拡張されてもよい。

リンクされた操作は、operationRef または operationId のいずれかを使用して識別されなければなりません。識別または参照された操作は一意でなければならず、operationId の場合、OpenAPI Description (OAD) のスコープ内で解決されなければなりません。名前の衝突の可能性のため、operationRef 構文がマルチドキュメント OAD で推奨されます。ただし、操作の使用は Paths Object の URL パステンプレートに依存するため、OAD 内で複数回参照される Path Item Object からの操作は明確に解決できません。このような曖昧なケースでは、結果の動作は実装定義であり、エラーが発生する場合があります。

ランタイム式の構文に一致する定数値を parameters に提供することはできないことに注意してください。あいまいなパラメーター名を持つことは可能ですが、たとえば name: "id", in: "path" と name: "path.id", in: "query" のように、これは推奨されませんし、動作は実装定義ですが、実装は修飾された解釈 (パスパラメーターとしての path.id) を優先すべきです。なぜなら、名前は常に修飾してあいまいさを解消できるからです (たとえば、クエリパラメーターには query.path.id を使用する)。

例

$request.path.id を使用してリクエストパラメーターをリンクされた操作に渡すリクエスト操作からリンクを計算します。

paths:
  /users/{id}:
    parameters:
      - name: id
        in: path
        required: true
        description: the user identifier, as userId
        schema:
          type: string
    get:
      responses:
        '200':
          description: the user being returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  uuid: # the unique user id
                    type: string
                    format: uuid
          links:
            address:
              # the target link operationId
              operationId: getUserAddress
              parameters:
                # get the `id` field from the request path parameter named `id`
                userid: $request.path.id
  # the path item of the linked operation
  /users/{userid}/address:
    parameters:
      - name: userid
        in: path
        required: true
        description: the user identifier, as userId
        schema:
          type: string
    # linked operation
    get:
      operationId: getUserAddress
      responses:
        '200':
          description: the user's address

ランタイム式の評価に失敗した場合、ターゲット操作にはパラメーター値は渡されません。

応答ボディの値を使用して、リンクされた操作を駆動することができます。

links:
  address:
    operationId: getUserAddressByUUID
    parameters:
      # get the `uuid` field from the `uuid` field in the response body
      userUuid: $response.body#/uuid

クライアントは自己の裁量で全てのリンクをたどります。リンクが存在するからといって、そのリンクを正常に呼び出す権限や能力が保証されるわけではありません。

operationRef の例

operationIdへの参照は不可能かもしれないため（operationIdはOperation Objectのオプションフィールド）、相対operationRefを通じて参照を行うこともできます。

links:
  UserRepositories:
    # returns array of '#/components/schemas/repository'
    operationRef: '#/paths/~12.0~1repositories~1%7Busername%7D/get'
    parameters:
      username: $response.body#/username

または URI operationRef

links:
  UserRepositories:
    # returns array of '#/components/schemas/repository'
    operationRef: https://na2.gigantic-server.com/#/paths/~12.0~1repositories~1%7Busername%7D/get
    parameters:
      username: $response.body#/username

operationRef の使用では、JSON ポインターを使用する場合、エスケープされたスラッシュが必要であり、URI フラグメントとして JSON ポインターを使用する場合、{ と } をそれぞれ %7B と %7D に URL エンコードする必要があることに注意してください。

ランタイム式

ランタイム式は、実際の API 呼び出しの HTTP メッセージ内でのみ利用可能な情報に基づいて値を定義することを可能にします。このメカニズムは、Link Objects と Callback Objects で使用されます。

ランタイム式は以下の ABNF 構文で定義されます。

    expression = "$url" / "$method" / "$statusCode" / "$request." source / "$response." source
    source     = header-reference / query-reference / path-reference / body-reference
    header-reference = "header." token
    query-reference  = "query." name
    path-reference   = "path." name
    body-reference   = "body" ["#" json-pointer ]
    json-pointer    = *( "/" reference-token )
    reference-token = *( unescaped / escaped )
    unescaped       = %x00-2E / %x30-7D / %x7F-10FFFF
                    ; %x2F ('/') and %x7E ('~') are excluded from 'unescaped'
    escaped         = "~" ( "0" / "1" )
                    ; representing '~' and '/', respectively
    name = *( CHAR )
    token = 1*tchar
    tchar = "!" / "#" / "$" / "%" / "&" / "'" / "*" / "+" / "-" / "."
          / "^" / "_" / "`" / "|" / "~" / DIGIT / ALPHA

ここで、json-pointer は RFC6901 から、char は RFC7159 から、token は RFC7230 から取得されています。

name 識別子は大文字と小文字を区別しますが、token は区別しません。

以下の表は、ランタイム式の例と、値での使用例を示しています。

例

ソースの場所	例の式	ノート
HTTP メソッド	$method	$method に許可される値は、HTTP 操作に対するものです。
リクエストされたメディアタイプ	$request.header.accept
リクエストパラメータ	$request.path.id	リクエストパラメーターは親操作の parameters セクションで宣言されなければ評価できません。これにはリクエストヘッダーも含まれます。
リクエストボディのプロパティ	$request.body#/user/uuid	ペイロードを受け入れる操作では、requestBody の一部または全体を参照できます。
リクエストURL	$url
応答値	$response.body#/status	ペイロードを返す操作では、レスポンスボディの一部または全体を参照できます。
応答ヘッダー	$response.header.Server	単一のヘッダー値のみ利用可能です。

ランタイム式は参照された値の型を保持します。式は {} 波括弧で囲むことで文字列値に埋め込むことができます。

Header Object

HTTP レスポンスとmultipart 表現の個々のパートに対する単一のヘッダーを記述します。どのヘッダーを記述できるかの制限については、関連するResponse ObjectとEncoding Objectのドキュメントを参照してください。

Header Object は Parameter Object の構造に従い、schema または content の有無に基づいてシリアル化戦略を決定しますが、以下の変更点があります。

1. name は指定してはならず、対応する headers マップで与えられます。
2. in は指定してはならず、暗黙的に header になります。
3. ロケーションによって影響を受けるすべての特性は、header のロケーションに適用可能でなければなりません (例: style)。これは、allowEmptyValue と allowReserved を使用してはならず、style を使用する場合は "simple" に限定しなければならないことを意味します。

固定フィールド

共通固定フィールド

これらのフィールドは、contentまたはschemaのどちらでも使用できます。

フィールド名	タイプ	説明
説明	文字列	ヘッダーの簡単な説明。使用例を含むことができます。CommonMark 構文をリッチテキスト表現に使用してもよい。
必須	ブール値	このヘッダーが必須かどうかを決定します。デフォルト値は false です。
非推奨	ブール値	ヘッダーが非推奨であり、使用を中止すべきであることを指定します。デフォルト値は false です。

このオブジェクトは仕様拡張で拡張されてもよい。

schemaで使用するための固定フィールド

より単純なシナリオでは、schemaとstyleがヘッダーの構造と構文を記述できます。exampleまたはexamplesがschemaフィールドとともに提供される場合、その例はヘッダーに規定されたシリアル化戦略に従う必要があります。

値にパラメーター (; の後に続く name=value ペア) が含まれるヘッダー、または値に URL セーフでない文字が含まれる可能性があるヘッダーの場合、schema を使用したシリアル化は推奨されません。詳細については、付録 D を参照してください。

example または examples が schema フィールドと共に提供される場合、例は指定されたスキーマに一致し、ヘッダーに規定されたシリアル化戦略に従う必要があります。example と examples フィールドは相互排他的であり、どちらかが存在する場合はスキーマ内の example をオーバーライドするものとします。

フィールド名	タイプ	説明
スタイル	文字列	ヘッダー値がどのようにシリアル化されるかを記述します。デフォルト値（およびヘッダーの唯一の有効な値）は "simple" です。
展開	ブール値	これが true の場合、array または object 型のヘッダー値は、配列の項目またはマップのキーと値のペアをコンマ区切りでリストした単一のヘッダーを生成します。スタイル例を参照してください。他のデータ型の場合、このフィールドは効果がありません。デフォルト値は false です。
スキーマ	Schema Object | Reference Object	ヘッダーに使用される型を定義するスキーマ。
例	任意	ヘッダーの潜在的な値の例。例の操作を参照してください。
例	Map[ string, Example Object | Reference Object]	ヘッダーの潜在的な値の例。例の操作を参照してください。

追加のガイダンスについては、付録C：RFC6570ベースのシリアライゼーションの使用も参照してください。

contentで使用するための固定フィールド

より複雑なシナリオでは、content フィールドでヘッダーのメディアタイプとスキーマを定義し、その使用例を示すことができます。schema 戦略が適切でないヘッダーの場合、text/plain メディアタイプで content を使用することが推奨されます。

フィールド名	タイプ	説明
コンテンツ	Map[string, Media Type Object]	ヘッダーの表現を含むマップ。キーはメディアタイプであり、値はそれを記述します。マップは1つのエントリのみを含む必要があります。

Header Object の例

型 integer の単純なヘッダー

"X-Rate-Limit-Limit": {
  "description": "The number of allowed requests in the current period",
  "schema": {
    "type": "integer"
  }
}

X-Rate-Limit-Limit:
  description: The number of allowed requests in the current period
  schema:
    type: integer

強力な ETag ヘッダー (W/ ではなく " で始まる値) の存在を要求します。content の使用に注意してください。schema と style を使用すると、" を %22 にパーセントエンコードする必要があるためです。

"ETag": {
  "required": true,
  "content": {
    "text/plain": {
      "schema": {
        "type": "string",
        "pattern": "^\""
      }
    }
  }
}

ETag:
  required: true
  content:
    text/plain:
      schema:
        type: string
        pattern: ^"

タグオブジェクト

Operation Object で使用される単一のタグにメタデータを追加します。Operation Object インスタンスで定義されたタグごとに Tag Object を持つことは必須ではありません。

固定フィールド

フィールド名	タイプ	説明
名前	文字列	必須。タグの名前。
説明	文字列	タグの説明。CommonMark 構文をリッチテキスト表現に使用してもよい。
外部ドキュメント	外部ドキュメントオブジェクト	このタグの追加の外部ドキュメント。

このオブジェクトは仕様拡張で拡張されてもよい。

Tag Object の例

{
  "name": "pet",
  "description": "Pets operations"
}

name: pet
description: Pets operations

Reference Object

OpenAPI Description 内外の他のコンポーネントを参照できるようにするシンプルなオブジェクト。

$ref 文字列値には、参照される値を識別する URI RFC3986 が含まれています。

相対参照を解決するためのルールを参照してください。

固定フィールド

フィールド名	タイプ	説明
$ref	文字列	必須。参照識別子。これは URI の形式である必要があります。
概要	文字列	デフォルトでは参照されるコンポーネントの概要を上書きするべき短い概要。参照されるオブジェクト型が summary フィールドを許可しない場合、このフィールドは効果がありません。
説明	文字列	デフォルトでは、参照されるコンポーネントの説明を上書きすべき説明。CommonMark 構文をリッチテキスト表現に使用してもよい。参照されるオブジェクト型が description フィールドを許可しない場合、このフィールドは効果がない。

このオブジェクトは追加のプロパティで拡張することはできず、追加されたプロパティはすべて無視されます。

追加プロパティに対するこの制限は、Reference Objects と $ref キーワードを含む Schema Objects の違いであることに注意してください。

Reference Object の例

{
  "$ref": "#/components/schemas/Pet"
}

$ref: '#/components/schemas/Pet'

相対スキーマドキュメントの例

{
  "$ref": "Pet.json"
}

$ref: Pet.yaml

埋め込みスキーマを含む相対ドキュメントの例

{
  "$ref": "definitions.json#/Pet"
}

$ref: definitions.yaml#/Pet

スキーマオブジェクト

Schema Object は、入力および出力データ型の定義を可能にします。これらの型はオブジェクトであるだけでなく、プリミティブや配列も可能です。このオブジェクトは JSON Schema Specification Draft 2020-12 のスーパーセットです。任意のインスタンスを検証できる空のスキーマは boolean 値 true で表すことができ、どのインスタンスも検証できないスキーマは boolean 値 false で表すことができます。

キーワードの詳細については、JSON Schema Core および JSON Schema Validation を参照してください。

特に明記されていない限り、キーワード定義は JSON Schema のものに従い、追加のセマンティクスは追加されません。これには、$schema、$id、$ref、$dynamicRef などのキーワードが URL ではなく URI であることも含まれます。JSON Schema がアプリケーションによって動作が定義されると示している場合 (アノテーションなど)、OAS もセマンティクスの定義を OpenAPI ドキュメントを使用するアプリケーションに委ねます。

JSON スキーマキーワード

OpenAPI Schema Object の 方言は、JSON Schema Specification Draft 2020-12 の 汎用メタスキーマで指定されている語彙に加えて、OAS 基本語彙を必須とするものとして定義されています。

この仕様のこのバージョンの OpenAPI スキーマオブジェクト方言は、URI https://spec.openapis.org/oas/3.1/dialect/base ("OAS 方言スキーマ ID") によって識別されます。

以下のキーワードは JSON Schema 仕様から取得されていますが、その定義は OAS によって拡張されています。

• description - CommonMark 構文をリッチテキスト表現に使用してもよい。
• format - 詳細については、データ型フォーマットを参照してください。JSON Schema で定義されたフォーマットに依存しつつ、OAS はいくつかの追加の事前定義フォーマットを提供します。

OAS 方言を構成する JSON Schema キーワードに加えて、Schema Object は他の語彙からのキーワード、または完全に任意のプロパティをサポートします。

JSON Schema の実装は、OpenAPI Specification の基本語彙によって定義されたキーワードを 不明なキーワードとして扱うことを選択する場合があります。これは、$vocabulary の値が false である $vocabulary を持つ OAS 方言に含まれているためです。OAS 基本語彙は、以下のキーワードで構成されます。

固定フィールド

フィールド名	タイプ	説明
識別子	識別子オブジェクト	多態性のサポートを追加します。識別子は、ペイロードが満たすべきスキーマのセットのうちどれであるかを決定するために使用されます。詳細については、合成と継承を参照してください。
XML	XML オブジェクト	これはプロパティスキーマでのみ使用できます。ルートスキーマには影響しません。このプロパティの XML 表現を記述するための追加のメタデータを追加します。
外部ドキュメント	外部ドキュメントオブジェクト	このスキーマに関する追加の外部ドキュメント。
例	任意	このスキーマのインスタンス例を含めるための自由形式フィールド。JSON または YAML で自然に表現できない例を表現するには、必要に応じてエスケープして文字列値で例を含めることができます。 非推奨: example フィールドは JSON Schema の examples キーワードに置き換えられ、非推奨になりました。example の使用は推奨されず、この仕様の将来のバージョンでは削除される可能性があります。

このオブジェクトは 仕様拡張で拡張できますが、前述のとおり、追加プロパティはこのオブジェクト内で x- プレフィックスを省略してもよいです。

注釈付きの拡張検証

JSON Schema Draft 2020-12 は、アノテーションの収集をサポートしており、認識されないキーワードをアノテーションとして扱うことも含まれます。OAS の実装は、宣言された JSON Schema 語彙の一部として認識されない拡張を含むそのようなアノテーションを、さらなる検証の基礎として使用しても構いません。JSON Schema Draft 2020-12 は拡張に x- プレフィックスを要求しないことに注意してください。

非検証制約キーワード

format キーワード (デフォルトのフォーマットアノテーション語彙を使用する場合) および contentMediaType、contentEncoding、および contentSchema キーワードはデータに制約を定義しますが、直接検証されるのではなくアノテーションとして扱われます。拡張検証は、これらの制約を強制する方法の1つです。

readOnly および writeOnly の検証

readOnly と writeOnly キーワードはアノテーションであり、JSON Schema は検証するデータがどのように使用されているかを認識していません。これらのキーワードの検証は、アノテーション、読み取りまたは書き込みの方向、および (関連する場合) フィールドの現在の値をチェックすることで行われる場合があります。JSON Schema Validation Draft 2020-12 §9.4 はこれらのキーワードの期待値を定義しており、リソース (「所有権者」として記述) は readOnly フィールドを無視するか、エラーとして扱うことができると述べています。

必須かつ読み取り専用のフィールドは、PUTでreadOnly: true制約を無視することが有益な場合の例です。特に値が変更されていない場合は。これにより、GETでフィールドを正しく要求し、PUTでも同じ表現とスキーマを使用することができます。読み取り専用フィールドが必須でない場合でも、それらを削除するのはクライアントにとって負担であり、特にJSONデータが複雑であったり深くネストされている場合はなおさらです。

readOnly の動作は、この仕様のバージョン 3.0 で指定されたものとは異なることに特に注意してください。

データモデリング技術

構成と継承（多態性）

OpenAPI Specification は、JSON Schema の allOf キーワードを使用してモデル定義を結合および拡張することを可能にし、実質的にモデル構成を提供します。allOf は、独立して検証されるが、結合して単一のオブジェクトを構成するオブジェクト定義の配列を受け取ります。

組成はモデルの拡張性を提供しますが、モデル間の階層を意味するものではありません。多態性をサポートするために、OpenAPI Specification は discriminator フィールドを追加します。使用される場合、discriminator は、どのスキーマ定義がモデルの構造を検証することが期待されるかを示すプロパティの名前を示します。したがって、discriminator フィールドは必須フィールドである必要があります。継承するインスタンスの discriminator の値を定義する方法は2つあります。

• スキーマ名を使用します。
• 新しい値でプロパティをオーバーライドすることにより、スキーマ名をオーバーライドします。新しい値が存在する場合、これはスキーマ名よりも優先されます。

汎用（テンプレート）データ構造

実装は、JSON Schema の動的参照機能を使用して汎用またはテンプレートデータ構造の定義をサポートする場合があります。

• $dynamicAnchor は、$dynamicRef が解決できる一連の可能なスキーマ (デフォルトのプレースホルダー スキーマを含む) を識別します。
• $dynamicRef は、JSON Schema 仕様に記述されているように、スキーマのエントリポイントから参照へのパスで最初に見つかった一致する $dynamicAnchor に解決されます。

以下の「Schema Object Examples」セクションに例が含まれており、詳細については Learn OpenAPI サイトの「動的参照」ページで見つけることができます。

注釈付き列挙

Schema Object の enum キーワードは、個々の値に説明やその他の情報を関連付けることを許可していません。

実装は、oneOf または anyOf を認識することをサポートする場合があります。ここで、キーワードの配列内の各サブスキーマは const キーワードと、title や description などのアノテーションで構成されており、追加情報を持つ列挙型として扱われます。このパターンの JSON Schema で要求される範囲を超える正確な動作は、実装に依存します。

XML モデリング

xml フィールドを使用すると、JSON 定義を XML に変換する際に追加の定義を行うことができます。XML Object には、利用可能なオプションに関する追加情報が含まれています。

スキーマ方言の指定

ツールが、与えられたリソースがどのダイアレクトまたはメタスキーマで処理されることを希望するか (JSON Schema Core、JSON Schema Validation、OpenAPI Schema ダイアレクト、またはカスタムメタスキーマ) を判断できることは重要です。

$schema キーワードは、スキーマリソースルートである任意の Schema Object に存在してもよく、存在する場合はスキーマを処理する際に使用すべきダイアレクトを決定するために使用されなければなりません。これにより、デフォルトの Draft 2020-12 のサポートとは異なる JSON Schema の他のドラフトに準拠する Schema Object を使用できます。ツールはOAS ダイアレクトスキーマ IDをサポートしなければならず、$schema の追加の値をサポートしてもよいです。

OAS ドキュメントに含まれるすべての Schema Object に対して、異なるデフォルトの $schema 値を使用できるように、OpenAPI Object 内で jsonSchemaDialect 値を設定できます。このデフォルトが設定されていない場合、これらの Schema Object には OAS ダイアレクトスキーマ ID を使用する必要があります。リソースルート Schema Object 内の $schema の値は常に、任意のデフォルトをオーバーライドします。

$schema を設定しないスタンドアロンの JSON Schema ドキュメント、または 完全なドキュメントではない OpenAPI 説明ドキュメント内の Schema Object の場合、ダイアレクトは OAS ダイアレクトであると仮定すべきです。ただし、最大限の相互運用性のために、OpenAPI 説明の作成者は、そのようなドキュメントで $schema を介してダイアレクトを明示的に設定することを推奨します。

Schema Object の例

プリミティブの例

{
  "type": "string",
  "format": "email"
}

type: string
format: email

単純なモデル

{
  "type": "object",
  "required": ["name"],
  "properties": {
    "name": {
      "type": "string"
    },
    "address": {
      "$ref": "#/components/schemas/Address"
    },
    "age": {
      "type": "integer",
      "format": "int32",
      "minimum": 0
    }
  }
}

type: object
required:
  - name
properties:
  name:
    type: string
  address:
    $ref: '#/components/schemas/Address'
  age:
    type: integer
    format: int32
    minimum: 0

マップ/辞書プロパティを持つモデル

単純な文字列から文字列へのマッピングの場合

{
  "type": "object",
  "additionalProperties": {
    "type": "string"
  }
}

type: object
additionalProperties:
  type: string

文字列からモデルへのマッピングの場合

{
  "type": "object",
  "additionalProperties": {
    "$ref": "#/components/schemas/ComplexModel"
  }
}

type: object
additionalProperties:
  $ref: '#/components/schemas/ComplexModel'

注釈付き列挙を持つモデル

{
  "oneOf": [
    {
      "const": "RGB",
      "title": "Red, Green, Blue",
      "description": "Specify colors with the red, green, and blue additive color model"
    },
    {
      "const": "CMYK",
      "title": "Cyan, Magenta, Yellow, Black",
      "description": "Specify colors with the cyan, magenta, yellow, and black subtractive color model"
    }
  ]
}

oneOf:
  - const: RGB
    title: Red, Green, Blue
    description: Specify colors with the red, green, and blue additive color model
  - const: CMYK
    title: Cyan, Magenta, Yellow, Black
    description: Specify colors with the cyan, magenta, yellow, and black subtractive color model

例付きのモデル

{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "format": "int64"
    },
    "name": {
      "type": "string"
    }
  },
  "required": ["name"],
  "examples": [
    {
      "name": "Puma",
      "id": 1
    }
  ]
}

type: object
properties:
  id:
    type: integer
    format: int64
  name:
    type: string
required:
  - name
examples:
  - name: Puma
    id: 1

構成を持つモデル

{
  "components": {
    "schemas": {
      "ErrorModel": {
        "type": "object",
        "required": ["message", "code"],
        "properties": {
          "message": {
            "type": "string"
          },
          "code": {
            "type": "integer",
            "minimum": 100,
            "maximum": 600
          }
        }
      },
      "ExtendedErrorModel": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ErrorModel"
          },
          {
            "type": "object",
            "required": ["rootCause"],
            "properties": {
              "rootCause": {
                "type": "string"
              }
            }
          }
        ]
      }
    }
  }
}

components:
  schemas:
    ErrorModel:
      type: object
      required:
        - message
        - code
      properties:
        message:
          type: string
        code:
          type: integer
          minimum: 100
          maximum: 600
    ExtendedErrorModel:
      allOf:
        - $ref: '#/components/schemas/ErrorModel'
        - type: object
          required:
            - rootCause
          properties:
            rootCause:
              type: string

ポリモーフィズムをサポートするモデル

{
  "components": {
    "schemas": {
      "Pet": {
        "type": "object",
        "discriminator": {
          "propertyName": "petType"
        },
        "properties": {
          "name": {
            "type": "string"
          },
          "petType": {
            "type": "string"
          }
        },
        "required": ["name", "petType"]
      },
      "Cat": {
        "description": "A representation of a cat. Note that `Cat` will be used as the discriminating value.",
        "allOf": [
          {
            "$ref": "#/components/schemas/Pet"
          },
          {
            "type": "object",
            "properties": {
              "huntingSkill": {
                "type": "string",
                "description": "The measured skill for hunting",
                "default": "lazy",
                "enum": ["clueless", "lazy", "adventurous", "aggressive"]
              }
            },
            "required": ["huntingSkill"]
          }
        ]
      },
      "Dog": {
        "description": "A representation of a dog. Note that `Dog` will be used as the discriminating value.",
        "allOf": [
          {
            "$ref": "#/components/schemas/Pet"
          },
          {
            "type": "object",
            "properties": {
              "packSize": {
                "type": "integer",
                "format": "int32",
                "description": "the size of the pack the dog is from",
                "default": 0,
                "minimum": 0
              }
            },
            "required": ["packSize"]
          }
        ]
      }
    }
  }
}

components:
  schemas:
    Pet:
      type: object
      discriminator:
        propertyName: petType
      properties:
        name:
          type: string
        petType:
          type: string
      required:
        - name
        - petType
    Cat: # "Cat" will be used as the discriminating value
      description: A representation of a cat
      allOf:
        - $ref: '#/components/schemas/Pet'
        - type: object
          properties:
            huntingSkill:
              type: string
              description: The measured skill for hunting
              enum:
                - clueless
                - lazy
                - adventurous
                - aggressive
          required:
            - huntingSkill
    Dog: # "Dog" will be used as the discriminating value
      description: A representation of a dog
      allOf:
        - $ref: '#/components/schemas/Pet'
        - type: object
          properties:
            packSize:
              type: integer
              format: int32
              description: the size of the pack the dog is from
              default: 0
              minimum: 0
          required:
            - packSize

汎用データ構造モデル

{
  "components": {
    "schemas": {
      "genericArrayComponent": {
        "$id": "fully_generic_array",
        "type": "array",
        "items": {
          "$dynamicRef": "#generic-array"
        },
        "$defs": {
          "allowAll": {
            "$dynamicAnchor": "generic-array"
          }
        }
      },
      "numberArray": {
        "$id": "array_of_numbers",
        "$ref": "fully_generic_array",
        "$defs": {
          "numbersOnly": {
            "$dynamicAnchor": "generic-array",
            "type": "number"
          }
        }
      },
      "stringArray": {
        "$id": "array_of_strings",
        "$ref": "fully_generic_array",
        "$defs": {
          "stringsOnly": {
            "$dynamicAnchor": "generic-array",
            "type": "string"
          }
        }
      },
      "objWithTypedArray": {
        "$id": "obj_with_typed_array",
        "type": "object",
        "required": ["dataType", "data"],
        "properties": {
          "dataType": {
            "enum": ["string", "number"]
          }
        },
        "oneOf": [{
          "properties": {
            "dataType": {"const": "string"},
            "data": {"$ref": "array_of_strings"}
          }
        }, {
          "properties": {
            "dataType": {"const": "number"},
            "data": {"$ref": "array_of_numbers"}
          }
        }]
      }
    }
  }
}

components:
  schemas:
    genericArrayComponent:
      $id: fully_generic_array
      type: array
      items:
        $dynamicRef: '#generic-array'
      $defs:
        allowAll:
          $dynamicAnchor: generic-array
    numberArray:
      $id: array_of_numbers
      $ref: fully_generic_array
      $defs:
        numbersOnly:
          $dynamicAnchor: generic-array
          type: number
    stringArray:
      $id: array_of_strings
      $ref: fully_generic_array
      $defs:
        stringsOnly:
          $dynamicAnchor: generic-array
          type: string
    objWithTypedArray:
      $id: obj_with_typed_array
      type: object
      required:
      - dataType
      - data
      properties:
        dataType:
          enum:
          - string
          - number
      oneOf:
      - properties:
          dataType:
            const: string
          data:
            $ref: array_of_strings
      - properties:
          dataType:
            const: number
          data:
            $ref: array_of_numbers

識別子オブジェクト

リクエストボディまたはレスポンスペイロードが複数の異なるスキーマのうちの1つである可能性がある場合、Discriminator Object はドキュメントの予期されるスキーマに関するヒントを提供します。このヒントは、シリアル化、デシリアル化、および検証を支援するために使用できます。Discriminator Object は、名前付きプロパティの可能な値を代替スキーマと暗黙的または明示的に関連付けることによってこれを行います。

discriminator はスキーマの検証結果を変更してはならないことに注意してください。

固定フィールド

フィールド名	タイプ	説明
プロパティ名	文字列	必須。判別値を保持するペイロード内のプロパティ名。このプロパティはペイロードスキーマで必須であるべきです。プロパティが存在しない場合の動作は未定義です。
マッピング	Map[string, string]	ペイロード値とスキーマ名または URI 参照間のマッピングを保持するオブジェクト。

このオブジェクトは仕様拡張で拡張されてもよい。

Discriminator Object の使用条件

Discriminator Object は、複合キーワード oneOf、anyOf、allOf のいずれかを使用している場合にのみ有効です。

oneOf と anyOf の両方の使用例では、これらのキーワードが discriminator に隣接している場合、可能なすべてのスキーマを明示的にリストする必要があります。

冗長性を避けるため、識別子を親スキーマ定義に追加し、allOf 構成を介して親スキーマに基づいて構築されるすべてのスキーマを代替スキーマとして使用してもよい。

discriminator の allOf 形式は、非検証ユースケースにのみ有用です。この形式の discriminator を使用した親スキーマでの検証は、子スキーマの検索や検証での使用を一切行いません。これは、discriminator が検証結果を変更できないこと、および標準の JSON Schema キーワードが親スキーマと子スキーマを接続しないためです。

上記の記述と異なる oneOf、anyOf、allOf、および discriminator の構成の動作は未定義です。

値をスキーマにマッピングするためのオプション

propertyName で指定されたプロパティの値は、Components Object 内の関連するスキーマの名前として使用されます。ただし、その値に対して mapping が存在する場合は例外です。mapping エントリは、特定のプロパティ値を別のスキーマコンポーネント名、または URI で識別されるスキーマにマッピングします。暗黙的または明示的なスキーマコンポーネント名を使用する場合、インラインの oneOf または anyOf サブスキーマは考慮されません。有効なスキーマ名と有効な相対 URI 参照の両方である mapping 値の動作は実装定義ですが、スキーマ名として扱うことを推奨します。曖昧な値 (例: "foo") がすべての実装で相対 URI 参照として扱われることを確実にするために、作成者は "." パスセグメント (例: "./foo") をプレフィックスとして追加する必要があります。

マッピングキーは文字列値である必要がありますが、ツールは比較のためにレスポンス値を文字列に変換しても構いません。ただし、そのような変換の正確な性質は実装定義です。

例

これらの例では、すべてのスキーマがOADのエントリドキュメントにあると仮定しています。参照されるドキュメントでのdiscriminatorの扱いについては、暗黙的な接続の解決を参照してください。

OAS 3.x では、応答ペイロードは複数の型の中から正確に1つであるように記述できます。

MyResponseType:
  oneOf:
    - $ref: '#/components/schemas/Cat'
    - $ref: '#/components/schemas/Dog'
    - $ref: '#/components/schemas/Lizard'

これは、ペイロードが、Cat、Dog、または Lizard によって記述されたスキーマのうち、検証によって正確に1つに一致しなければならないことを意味します。oneOf のデシリアライズは、ペイロードに一致するスキーマを決定し、それによってデシリアライズに使用されるべきであるため、コストのかかる操作になる可能性があります。この問題は anyOf スキーマにも存在します。discriminator は、一致するスキーマの選択の効率を向上させるための「ヒント」として使用できます。discriminator フィールドは oneOf の検証結果を変更することはできません。デシリアライズをより効率的にし、より良いエラーメッセージを提供することしかできません。インスタンスに一致することが期待されるスキーマを示す正確なフィールドを指定できます。

MyResponseType:
  oneOf:
    - $ref: '#/components/schemas/Cat'
    - $ref: '#/components/schemas/Dog'
    - $ref: '#/components/schemas/Lizard'
  discriminator:
    propertyName: petType

応答ペイロードには petType という名前のプロパティが必ず存在し、その値は OpenAPI Description で定義されたスキーマ名に対応するという期待が生まれました。したがって、応答ペイロード

{
  "id": 12345,
  "petType": "Cat"
}

は Cat スキーマがこのペイロードと一致することが期待されることを示します。

discriminator フィールドの値がスキーマ名と一致しない場合や、暗黙的なマッピングが不可能なシナリオでは、オプションの mapping 定義を使用しても構いません。

MyResponseType:
  oneOf:
    - $ref: '#/components/schemas/Cat'
    - $ref: '#/components/schemas/Dog'
    - $ref: '#/components/schemas/Lizard'
    - $ref: https://gigantic-server.com/schemas/Monster/schema.json
  discriminator:
    propertyName: petType
    mapping:
      dog: '#/components/schemas/Dog'
      monster: https://gigantic-server.com/schemas/Monster/schema.json

ここでは、dog の判別値は、デフォルト (暗黙的) の #/components/schemas/dog ではなく、スキーマ #/components/schemas/Dog にマッピングされます。判別値が暗黙的または明示的なマッピングと一致しない場合、スキーマを決定できず、検証は失敗するべきです。

anyOf 構成と組み合わせて使用すると、discriminator を使用することで、複数のスキーマが単一のペイロードを満たす可能性のあるシリアライザ/デシリアライザの曖昧さを回避できます。

この例は、親ですべての子スキーマを参照する必要を回避する allOf の使用法を示しています。

components:
  schemas:
    Pet:
      type: object
      required:
        - petType
      properties:
        petType:
          type: string
      discriminator:
        propertyName: petType
        mapping:
          dog: Dog
    Cat:
      allOf:
        - $ref: '#/components/schemas/Pet'
        - type: object
          # all other properties specific to a `Cat`
          properties:
            name:
              type: string
    Dog:
      allOf:
        - $ref: '#/components/schemas/Pet'
        - type: object
          # all other properties specific to a `Dog`
          properties:
            bark:
              type: string
    Lizard:
      allOf:
        - $ref: '#/components/schemas/Pet'
        - type: object
          # all other properties specific to a `Lizard`
          properties:
            lovesRocks:
              type: boolean

Pet スキーマに対して検証された、このようなペイロード

{
  "petType": "Cat",
  "name": "Misty"
}

は、#/components/schemas/Cat スキーマが一致することが期待されることを示します。同様に、このペイロードも

{
  "petType": "dog",
  "bark": "soft"
}

mapping 要素の dog エントリが Dog にマップされるため、#/components/schemas/Dog にマップされます。Dog は #/components/schemas/Dog のスキーマ名です。

XML オブジェクト

よりきめ細かいXMLモデル定義を可能にするメタデータオブジェクト。

配列を使用する場合、XML 要素名は（単数形/複数形について）推論されず、その情報を追加するために name フィールドを使用するべきです。予期される動作については例を参照してください。

固定フィールド

フィールド名	タイプ	説明
名前	文字列	記述されているスキーマプロパティに使用される要素/属性の名前を置き換えます。items 内で定義された場合、リスト内の個々の XML 要素の名前に影響を与えます。type が "array" と並行して定義された場合 (items の外部)、wrapped が true の場合に限り、ラッピング要素に影響を与えます。wrapped が false の場合、無視されます。
名前空間	文字列	名前空間定義の URI。値は非相対 URI の形式でなければなりません。
プレフィックス	文字列	名前に使用されるプレフィックス。
属性	ブール値	プロパティ定義が要素ではなく属性に変換されるかどうかを宣言します。デフォルト値は false です。
ラップ	ブール値	配列定義にのみ使用できます。配列がラップされているか (例: <books><book/><book/></books>)、またはラップされていないか (<book/><book/>) を示します。デフォルト値は false です。この定義は、type が "array" と並行して定義されている場合 (items の外部) にのみ有効になります。

このオブジェクトは仕様拡張で拡張されてもよい。

namespace フィールドは XML 名前空間の構文に一致することを意図していますが、いくつかの注意点があります。

• この仕様のバージョン 3.1.0、3.0.3、およびそれ以前では、「非相対 URI」ではなく誤って「絶対 URI」という用語が使用されていたため、フラグメントを含む名前空間を使用する作者はツールのサポートを慎重に確認する必要があります。
• XML は相対 URI 参照を許可しますが推奨しませんが、この仕様ではそれらを完全に禁止しています。
• XML 1.1 は IRI (RFC3987) を名前空間として許可し、名前空間はエンコードもデコードもせずに比較されると規定しています。これは、この仕様の URI 構文要件を満たすようにエンコードされた IRI を、IRI とそのまま比較できないことを意味します。

XML Object の例

以下の各例は、簡潔にするために省略されている Schema Object 内の properties キーワードの値を表しています。properties 値の JSON および YAML 表現の後に、示されている単一のプロパティに対して生成された XML 表現の例が続きます。

XML 要素なし

基本的な文字列プロパティ

{
  "animals": {
    "type": "string"
  }
}

animals:
  type: string

<animals>...</animals>

基本的な文字列配列プロパティ（wrappedはデフォルトでfalse）

{
  "animals": {
    "type": "array",
    "items": {
      "type": "string"
    }
  }
}

animals:
  type: array
  items:
    type: string

<animals>...</animals>
<animals>...</animals>
<animals>...</animals>

XML名置換

{
  "animals": {
    "type": "string",
    "xml": {
      "name": "animal"
    }
  }
}

animals:
  type: string
  xml:
    name: animal

<animal>...</animal>

XML属性、プレフィックス、および名前空間

この例では、完全なモデル定義を示します。

{
  "Person": {
    "type": "object",
    "properties": {
      "id": {
        "type": "integer",
        "format": "int32",
        "xml": {
          "attribute": true
        }
      },
      "name": {
        "type": "string",
        "xml": {
          "namespace": "https://example.com/schema/sample",
          "prefix": "sample"
        }
      }
    }
  }
}

Person:
  type: object
  properties:
    id:
      type: integer
      format: int32
      xml:
        attribute: true
    name:
      type: string
      xml:
        namespace: https://example.com/schema/sample
        prefix: sample

<Person id="123">
    <sample:name xmlns:sample="https://example.com/schema/sample">example</sample:name>
</Person>

XML配列

要素名の変更

{
  "animals": {
    "type": "array",
    "items": {
      "type": "string",
      "xml": {
        "name": "animal"
      }
    }
  }
}

animals:
  type: array
  items:
    type: string
    xml:
      name: animal

<animal>value</animal>
<animal>value</animal>

外部の name フィールドは XML に影響しません。

{
  "animals": {
    "type": "array",
    "items": {
      "type": "string",
      "xml": {
        "name": "animal"
      }
    },
    "xml": {
      "name": "aliens"
    }
  }
}

animals:
  type: array
  items:
    type: string
    xml:
      name: animal
  xml:
    name: aliens

<animal>value</animal>
<animal>value</animal>

配列がラップされていても、名前が明示的に定義されていない場合、内部と外部の両方で同じ名前が使用されます。

{
  "animals": {
    "type": "array",
    "items": {
      "type": "string"
    },
    "xml": {
      "wrapped": true
    }
  }
}

animals:
  type: array
  items:
    type: string
  xml:
    wrapped: true

<animals>
  <animals>value</animals>
  <animals>value</animals>
</animals>

上記の例の名前付けの問題を克服するには、以下の定義を使用できます。

{
  "animals": {
    "type": "array",
    "items": {
      "type": "string",
      "xml": {
        "name": "animal"
      }
    },
    "xml": {
      "wrapped": true
    }
  }
}

animals:
  type: array
  items:
    type: string
    xml:
      name: animal
  xml:
    wrapped: true

<animals>
  <animal>value</animal>
  <animal>value</animal>
</animals>

内部名と外部名の両方に影響を与える

{
  "animals": {
    "type": "array",
    "items": {
      "type": "string",
      "xml": {
        "name": "animal"
      }
    },
    "xml": {
      "name": "aliens",
      "wrapped": true
    }
  }
}

animals:
  type: array
  items:
    type: string
    xml:
      name: animal
  xml:
    name: aliens
    wrapped: true

<aliens>
  <animal>value</animal>
  <animal>value</animal>
</aliens>

外部要素を変更しても内部要素を変更しない場合

{
  "animals": {
    "type": "array",
    "items": {
      "type": "string"
    },
    "xml": {
      "name": "aliens",
      "wrapped": true
    }
  }
}

animals:
  type: array
  items:
    type: string
  xml:
    name: aliens
    wrapped: true

<aliens>
  <aliens>value</aliens>
  <aliens>value</aliens>
</aliens>

セキュリティスキームオブジェクト

操作で使用できるセキュリティスキームを定義します。

サポートされるスキームは、HTTP 認証、API キー (ヘッダー、Cookie パラメータ、クエリ パラメータのいずれか)、相互 TLS (クライアント証明書の使用)、RFC6749 で定義されている OAuth2 の一般的なフロー (implicit、password、client credentials、authorization code)、および [[OpenID-Connect-Core]] です。2020 年現在、implicit フローは OAuth 2.0 Security Best Current Practice により非推奨となる予定であることに注意してください。ほとんどのユースケースでは、PKCE を伴う Authorization Code Grant フローが推奨されます。

固定フィールド

フィールド名	タイプ	適用対象	説明
タイプ	文字列	任意	必須。セキュリティスキームの種類。有効な値は "apiKey"、"http"、"mutualTLS"、"oauth2"、"openIdConnect" です。
説明	文字列	任意	セキュリティスキームの説明。CommonMark 構文をリッチテキスト表現に使用してもよい。
名前	文字列	API キー	必須。使用するヘッダー、クエリ、またはクッキーパラメーターの名前。
イン	文字列	API キー	必須。API キーの場所。有効な値は "query"、"header"、または "cookie" です。
スキーム	文字列	HTTP	必須。RFC7235 で定義されている Authorization ヘッダーで使用される HTTP 認証スキームの名前。使用される値は IANA 認証スキームレジストリに登録されているべきです。RFC7235 で定義されているように、値は大文字と小文字を区別しません。
ベアラ形式	文字列	http ("bearer")	ベアラトークンがどのようにフォーマットされているかをクライアントが識別するためのヒント。ベアラトークンは通常、認証サーバーによって生成されるため、この情報は主にドキュメント作成目的です。
フロー	OAuth フローオブジェクト	oauth2	必須。サポートされるフロータイプの設定情報を含むオブジェクト。
OpenID Connect URL	文字列	オープンID接続	必須。[[OpenID-Connect-Discovery]] の プロバイダーメタデータを検出するためのWell-known URL。

このオブジェクトは仕様拡張で拡張されてもよい。

Security Scheme Object の例

基本的な認証の例

{
  "type": "http",
  "scheme": "basic"
}

type: http
scheme: basic

APIキーの例

{
  "type": "apiKey",
  "name": "api-key",
  "in": "header"
}

type: apiKey
name: api-key
in: header

JWTベアラの例

{
  "type": "http",
  "scheme": "bearer",
  "bearerFormat": "JWT"
}

type: http
scheme: bearer
bearerFormat: JWT

MutualTLSの例

{
  "type": "mutualTLS",
  "description": "Cert must be signed by example.com CA"
}

type: mutualTLS
description: Cert must be signed by example.com CA

暗黙的なOAuth2の例

{
  "type": "oauth2",
  "flows": {
    "implicit": {
      "authorizationUrl": "https://example.com/api/oauth/dialog",
      "scopes": {
        "write:pets": "modify pets in your account",
        "read:pets": "read your pets"
      }
    }
  }
}

type: oauth2
flows:
  implicit:
    authorizationUrl: https://example.com/api/oauth/dialog
    scopes:
      write:pets: modify pets in your account
      read:pets: read your pets

OAuth フローオブジェクト

サポートされている OAuth フローの設定を許可します。

固定フィールド

フィールド名	タイプ	説明
暗黙的	OAuth フローオブジェクト	OAuth Implicit フローの設定
パスワード	OAuth フローオブジェクト	OAuth Resource Owner Password フローの設定
クライアントクレデンシャル	OAuth フローオブジェクト	OAuth クライアントクレデンシャルフローの設定。OpenAPI 2.0 では以前 application と呼ばれていました。
認証コード	OAuth フローオブジェクト	OAuth Authorization Code フローの設定。OpenAPI 2.0 では以前 accessCode と呼ばれていました。

このオブジェクトは仕様拡張で拡張されてもよい。

OAuth フローオブジェクト

サポートされているOAuthフローの設定詳細

固定フィールド

フィールド名	タイプ	適用対象	説明
認証URL	文字列	oauth2 ("implicit", "authorizationCode")	必須。このフローに使用される認証URL。これはURLの形式でなければなりません。OAuth2標準はTLSの使用を要求しています。
トークンURL	文字列	oauth2 ("password", "clientCredentials", "authorizationCode")	必須。このフローで使用されるトークンURL。これはURLの形式でなければなりません。OAuth2標準はTLSの使用を要求しています。
リフレッシュURL	文字列	oauth2	リフレッシュトークンを取得するために使用されるURL。これはURLの形式でなければなりません。OAuth2標準はTLSの使用を要求しています。
スコープ	Map[string, string]	oauth2	必須。OAuth2セキュリティスキームで利用可能なスコープ。スコープ名とそれに関する短い説明の間のマップ。マップは空でもよい。

このオブジェクトは仕様拡張で拡張されてもよい。

OAuth Flow Object の例

{
  "type": "oauth2",
  "flows": {
    "implicit": {
      "authorizationUrl": "https://example.com/api/oauth/dialog",
      "scopes": {
        "write:pets": "modify pets in your account",
        "read:pets": "read your pets"
      }
    },
    "authorizationCode": {
      "authorizationUrl": "https://example.com/api/oauth/dialog",
      "tokenUrl": "https://example.com/api/oauth/token",
      "scopes": {
        "write:pets": "modify pets in your account",
        "read:pets": "read your pets"
      }
    }
  }
}

type: oauth2
flows:
  implicit:
    authorizationUrl: https://example.com/api/oauth/dialog
    scopes:
      write:pets: modify pets in your account
      read:pets: read your pets
  authorizationCode:
    authorizationUrl: https://example.com/api/oauth/dialog
    tokenUrl: https://example.com/api/oauth/token
    scopes:
      write:pets: modify pets in your account
      read:pets: read your pets

セキュリティ要件オブジェクト

この操作を実行するために必要なセキュリティスキームをリストします。各プロパティに使用される名前は、Components Object の下のSecurity Schemesで宣言されたセキュリティスキームに対応していなければなりません。

Security Requirement Object は複数のセキュリティスキームを参照してもよく、その場合、リクエストが承認されるためにはすべてのスキームを満たす必要があります。これにより、複数のクエリパラメーターまたは HTTP ヘッダーがセキュリティ情報を伝達するために必要なシナリオがサポートされます。

security フィールドが OpenAPI Object または Operation Object で定義されており、複数の Security Requirement Object を含んでいる場合、リクエストを承認するためにリスト内のいずれか1つのエントリを満たすだけで十分です。これにより、API が複数の独立したセキュリティスキームを許可するシナリオがサポートされます。

空の Security Requirement Object ({}) は、匿名アクセスがサポートされていることを示します。

パターンフィールド

フィールドパターン	タイプ	説明
{名前}	[string]	各名前は、Components Object の下の Security Schemes で宣言されたセキュリティスキームに対応していなければなりません。セキュリティスキームが "oauth2" または "openIdConnect" のタイプである場合、値は実行に必要なスコープ名のリストであり、認証に特定のスコープが不要な場合はリストは空でもよいです。他のセキュリティスキームタイプの場合、配列は実行に必要なロール名のリストを含むことができますが、それ以外は定義または帯域内で交換されません。

セキュリティ要件オブジェクトの例

マルチドキュメント OpenAPI Description で Security Requirement Object を使用する例については、付録 F: 参照されたドキュメントでのセキュリティ要件の解決も参照してください。

非 OAuth2 セキュリティ要件

{
  "api_key": []
}

api_key: []

OAuth2 セキュリティ要件

{
  "petstore_auth": ["write:pets", "read:pets"]
}

petstore_auth:
  - write:pets
  - read:pets

オプションの OAuth2 セキュリティ

OpenAPI Object または Operation Object で定義されるようなオプションの OAuth2 セキュリティ。

{
  "security": [
    {},
    {
      "petstore_auth": ["write:pets", "read:pets"]
    }
  ]
}

security:
  - {}
  - petstore_auth:
      - write:pets
      - read:pets

仕様の拡張

OpenAPI Specification はほとんどのユースケースに対応しようとしますが、特定の点において仕様を拡張するために追加のデータを追加することができます。

拡張プロパティは、常に x- をプレフィックスとするパターンフィールドとして実装されます。

フィールドパターン	タイプ	説明
^x-	任意	OpenAPIスキーマへの拡張を許可します。フィールド名にはx-をプレフィックスとして付ける必要があります（例：x-internal-id）。x-oai-およびx-oas-で始まるフィールド名は、OpenAPI Initiativeによって定義される用途のために予約されています。値は任意の有効なJSON値（null、プリミティブ、配列、またはオブジェクト）にすることができます。

OpenAPI Initiativeは、個々の拡張キーワードおよび拡張キーワードの名前空間を含む、いくつかの[[OpenAPI-Registry|拡張レジストリ]]を維持しています。

拡張機能は、仕様への提案された追加機能の実現可能性を証明するための最良の方法の1つです。したがって、コミュニティの実験をサポートするために、実装は拡張性を考慮して設計されることを推奨します。

いずれかの拡張機能のサポートは任意であり、ある拡張機能のサポートは他の拡張機能のサポートを意味しません。

セキュリティフィルタリング

OpenAPI Specificationの一部のオブジェクトは、APIドキュメントの中核をなすものであっても、宣言されて空のままになったり、完全に削除されたりする場合があります。

その理由は、ドキュメントに対して追加のアクセス制御レイヤーを許可することです。仕様自体の一部ではありませんが、特定のライブラリは、何らかの形式の認証/承認に基づいてドキュメントの一部へのアクセスを許可することを選択する場合があります。

これの2つの例

1. Paths Objectは存在しても空である可能性があります。これは直感に反するかもしれませんが、閲覧者が正しい場所に到達したが、ドキュメントにアクセスできないことを示している場合があります。閲覧者は、認証に関する追加情報を含む可能性のある少なくともInfo Objectにはアクセスできます。
2. Path Item Objectは空である可能性があります。この場合、閲覧者はパスが存在することを認識しますが、その操作やパラメーターを見ることはできません。Paths Objectからパス自体を隠すのとは異なり、ユーザーはその存在を認識します。これにより、ドキュメントプロバイダーは閲覧者が見ることができるものを細かく制御できます。

セキュリティに関する考慮事項

OpenAPI記述形式

OpenAPI記述はJSON、YAML、JSON Schemaの組み合わせを使用するため、それらのセキュリティに関する考慮事項を共有します。

• JSON
• YAML
• JSON Schema Core
• JSON Schema Validation

ツールと使用シナリオ

さらに、OpenAPI記述は、クライアントコード生成、ドキュメント生成、サーバーサイドルーティング、APIテストなど、さまざまな目的のために幅広いツールによって処理されます。OpenAPI記述の作成者は、OpenAPI記述が使用される可能性のあるシナリオのリスクを考慮する必要があります。

セキュリティスキーム

OpenAPI記述は、定義するリソースを保護するために使用されるセキュリティスキームを記述します。利用可能なセキュリティスキームは、さまざまな程度の保護を提供します。データの機密性やセキュリティ侵害の潜在的な影響などの要因は、APIリソースのセキュリティスキームの選択を導く必要があります。基本認証やOAuth Implicitフローなどの一部のセキュリティスキームは、既存のAPIとの互換性のためにサポートされています。ただし、OpenAPIへのそれらの包含は、特に機密性の高いデータや操作については、それらの使用を推奨するものではありません。

外部リソースの処理

OpenAPI記述には、利用ツールによって自動的に逆参照される可能性のある外部リソースへの参照が含まれる場合があります。外部リソースは、信頼できない異なるドメインでホストされる場合があります。

参照サイクルの処理

OpenAPI記述内の参照により、サイクルが発生する可能性があります。ツールは、リソースの枯渇を防ぐためにサイクルを検出し、処理する必要があります。

MarkdownとHTMLのサニタイズ

特定のフィールドでは、スクリプトを含むHTMLを含むMarkdownの使用が許可されています。Markdownを適切にサニタイズするのはツールの責任です。

付録A: 改訂履歴

バージョン	日付	備考
3.1.1	2024-10-24	OpenAPI Specification 3.1.1のパッチリリース
3.1.0	2021-02-15	OpenAPI Specification 3.1.0のリリース
3.1.0-rc1	2020-10-08	3.1仕様のrc1
3.1.0-rc0	2020-06-18	3.1仕様のrc0
3.0.4	2024-10-24	OpenAPI Specification 3.0.4のパッチリリース
3.0.3	2020-02-20	OpenAPI Specification 3.0.3のパッチリリース
3.0.2	2018-10-08	OpenAPI Specification 3.0.2のパッチリリース
3.0.1	2017-12-06	OpenAPI Specification 3.0.1のパッチリリース
3.0.0	2017-07-26	OpenAPI Specification 3.0.0のリリース
3.0.0-rc2	2017-06-16	3.0仕様のrc2
3.0.0-rc1	2017-04-27	3.0仕様のrc1
3.0.0-rc0	2017-02-28	3.0仕様の実装者ドラフト
2.0	2015-12-31	Swagger 2.0のOpenAPI Initiativeへの寄贈
2.0	2014-09-08	Swagger 2.0のリリース
1.2	2014-03-14	正式文書の初回リリース
1.1	2012-08-22	Swagger 1.1のリリース
1.0	2011-08-10	Swagger Specificationの初回リリース

付録B: データ型変換

text/plainメッセージボディまたはmultipartパーツ、およびURLクエリ文字列またはメッセージボディのapplication/x-www-form-urlencoded形式で発生する可能性のある、型付きデータをプレーンテキストにシリアル化することには、実装またはアプリケーション定義の動作が大きく関わります。

スキーマオブジェクトは、JSON Schemaデータモデルに基づいてデータを検証します。JSON Schemaデータモデルは、4つのプリミティブデータ型のみを認識します。文字列（UTF-8として広く相互運用可能であるもののみ）、数値、ブール値、およびnullです。特に、整数は他の数値とは異なる型ではなく、type: "integer"は数学的に定義された便宜であり、文字列表現における小数点以下の有無に基づいているわけではありません。

Parameter Object、Header Object、およびEncoding Objectは、配列またはオブジェクト型から値の配置を制御する機能を提供します。これらは、予約文字や不正な文字を避けるために文字列をさらにエンコードする方法を制御するためにも使用できます。ただし、スキーマ検証された非UTF-8プリミティブデータ型（または配列全体やオブジェクト全体）を文字列に変換するための汎用的な仕様はありません。

2つのケースは標準ベースのガイダンスを提供します

• RFC3987は、特にURI（およびその拡張として、同じエンコード規則を使用するフォームメディアタイプ）のコンテキストで、非Unicode文字列をUTF-8に変換するためのガイダンスを提供します。
• RFC6570は、nullを含むがこれに限定されない値で、未定義と見なされ、その仕様に基づいてシリアル化する際に拡張プロセスで特別に扱われるものを指定します。

RFC6570の実装には、非文字列値を変換するための独自の慣例があることがよくありますが、これらは実装固有であり、RFC自体によって定義されているわけではありません。これが、OpenAPI Specificationがこれらの変換を実装定義のままにしている理由の1つです。これにより、RFC6570の実装が変換をどのように行うかに関係なく使用できるようになります。

数値、ブール値、およびnull（またはRFC6570が未定義と見なすその他の値）のシリアル化をより正確に制御するには、スキーマをtype: "string"として定義し、pattern、enum、format、およびその他のキーワードを使用して制約を付け、アプリケーションがスキーマ検証の前にデータをどのように事前に変換する必要があるかを伝えることができます。結果として得られる文字列は、それ以上の型変換を必要としません。

formatキーワードはシリアル化に役立ちます。一部の形式（date-timeなど）は明確ですが、他の形式（フォーマットレジストリのdecimalなど）はあまり明確ではありません。ただし、formatを使用する際は、特定のフォーマットがすべての関連ツールでサポートされていることを確認する必要があります。認識されないフォーマットは無視されるためです。

事前フォーマットされたスキーマ検証済み文字列として入力を要求することも、すべてのプログラミング言語と環境が同じデータ型をサポートしているわけではないため、ラウンドトリップの相互運用性を向上させます。

付録C: RFC6570ベースのシリアル化の使用

シリアル化は、3つのシナリオでRFC6570 URIテンプレートの観点から定義されます。

オブジェクト	条件
パラメーターオブジェクト	schemaが存在する場合
Header Object	schemaが存在する場合
エンコーディングオブジェクト	application/x-www-form-urlencodedのエンコードで、style、explode、またはallowReservedのいずれかが使用されている場合

この仕様の実装は、RFC6570の実装を使用して変数展開を実行する場合がありますが、いくつかの注意点があります。

style: "form" RFC6570展開を使用してapplication/x-www-form-urlencoded HTTPメッセージボディを生成する場合、URIクエリ文字列構文を満たすために生成される?プレフィックスを削除する必要があることに注意してください。

styleや類似のキーワードを使用してmultipart/form-dataボディを生成する場合、クエリ文字列名はContent-Dispositionパートヘッダーのnameパラメーターに配置され、値は対応するパートボディに配置されます。?、=、および&文字は使用されません。[[RFC7578]]は「ファイル名」での[[RFC3986]]パーセントエンコーディングの使用を許可していますが、フォーマット内でのパーセントエンコーディングの使用については言及していません。RFC7578はmultipart/form-dataの文字セットとエンコーディングの問題について詳細に議論しており、OpenAPI記述の作成者は、このメディアタイプでRFC6570ベースのシリアル化を使用することを決定する前に、このガイダンスを注意深く読むことを推奨します。

また、すべてのRFC6570実装がOpenAPI Specificationの使用を完全にサポートするために必要な4つのレベルのオペレーターすべてをサポートしているわけではないことにも注意してください。サポートレベルの低い実装を使用する場合、制限を回避するためにURIテンプレートの追加の手動構築が必要になります。

フィールドとRFC6570オペレーター間の等価性

特定のフィールド値はRFC6570演算子（またはその欠如）に変換されます

フィールド	値	同等
スタイル	"simple"	該当なし
スタイル	"matrix"	; プレフィックス演算子
スタイル	"label"	. プレフィックス演算子
スタイル	"form"	? プレフィックス演算子
allowReserved	偽	該当なし
allowReserved	本当	+ プレフィックス演算子
爆発する	偽	該当なし
爆発する	本当	* 修飾子サフィックス

複数のstyle: "form"パラメーターは、?プレフィックス演算子を使用した単一のRFC6570変数リストと同等です。

parameters:
- name: foo
  in: query
  schema:
    type: object
  explode: true
- name: bar
  in: query
  schema:
    type: string

この例はRFC6570の{?foo*,bar}と同等であり、{?foo*}{&bar}とは異なります。後者は、fooが定義されていない場合、結果が無効なURIになるため問題があります。&プレフィックス演算子にはParameter Objectに同等なものはありません。

RFC6570は、explodeで対応する単一レベルを超える複合値の動作を特定していないことに注意してください。オブジェクトや配列が明確な動作が指定されていない場所で使用された場合の結果は、実装定義です。

パラメーター値の区切り文字

style: "simple"で配列やオブジェクト値を結合するために使用される,など、RFC6570展開で使用される区切り文字は、allowReservedがfalseである限り、すべて自動的にパーセントエンコードされます。RFC6570はURIテンプレートに基づいて変数を解析する方法を定義していないため、ユーザーは、区切り文字を含む可能性のある値をパーセントデコードする前に、まず区切り文字で値を分割するように注意する必要があります。

allowReservedがtrueの場合、パーセントエンコーディング（区切り文字で値を結合する前）とパーセントデコーディング（区切り文字で分割した後）の両方を、適切なタイミングで手動で行う必要があります。

付録Eを参照して、RFC6570に相当するものがなく、区切り文字として使用する際にすでにパーセントエンコードが必要なstyle値の区切り文字の処理に関する追加のガイダンスを確認してください。

非RFC6570フィールド値と組み合わせ

直接的なRFC6570の等価性を持たない設定も、RFC6570に従って処理されるべきです。実装は、RFC6570の通常の展開または予約された展開（allowReservedに基づく）を使用して、個々の名前と値の変数を適切に区切ったURIテンプレートを作成する場合があります。

これには以下が含まれます。

• pipeDelimited、spaceDelimited、deepObjectのスタイルで、全く同等なものがないもの。
• styleがformでallowReserved: trueの組み合わせ。これは、一度に1つのプレフィックスオペレーターしか使用できないため許可されません。
• RFC6570の有効な変数名ではないパラメーター名。

Parameter Objectのnameフィールドは、RFC6570の変数名構文よりもはるかに寛容な構文を持っています。許可されているRFC6570の変数文字セット以外の文字を含むパラメーター名は、URIテンプレートで使用する前にパーセントエンコードする必要があります。

例

formulasが展開され、wordsが展開されないフォームクエリ文字列で以下のデータを使用するとします。

formulas:
  a: x+y
  b: x/y
  c: x^y
words:
- math
- is
- fun

RFC6570互換の展開

このParameter Objectの配列は、RFC6570で完全にサポートされている通常のstyle: "form"展開を使用します。

parameters:
- name: formulas
  in: query
  schema:
    type: object
    additionalProperties:
      type: string
  explode: true
- name: words
  in: query
  schema:
    type: array
    items:
      type: string

これは、次のURIテンプレートに変換されます。

{?formulas*,words}

前に与えられたデータで展開すると、次のようになります。

?a=x%2By&b=x%2Fy&c=x%5Ey&words=math,is,fun

RFC6570でサポートされていないオプションによる展開

しかし、今度は（何らかの理由で）、bの式にある/をクエリ文字列にそのまま表示させたい、そして単語を書き言葉のようにスペースで区切りたいとします。そのためには、formulasにallowReserved: trueを追加し、wordsにはstyle: "spaceDelimited"に変更します。

parameters:
- name: formulas
  in: query
  schema:
    type: object
    additionalProperties:
      type: string
  explode: true
  allowReserved: true
- name: words
  in: query
  style: spaceDelimited
  explode: false
  schema:
    type: array
    items:
      type: string

?と+のRFC6570プレフィックスを組み合わせることはできず、RFC6570では,区切り文字をスペース文字に置き換える方法もありません。そのため、すべての部分を適切な種類の展開で通過させるために、手動で構築されたURIテンプレートに合うようにデータを再構築する必要があります。

以下に、単語の値の最初の項目にはwords.0、2番目にはwords.1、3番目にはwords.2という架空の規則を使用したテンプレートを示します。

?a={+a}&b={+b}&c={+c}&words={words.0} {words.1} {words.2}

RFC6570は、サブ構造における名前の階層を示すための.の使用について言及していますが、特定の命名規則や動作は定義していません。.の使用は自動ではないため、この新しいテンプレートに適した入力構造を構築する必要があります。

また、formulasの値は事前に処理する必要があります。これは、/およびその他のほとんどの予約文字はRFC3986によってクエリ文字列で許可されていますが、[、]、および#は許可されておらず、&、=、および+はすべて、クエリ文字列で使用しているapplication/x-www-form-urlencoded形式で特別な動作を持つためです。

allowReserved: trueを設定しても、URIで許可されていない予約文字が許可されるようになるわけではありません。それは単に、それらが展開を介して変更されずに渡されることを許可するだけです。したがって、予約された展開はそれを実行しないため、どのツールもこれらの文字をパーセントエンコードする必要がありますが、パーセントエンコードされたトリプルは変更されません。パーセントエンコーディングとフォームメディアタイプに関する詳細なガイダンスについては、付録Eも参照してください。これには、spaceDelimited、pipeDelimited、およびdeepObjectの区切り文字をパラメーター名と値で処理するためのガイダンスが含まれます。

したがって、上記テンプレートに合うように名前と値を配置したデータ構造は次のとおりです。formulasの値は、[]#&=+が事前にパーセントエンコードされています（ただし、この例では+のみが表示されています）。

a: x%2By
b: x/y
c: x^y
words.0: math
words.1: is
words.2: fun

手動で組み立てたテンプレートを再構築したデータで展開すると、以下のクエリ文字列が得られます。

?a=x%2By&b=x/y&c=x%5Ey&words=math%20is%20fun

/と事前にパーセントエンコードされた%2Bはそのままですが、許可されていない^文字（値の中）とスペース文字（テンプレート内だが展開された変数外）はパーセントエンコードされました。

未定義の値と手動によるURIテンプレートの構築

RFC6570が未定義と見なす値を正しく処理するために、テンプレートを手動で構築する際には注意が必要です。

formulas: {}
words:
- hello
- world

このデータを、元のRFC6570フレンドリーなURIテンプレート{?formulas*,words}で使用すると、次のようになります。

?words=hello,world

これは、手動で構築されたURIテンプレートと再構築されたデータがformulasオブジェクト全体を省略する必要があることを意味し、それによってwordsパラメーターがクエリ文字列の最初で唯一のパラメーターになります。

再構築されたデータ

words.0: hello
words.1: world

手動で構築されたURIテンプレート

?words={words.0} {words.1}

結果

?words=hello%20world

パラメータ名としての不正な変数名

この例では、ハートの絵文字はURIテンプレート名（またはURI）では不正です。

parameters:
- name: ❤️
  in: query
  schema:
    type: string

❤️: "love!"をRFC6570実装にそのまま渡すことはできません。代わりに、データとURIテンプレートの両方で名前（6オクテットのUTF-8シーケンス）を事前にパーセントエンコードする必要があります。

"%E2%9D%A4%EF%B8%8F": love!

{?%E2%9D%A4%EF%B8%8F}

これは、次の結果に展開されます。

?%E2%9D%A4%EF%B8%8F=love%21

付録D: ヘッダーとクッキーのシリアル化

RFC6570のパーセントエンコーディングの動作は、in: "header"およびin: "cookie"パラメーターには常に適切であるとは限りません。多くの場合、text/plainのようなメディアタイプでcontentを使用し、アプリケーションに正しい文字列を組み立てさせる方が適切です。

RFC6265のクッキーとRFC8941の構造化フィールド構文を使用するHTTPヘッダーの両方で、非ASCIIコンテンツはbase64エンコーディング（contentEncoding: "base64"）を使用して処理されます。標準のbase64エンコーディングアルファベットには、RFC6570の展開によってパーセントエンコードされるURLに安全でない文字が含まれていることに注意してください。両方のエンコーディングで値をシリアル化することは推奨されません。contentEncodingはURLに安全なbase64urlエンコーディングもサポートしていますが、ヘッダーとクッキーのRFCはこのエンコーディングについて言及していません。

ほとんどのHTTPヘッダーは構造化フィールド構文よりも古く、その構文とエンコーディングルールに関する包括的な評価は、この仕様の範囲をはるかに超えています。RFC8187はHTTP（ヘッダーまたはトレーラー）フィールドパラメーターのパーセントエンコーディングを推奨していますが、これらのパラメーターは;文字の後に現れます。style: "simple"の場合、その区切り文字自体がパーセントエンコードされ、一般的なHTTPフィールド構文に違反します。

style: "form"とin: "cookie"を組み合わせると、単一の値に対しては曖昧であり、複数の値に対しては誤りです。これは、複数の値がexplode: trueの使用の結果であるかどうかにかかわらず当てはまります。

このスタイルは、?文字を含むRFC6570フォーム展開と同等であると指定されています（詳細については付録Cを参照）。?文字はクッキー構文の一部ではありません。しかし、この仕様の過去のバージョンのこのスタイルの例では、?プレフィックスは含まれておらず、比較が正確ではないことを示唆しています。RFC6570の実装に依存する実装と、スタイル例に基づいてカスタムシリアル化を実行する実装は異なる結果を生成するため、どちらの結果が正しいかは実装定義です。

複数の値の場合、style: "form"は常に誤りです。クッキーの名前と値のペアは&ではなく;（セミコロンの後にスペース文字）で区切られるためです。

付録E: パーセントエンコーディングとフォームメディアタイプ

注: このセクションでは、読みやすさのためにapplication/x-www-form-urlencodedとmultipart/form-dataのメディアタイプをそれぞれform-urlencodedとform-dataと略します。

パーセントエンコーディングは、URIおよびURIから構文を派生するメディアタイプで使用されます。このプロセスは、3つの文字セットに関係しており、それらの名前は仕様によって異なりますが、このセクションの目的のために次のように定義されます。

• 非予約文字はパーセントエンコードする必要はありません。パーセントエンコードしても安全ですが、そうすると正規化されていないURIが生成されます。
• 予約文字は、URI構文で特別な動作をする（コンポーネントを区切るなど）、または特別な動作を定義する必要のある他の仕様のために予約されています（例: form-urlencodedは=、&、および+に特別な動作を定義します）。
• 安全でない文字は、特定の環境でURIを解析する際に問題を引き起こすことが知られています。

別途指定がない限り、このセクションではRFC3986の予約済みと非予約済みの定義を使用し、安全でないセットはこれらのいずれのセットにも含まれないすべての文字として定義します。

パーセントエンコーディングとform-urlencoded

各URIコンポーネント（クエリ文字列など）は、予約文字の一部を安全でないとみなします。これは、それらがコンポーネント間の区切り文字として機能する（例：#）ためか、あるいは（[と]の場合）歴史的にグローバルに安全でないとみなされていたものの、後に限定された目的のために予約済みのステータスを与えられたためです。

コンポーネント内で特別な意味が定義されていない予約文字は、パーセントエンコードせずに残すことができます。ただし、他の仕様が特別な意味を定義することができ、その場合、追加の特別な意味以外のそれらの文字に対してパーセントエンコードが必要になります。

form-urlencodedメディアタイプは、=と&を区切り文字として、+をスペース文字の置換として特別な意味を定義します（パーセントエンコード形式の%20ではなく）。これは、これら3つの文字がRFC3986によってクエリ文字列で予約済みだが許可されているにもかかわらず、form-urlencodedの目的に使用される場合を除き、form-urlencodedクエリ文字列ではパーセントエンコードされなければならないことを意味します。フォーム値での+の処理例については、付録Cを参照してください。

パーセントエンコーディングとform-data

RFC7578は、ファイル名などのテキストベースのパートごとのヘッダーデータをASCII文字セット内に保持するためのメカニズムとして、RFC3986ベースのパーセントエンコーディングを推奨しています。この提案は、古い（2015年以前の）form-dataの仕様には含まれていなかったため、相互運用性を確保するために注意が必要です。

form-dataメディアタイプは、そのパートに任意のテキストまたはバイナリデータを許可するため、パーセントエンコーディングは不要であり、パートのContent-Typeがそれを要求するように定義されていない限り、相互運用性の問題を引き起こす可能性があります。

URIとform-urlencoded文字列の生成と検証

URIパーセントエンコーディングとform-urlencodedメディアタイプは、複数の改訂にまたがる複雑な仕様履歴を持ち、場合によっては、異なる標準化団体による所有権の主張が対立することもあります。残念ながら、これらの仕様はそれぞれわずかに異なるパーセントエンコーディングルールを定義しており、URIまたはform-urlencodedメッセージボディが厳密な検証の対象となる場合は、これを考慮に入れる必要があります（多くのURIパーサーはデフォルトでは検証を実行しないことに注意してください）。

この仕様は、以下の関連する標準を規範的に引用しています。

仕様	日付	OASの使用法	パーセントエンコーディング	備考
RFC3986	01/2005	URI/URL構文	[[RFC3986]]	[[RFC1738]]、[[RFC2396]]を廃止
RFC6570	03/2012	スタイルベースのシリアル化	[[RFC3986]]	form‑urlencodedには+を使用しません
RFC1866	11/1995	コンテンツベースのシリアル化	[[RFC1738]]	[[HTML401]] セクション17.13.4.1、[[URL]] セクション5によって廃止

スタイルベースのシリアル化は、Parameter Objectでschemaが存在する場合、およびEncoding Objectでstyle、explode、またはallowReservedのいずれかが存在する場合に使用されます。RFC6570の2つの異なるパーセントエンコーディングのアプローチの詳細については、付録Cを参照してください。これには、+を含む例も含まれます。

コンテンツベースのシリアル化は、Media Type Objectによって定義され、contentフィールドが存在する場合のParameter Object、およびstyle、explode、allowReservedのフィールドがない場合のcontentTypeフィールドに基づいてEncoding Objectで使用されます。各パートはメディアタイプ（例: text/plainまたはapplication/json）に基づいてエンコードされ、その後form-urlencoded文字列で使用するためにパーセントエンコードされなければなりません。

form-dataのコンテンツベースのシリアル化は、データ内のパーセントエンコーディングを期待または要求しません。パートごとのヘッダー値のみです。

過去の仕様との相互運用性

ほとんどの場合、[[RFC3986]]に厳密に準拠してクエリ文字列を生成することで検証に合格するのに十分ですが（JSONスキーマのformat: "uri"およびformat: "uri-reference"を含む）、一部のform-urlencoded実装では、わずかに制限の厳しい[[RFC1738]]ルールが使用されることをまだ期待しています。

すべてのRFC1738準拠URIはRFC3986に準拠しているため、過去の相互運用性を確保する必要があるアプリケーションは、RFC1738のルールを使用するべきです。

ウェブブラウザ環境との相互運用性

WHATWGは、ブラウザコンテキストでのURLの解析とシリアル化、およびform-urlencodedデータの解析とシリアル化のための「URLリビング標準」を定義したウェブブラウザ指向の標準化団体です。WHATWGのクエリ文字列のパーセントエンコーディングルールは、クエリ文字列がform-urlencodedとして扱われるか（[[RFC1738]]よりも多くのパーセントエンコーディングを要求する）、または汎用構文の一部として扱われるか（[[RFC3986]]が禁止する文字を許可する）によって異なります。

ウェブブラウザとの最大限の互換性が必要な実装は、WHATWGのform-urlencodedパーセントエンコーディングルールを使用するべきです。ただし、WHATWGの厳格でない汎用クエリ文字列ルールに依存するべきではありません。結果として得られるURLは、JSONスキーマのformat: uriおよびformat: uri-referenceを含むRFC3986検証に失敗するためです。

URIとform-urlencoded文字列のデコード

パーセントデコードアルゴリズムは、どの文字がパーセントデコードされたか、されなかったかに関心がなく、これはどの仕様に従ってパーセントエンコードされたURIでも正しくデコードされることを意味します。

同様に、すべてのform-urlencodedデコードアルゴリズムは、+からスペースへの処理をパーセントデコードアルゴリズムに追加するだけであり、使用されたエンコーディング仕様に関係なく機能します。

ただし、+がスペースを表す場合はform-urlencodedデコードを、+がリテラル値としてそれ自身を表す場合は通常のパーセントデコードを使用するように注意する必要があります。

パーセントエンコーディングと不正または予約済みの区切り文字

deepObject、pipeDelimited、spaceDelimitedスタイルでそれぞれ区切り文字として使用される[、]、|、およびスペース文字は、すべて[[RFC3986]]に準拠するためにパーセントエンコードされなければなりません。これにより、これらのスタイルのいずれかを使用する際に、パラメーター名と値の区切り文字としての使用と区別するために、ユーザーは文字を別の方法で事前にエンコードする必要があります。

スペース文字は常に不正であり、関連する標準のすべてのバージョンのすべての実装によって何らかの方法でエンコードされます。パラメーター名と値のスペースを、%20としてエンコードされたspaceDelimited区切り文字と区別するために、form-urlencodedの慣例である+を使用することも可能ですが、仕様ではデコードが単一パスとして定義されており、デコードされた結果で異なる使用法を区別することは不可能です。

一部の環境では、[、]、場合によっては|がクエリ文字列でエンコードされずに使用されているようですが、WHATWGの汎用クエリ文字列ルールでは、これらをパーセントエンコードする必要はありません。これらの区切り文字をエンコードせずに残し、名前と値の中では通常のパーセントエンコードを使用するコードは、すべての実装で相互運用性が保証されるわけではありません。

最大限の相互運用性のために、これらのスタイルの区切り文字をパーセントエンコードする際に、追加のエスケープ規則を定義して文書化するか、これらのスタイルを完全に避けることを推奨します。追加のエンコーディング/エスケープの正確な方法はAPI設計者に委ねられ、この仕様で記述されているシリアル化とエンコーディングの前に実行され、この仕様のエンコーディングとシリアル化のステップが逆転された後に逆転されることが期待されます。これにより、この仕様で規定されているプロセスから外れます。

付録F: 参照ドキュメントにおけるセキュリティ要件の解決

この付録では、HTTPアクセス可能なマルチドキュメントOpenAPI記述（OAD）を取得し、参照される（エントリではない）ドキュメント内のSecurity Requirement Objectを解決する方法を示します。詳細については、暗黙的な接続の解決を参照してください。

まず、解析はエントリドキュメントから始まります。ここでは、MySecurityセキュリティスキームがJWTベースであると定義され、パスアイテムが別のドキュメントのコンポーネントへの参照として定義されています。

GET /api/description/openapi HTTP/1.1
Host: www.example.com
Accept: application/openapi+json

"components": {
  "securitySchemes": {
    "MySecurity": {
      "type": "http",
      "scheme": "bearer",
      "bearerFormat": "JWT"
    }
  }
},
"paths": {
  "/foo": {
    "$ref": "other#/components/pathItems/Foo"
  }
}

GET /api/description/openapi HTTP/1.1
Host: www.example.com
Accept: application/openapi+yaml

components:
  securitySchemes:
    MySecurity:
      type: http
      scheme: bearer
      bearerFormat: JWT
paths:
  /foo:
    $ref: 'other#/components/pathItems/Foo'

このエントリドキュメントは、ファイル拡張子を使用せずに別のドキュメントotherを参照しています。これにより、クライアントは、両方の表現が利用可能であると仮定して、リソースごとに許容可能な形式を選択する柔軟性が得られます。

GET /api/description/other HTTP/1.1
Host: www.example.com
Accept: application/openapi+json

"components": {
  "securitySchemes": {
    "MySecurity": {
      "type": "http",
      "scheme": "basic"
    }
  },
  "pathItems": {
    "Foo": {
      "get": {
        "security": [
          "MySecurity": []
        ]
      }
    }
  }
}

GET /api/description/other HTTP/1.1
Host: www.example.com
Accept: application/openapi+yaml

components:
  securitySchemes:
    MySecurity:
      type: http
      scheme: basic
  pathItems:
    Foo:
      get:
        security:
          - MySecurity: []

otherドキュメントでは、参照されたパスアイテムにセキュリティスキームMySecurityのセキュリティ要件があります。同じセキュリティスキームが元のエントリドキュメントにも存在します。暗黙的な接続の解決で概説されているように、MySecurityは実装定義の動作で解決されます。ただし、そのセクションに文書化されているように、ツールがエントリドキュメントからコンポーネント名を解決することを推奨します。すべての実装定義の動作と同様に、サポートされている動作を決定するためにツールのドキュメントを確認することが重要です。