OpenAPI仕様 v3.2.0

OAD内の各文書は参照ターゲットを発見するため完全にパースしなければなりません。 この要件にはJSON Schema仕様ドラフト2020-12のパース要件も含まれますが、ベースURIについてはURIの相対参照の指定に従います。 参照ターゲットはOpenAPIオブジェクトの$selfフィールドや、スキーマオブジェクトの$id、$anchor、$dynamicAnchorキーワードなどのフィールドで定義されます。

実装は、OADのあらゆる文書が完全にパースされるまで、参照を未解決扱いとしてはなりません。

参照解決時に対象部分だけパースした場合、その挙動は実装定義または未定義となります（詳細は断片的パースに関する注意および付録Gを参照）。

OpenAPI記述内の参照や外部ドキュメント・ライセンスなど補足情報へのURIは識別子として解決され、本仕様でURIと呼びます（API URLとは区別）。歴史的に一部フィールドはurlと名付けられていますが、説明では「URI」用語が使われています。

文書のパースで述べた通り、いくつかのフィールドでOpenAPI文書やスキーマオブジェクトをURIに関連付けできます。そのため、参照元文書やスキーマが配置されている場所と一致しないURIを割り当てることが可能です。 これにより、ローカルファイルやセキュリティ制限・ネットワーク制約下でも同じ参照を利用できます。

特別な記載がない限り、URIフィールドはすべて[RFC3986] 4.2章の定義に従い相対参照を許容します。

この仕様のいくつかの機能では、OpenAPI記述（OAD）内の他の部分へのURIに基づかない接続を解決する必要があります。

単一文書OADでは接続は明確ですが、複数文書OADの解決処理は本セクションの制約下で実装定義です。 場合によっては明確なURIベース代替案もあり、OAD作成者は相互運用性向上のためその代替案の利用を推奨します。

Components ObjectやTag Objectの名前を参照元（非エントリ文書）から解決する際は、ツールはエントリ文書から解決することを推奨します。 operationIdでOperation Objectを解決する際は、パース済み全文書のOperation Objectを考慮することが推奨です。

なお、暗黙的接続解決はURI参照の解決に影響はありません。

詳細や暗黙接続を用いるフィールド・オブジェクト一覧は付録G:解析・解決ガイダンスを参照してください。

次のOpenAPI文書の取得URIが https://device1.example.com と仮定します：

openapi: 3.2.0
$self: https://apidescriptions.example.com/foo
info:
  title: Example API
  version: 1.0
servers:
- url: .
  description: The production API on this device
- url: ./test
  description: The test API on this device

API URLに関しては、OpenAPI文書を識別する$selfフィールドは無視され、代わりに取得URIが使用されます。これにより正規化された production URL は https://device1.example.com、正規化された test URL は https://device1.example.com/test となります。

次のパスを仮定すると、具体的な定義である /pets/mine が最初にマッチします:

  /pets/{petId}
  /pets/mine

次のパスは同一とみなされ、無効です:

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

次のようなパスは曖昧な解決を引き起こす可能性があります:

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

これらのフィールドは content または schema のいずれにもMAY 使用できます。

example と examples フィールドは相互に排他的です；検証要件については Working with Examples を参照してください。

This object MAY be extended with Specification Extensions.

Note that while "Cookie" as a name is not forbidden if in is "header", the effect of defining a cookie parameter that way is undefined; use in: "cookie" instead.

より単純なシナリオでは、schema と style によってパラメータの構造と構文を記述できます。

これらのフィールドは in: "querystring" と共に使用してはMUST NOT です。

schema を持つパラメータで in: "header" または in: "cookie", style: "cookie" の場合は注意が必要です：

• これらの値をシリアライズする際、URI パーセントエンコーディングはMUST NOT 適用されます。
• これらのパラメータを解析する際、見かけ上のパーセントエンコーディングはMUST NOT デコードされてはなりません。
• 自動的にエンコードまたはデコードを行う RFC6570 実装を使用する場合、使用前にその処理を取り消す必要がMUST あります。

これらの場合、実装は引用やエスケープを試みるのではなく値をそのまま通過させることがMUST です。ヘッダの引用規則やクッキーのエスケープ慣行は広く異なるため自動的に処理できないためです；引用とエスケープに関するガイダンスは 付録 D を参照してください。

追加のガイダンスについては 付録 C: RFC6570 ベースのシリアル化の使用 を参照してください。

より複雑なシナリオでは、content フィールドがパラメータのメディアタイプとスキーマを定義し、その使用例を示すことができます。

in: "querystring" と application/x-www-form-urlencoded に関しては、Encoding the x-www-form-urlencoded Media Type を参照してください。

OpenAPI Initiative は、この仕様で期待されるメディアタイプのサポートを要約し、各メディアタイプに関連する節への索引を提供する Media Type Registry を維持しています。レジストリは IANA 登録（存在する場合）や各メディアタイプに関連する主要な仕様文書へのリンクも含みます。 このレジストリに追加される拡張や他の OpenAPI 仕様の後続バージョン向けの追加メディアタイプは、本バージョンの OAS 実装でサポートされることがMAYあります。

本仕様内では、順次的メディアタイプ はヘッダ、フッタ、エンベロープ、その他のメタデータを持たず、繰り返し構造のみからなる任意のメディアタイプとして定義されます。

順次的メディアタイプの例（IANA 登録されていないが一般的に使用されるものを含む）には次が挙げられます：

  application/jsonl
  application/x-ndjson
  application/json-seq
  application/geo+json-seq
  text/event-stream
  multipart/mixed

上の最初の3つでは、繰り返される構造は任意の JSON value です。 4番目は application/geo+json 構造の値を繰り返し、text/event-stream は Server-Sent Events に関連するカスタムテキスト形式を繰り返します。最後の multipart/mixed は任意のメディアタイプのドキュメントの順序付けられた一覧を提供し、時にストリームされます。 multipart 形式は技術的にはプレアンブルやエピローグを許しますが、RFC はそれらを無視するよう指示しており、本仕様ではそれらをモデリングしていません。

実装は、順次的メディアタイプを JSON Schema データモデルにマッピングする際、それらの値を同じ順序の配列として扱うことで対応することがMUST です。

順次的メディアタイプをストリーミング文脈で扱う際の詳細（text/event-stream コンテンツに対する特別考慮を含む）は Complete vs Streaming Content を参照してください。multipart タイプについては Encoding By Position も参照してください。

maxLength キーワードは、文字列データ（エンコードされたバイナリデータを含む）または非エンコードのバイナリデータで構成されるストリーミングペイロードの想定上限を設定するためにMAY 使用できます。 非エンコードのバイナリデータの場合、長さはオクテット数です。 このユースケースでは、JSON Schema がバイナリデータに直接適用されないため、maxLength は通常の JSON Schema 評価の外で実装されることがMAY ありますし、エンコードされたバイナリストリームを完全にメモリに保持するのは現実的でない場合があります。

encoding フィールドの挙動はウェブフォームをサポートするように設計されているため、繰り返し値を許す名前と値のペアとして構造化されたメディアタイプ、特に application/x-www-form-urlencoded と multipart/form-data に対してのみ定義されています。

encoding フィールドを使用するためには、フィールド下の各キーがプロパティとして存在することがMUST です；対応するプロパティを持たない encoding エントリはSHALL 無視されます。 配列プロパティは、与えられた Encoding Object を適用して各配列アイテムごとに同じ name を持つエンコード済み値を1つずつ生成する方法で処理されることがMUST です（これは複数の値をフォームフィールドに供給することを推奨する [RFC7578] の指針に沿います）。その他の値型については、トップレベルの非配列プロパティや配列内の値を含め、Encoding Object は値全体に適用されることがMUST です。 これらの name-value ペアの順序は実装依存です。

application/x-www-form-urlencoded については、エンコーディングキーはパラメータ名にマップされ、値は Encoding Object のルールに従って生成されることがMUST です。 ガイダンスと例（encoding フィールドの有無に関わらず）は Encoding the x-www-form-urlencoded Media Type を参照してください。

multipart については、エンコーディングキーは各パートの Content-Disposition: form-data ヘッダの name parameter にマップされることがMUST です（これは multipart/form-data に対して [RFC7578] で定義されています）。 非ASCII のパート名に関するガイダンスは [RFC7578] の Section 5 を参照してください。

エンコーディングフィールドを伴う場合・伴わない場合のさらなるガイダンスと例は Encoding multipart Media Types を参照してください。

ほとんどの multipart メディアタイプ（基礎となるルールを定義する multipart/mixed を含む）は、名前付きパートを持ちません。これらのメディアタイプのデータは配列としてモデル化され、各パートに対して順序どおりに1アイテムが対応します。

prefixEncoding および／または itemEncoding フィールドを使用するには、itemSchema または配列の schema が存在することがMUST です。 これらのフィールドは prefixItems と items の JSON Schema キーワードに類似しており、prefixEncoding（存在する場合）はデータ配列内の同じ位置の値に適用される Encoding Object の配列を提供し、itemEncoding は配列中の残りのアイテムすべてに対して単一の Encoding Object を適用します。 prefixItems と同様に、インスタンス配列が prefixEncoding 配列より短くてもエラーではなく、追加の Encoding Object は無視されることがSHALL です。

itemEncoding フィールドは itemSchema と共に使用してストリーミング multipart コンテンツをサポートすることもできます。

prefixEncoding フィールドは任意の multipart コンテンツで固定のパート順序を要求するために使用できます。 これには multipart/form-data も含まれ、プロパティ名が存在しないため Encoding Object の headers フィールドを使用して Content-Disposition とパート名を提供する必要があることに注意してください。

本仕様の以前のバージョンでは、multipart/form-data 以外の multipart メディアタイプで encoding フィールドの制限を回避するために各パートの Content-Disposition: form-data ヘッダの name parameter を使用することが推奨されていました。実装はこの回避策をサポートすることがMAY ありますが、この使用法は一般的ではないため、非 form-data の multipart メディアタイプの実装がこれをサポートする可能性は低いです。

この例は YAML で記述されているため、Example Object の value フィールドは JSON への自明な変換が可能な限り YAML としてフォーマットできます。これにより JSON を文字列として埋め込む必要がなくなります。

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'

あるいは、すべての JSON は有効な YAML であるため、例の値は YAML ドキュメント内で JSON 構文を使ってもかまいません：

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'

アイテムが JSON 値である任意の 順次的メディアタイプ において、各値の変換は不要です。JSON Text Sequences（[RFC7464] の application/json-seq や [RFC8091] の +json-seq 構造接尾辞）、JSON Lines（application/jsonl）、および NDJSON（application/x-ndjson）はこのカテゴリに含まれます。JSON Lines と NDJSON のメディアタイプは IANA に登録されていませんが、広く使われています。

次の例は、ストリーミングログエントリとクエリに対する固定長セットの両方のための Media Type Object を示します。これは schema と itemSchema の関係と、それぞれを使用する場合を示しています（例フィールドはどちらの場合も同じです）。

components:
  schemas:
    LogEntry:
      type: object
      properties:
        timestamp:
          type: string
          format: date-time
        level:
          type: integer
          minimum: 0
        message:
          type: string
    Log:
      type: array
      items:
        $ref: "#/components/schemas/LogEntry"
      maxItems: 100
  examples:
    LogJSONSeq:
      summary: Log entries in application/json-seq
      # JSON Text Sequences require an unprintable character
      # that cannot be escaped in a YAML string, and therefore
      # must be placed in an external document shown below
      externalValue: examples/log.json-seq
    LogJSONPerLine:
      summary: Log entries in application/jsonl or application/x-ndjson
      description: JSONL and NDJSON are identical for this example
      # Note that the value must be written as a string with newlines,
      # as JSONL and NDJSON are not valid YAML
      value: |
        {"timestamp": "1985-04-12T23:20:50.52Z", "level": 1, "message": "Hi!"}
        {"timestamp": "1985-04-12T23:20:51.37Z", "level": 1, "message": "Bye!"}
  responses:
    LogStream:
      description: |
        A stream of JSON-format log messages that can be read
        for as long as the application is running, and is available
        in any of the sequential JSON media types.
      content:
        application/json-seq:
          itemSchema:
            $ref: "#/components/schemas/LogEntry"
          examples:
            JSON-SEQ:
              $ref: "#/components/examples/LogJSONSeq"
        application/jsonl:
          itemSchema:
            $ref: "#/components/schemas/LogEntry"
          examples:
            JSONL:
              $ref: "#/components/examples/LogJSONPerLine"
        application/x-ndjson:
          itemSchema:
            $ref: "#/components/schemas/LogEntry"
          examples:
            NDJSON:
              $ref: "#/components/examples/LogJSONPerLine"
    LogExcerpt:
      description: |
        A response consisting of no more than 100 log records,
        generally as a result of a query of the historical log,
        available in any of the sequential JSON media types.
      content:
        application/json-seq:
          schema:
            $ref: "#/components/schemas/Log"
          examples:
            JSON-SEQ:
              $ref: "#/components/examples/LogJSONSeq"
        application/jsonl:
          schema:
            $ref: "#/components/schemas/Log"
          examples:
            JSONL:
              $ref: "#/components/examples/LogJSONPerLine"
        application/x-ndjson:
          schema:
            $ref: "#/components/schemas/Log"
          examples:
            NDJSON:
              $ref: "#/components/examples/LogJSONPerLine"

我々の application/json-seq の例は、改行と YAML ブロックリテラルでエスケープできない非表示のレコードセパレータ（0x1E）を含むため外部文書である必要があります：

0x1E{
  "timestamp": "1985-04-12T23:20:50.52Z",
  "level": 1,
  "message": "Hi!"
}
0x1E{
  "timestamp": "1985-04-12T23:20:51.37Z",
  "level": 1,
  "message": "Bye!"
}

この例では、Special Considerations for Server-Sent Events セクションで提供された一般的なイベントスキーマが #/components/schemas/Event にあると仮定します：

description: A request body to add a stream of typed data.
required: true
content:
  text/event-stream:
    itemSchema:
      $ref: "#/components/schemas/Event"
      required: [event]
      oneOf:
      - properties:
          event:
            const: addString
      - properties:
          event:
            const: addInt64
          data:
            $comment: |
              Since the `data` field is a string,
              we need a format to signal that it
              should be handled as a 64-bit integer.
            format: int64
      - properties:
          event:
            const: addJson
          data:
            $comment: |
              These content fields indicate
              that the string value should
              be parsed and validated as a
              JSON document (since JSON is not
              a binary format, `contentEncoding`
              is not needed)
            contentMediaType: application/json
            contentSchema:
              type: object
              required: [foo]
              properties:
                foo:
                  type: integer

上記の例に対する有効なリクエストボディの例として、次の text/event-stream ドキュメントが挙げられます：

event: addString
data: This data is formatted
data: across two lines
retry: 5

event: addInt64
data: 1234.5678
unknownField: this is ignored

: This is a comment
event: addJSON
data: {"foo": 42}

このストリームの処理をより明確に示すため、以下は同等の JSON Lines ドキュメントです。数値や JSON データが文字列として扱われ、未知のフィールドやコメントが無視されスキーマ検証に渡されないことを示しています：

{"event": "addString", "data": "This data is formatted\nacross two lines", "retry": 5}
{"event": "addInt64", "data": "1234.5678"}
{"event": "addJSON", "data": "{\"foo\": 42}"}

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

このオブジェクトは Specification Extensions によって拡張されることがMAY あります。

contentType のデフォルト値は以下のとおりで、contentEncoding 列の n/a は contentEncoding の存在や値が無関係であることを意味します。この表は、Encoding Usage and Restrictions に従って Encoding Object が適用される値に基づいています。Encoding By Name の場合、配列内のプロパティ（type が "array" の場合）は配列の各アイテムが対象であり、それ以外の型では全体の値が対象です。したがってこの表の array 行は、名前によるエンコード時にトップレベル配列内の配列値にのみ適用されます。

null の type 値の扱い方は、null 値がどのようにシリアライズされるかによります。null 値が完全に省略される場合、contentType は無関係です。データ型変換のオプションについては Appendix B を参照してください。

multipart/form-data に対して RFC6570 スタイルのシリアライゼーションを使用する場合、URI のパーセントエンコーディングはMUST NOT 適用され、allowReserved の値は無効です。追加のガイダンスについては Appendix C: Using RFC6570 Implementations を参照してください。

style、explode、または allowReserved のいずれかが明示的な値で存在することは、in: "query" の Parameter Objects を schema とともに使用するのと同等です。これら三つのフィールドがすべて欠けている場合は、content を使用するのと同等ですが、メディアタイプは Media Type Object ではなく contentType で指定される点が異なります。

encoding フィールドがない場合、シリアライゼーション戦略は Encoding Object のデフォルト値に基づきます：

requestBody:
  content:
    application/x-www-form-urlencoded:
      schema:
        type: object
        properties:
          id:
            type: string
            format: uuid
          address:
            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, %3A, %2C, %7B, %7D にパーセントエンコードされます：

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

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

ここでは id パラメータ（address を除く）を text/plain ではなく application/json としてシリアライズし、WHATWG-URL の form-urlencoded 規則に従ってエンコードした例を示します：

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

application/x-www-form-urlencoded はテキスト形式であるため、バイナリデータは base64 エンコードする必要がある点に注意してください：

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

name が example、icon が 2x2 ピクセルの赤い PNG の場合、生成されるリクエストボディは次のようになります：

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

「URL safe」である contentEncoding: base64url を使用していても、末尾の = パディング文字はパーセントエンコードする必要がある点に注意してください。一部の base64 デコーダ実装はパディングなしで動作する可能性がありますが（[RFC4648] の Section 3.2 を参照）、これは保証されないため、互換性を高めるにはパディングを保持してパーセントデコードに依存する方が良い場合があります。

contentType に複数の値が提供される場合でも、パートの実際の Content-Type がドキュメントに含まれるため解析は簡単です。

エンコードおよびシリアライゼーションのために、実装はアプリケーションがどのメディアタイプを意図しているか示すための仕組みを提供することがMUST です。実装は代替としてメディアタイプのスニッフィング（SNIFF）を提供することがMAY ありますが、このプロセスにはセキュリティリスクがあるためデフォルト動作にしてはなりません（MUST NOT）。

multipart フィールドに対して contentEncoding を使用することは、Content-Transfer-Encoding を含む headers フィールドを持ち、その値が contentEncoding で使用される値を要求するスキーマを持つ Encoding Object を指定するのと同等です。もし contentEncoding が multipart フィールドに使用され、そのフィールドに対する Encoding Object の headers に含まれる Content-Transfer-Encoding が contentEncoding の値を許容しない場合、シリアライズおよび解析の結果は未定義になります。

Working with Binary Data で述べられているように、Encoding Object の contentType（明示的またはデフォルトによる）が Schema Object の contentMediaType と矛盾する場合、contentMediaType はSHALL 無視されます。このため、そして Encoding Object の contentType のデフォルト規則が Schema Object の contentMediaType を考慮に入れていないため、Encoding Object とともに contentMediaType を使用することはNOT RECOMMENDED です。

また、Content-Transfer-Encoding は HTTP でバイナリデータがサポートされているため、multipart/form-data に対しては非推奨である点に注意してください（[RFC7578] Section 4.7）。

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

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

requestBody:
  content:
    multipart/form-data:
      schema:
        type: object
        properties:
          # default content type for a string without `contentEncoding`
          # is `text/plain`
          id:
            type: string
            format: uuid

          # default content type for a schema without `type`
          # is `application/octet-stream`
          profileImage: {}

          # for arrays, the `encoding` field applies the Encoding Object
          # to each item individually and determines the default content type
          # based on the type in the `items` subschema, which in this example
          # is an object, so the default content type for each item is
          # `application/json`
          addresses:
            type: array
            items:
              $ref: '#/components/schemas/Address'

encoding を使用すると、バイナリデータのより具体的な型や、複雑な値の非 JSON フォーマットを設定できます。また各パートのヘッダを記述することもできます：

requestBody:
  content:
    multipart/form-data:
      schema:
        type: object
        properties:
          # No Encoding Object, so use default `text/plain`
          id:
            type: string
            format: uuid

          # Encoding Object overrides the default `application/json` content type
          # for each item in the array with `application/xml; charset=utf-8`
          addresses:
            description: addresses in XML format
            type: array
            items:
              $ref: '#/components/schemas/Address'

          # Encoding Object accepts only PNG or JPEG, and also describes
          # a custom header for just this part in the multipart format
          profileImage: {}

      encoding:
        addresses:
          contentType: application/xml; charset=utf-8
        profileImage:
          contentType: image/png, image/jpeg
          headers:
            X-Rate-Limit-Limit:
              description: The number of allowed requests in the current period
              schema:
                type: integer

[RFC7578] Section 4.3 に従い、単一のフォームフィールドに対する複数ファイルは各ファイルのパートで同じ名前（この例では 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 のメディアタイプを示します。

JSON メタデータ文書に続いて、そのメタデータが記述する画像が続く multipart/mixed ペイロードの例：

multipart/mixed:
  schema:
    type: array
    prefixItems:
    - type: object
      properties:
        author:
          type: string
        created:
          type: string
          format: datetime
        copyright:
          type: string
        license:
          type: string
    - # default content type for a schema without `type`
      # is `application/octet-stream`, which we need
      # to override.
      {}
  prefixEncoding:
  - # Encoding Object defaults are correct for JSON
    {}
  - contentType: image/*

[RFC2557] に記載されているように、ウェブページを構成するリソース群は multipart/related ペイロードで送られ、text/html ドキュメントからスクリプトやスタイルシート、画像などへのリンクを保持するために各ページに対して Content-Location ヘッダを定義できます。最初のパートがルートリソースとして使用され（Content-ID を使用する場合を除くが RFC2557 はそれを推奨せず、本例では禁止しています）、したがって先頭要素に HTML リソースであることを要求するために prefixItems と prefixEncoding を使用し、その後に任意の型のリソースが並べられることを許容します。

Content-Location ヘッダは URI 値のパーセントエンコードを避けるために content: {text/plain: {...}} を使って定義しています；詳細は Appendix D を参照してください。

components:
  headers:
    RFC2557NoContentId:
      description: Use Content-Location instead of Content-ID
      schema: false
    RFC2557ContentLocation:
      required: true
      content:
        text/plain:
          schema:
            $comment: Use a full URI (not a relative reference)
            type: string
            format: uri
  requestBodies:
    RFC2557:
      content:
        multipart/related; type=text/html:
          schema:
            prefixItems:
            - type: string
            items:
              anyOf:
              - type: string
              - $comment: To allow binary, this must always pass
          prefixEncoding:
          - contentType: text/html
            headers:
              Content-ID:
                $ref: '#/components/headers/RFC2557NoContentId'
              Content-Location:
                $ref: '#/components/headers/RFC2557ContentLocation'
          itemEncoding:
            contentType: text/css,text/javascript,image/*
            headers:
              Content-ID:
                $ref: '#/components/headers/RFC2557NoContentId'
              Content-Location:
                $ref: '#/components/headers/RFC2557ContentLocation'

この例は、大量の画像を撮影してそれらをストリームするデバイスを想定しています。前の例とは異なり、ここでは各画像が到着次第（または小さなバッチで）処理されることが期待されるため、すべてをバッファリングするのはメモリ的に不可能であることが分かっているため itemSchema を使用します。

multipart/mixed:
  itemSchema:
    $comment: A single data image from the device
  itemEncoding:
    contentType: image/jpg

multipart/byteranges の場合、RFC9110 の Section 14.6 に従い、Content-Range ヘッダが必要です：

ヘッダ値を記述するために content: {text/plain: {...}} を使用する理由の説明は Appendix D を参照してください。

multipart/byteranges:
  itemSchema:
    $comment: A single range of bytes from a video
  itemEncoding:
    contentType: video/mp4
    headers:
      Content-Range:
        required: true
        content:
          text/plain:
            schema:
              # The `pattern` regular expression that would
              # be included in practice is omitted for simplicity
              type: string

これは二部構成の multipart/mixed を定義しており、最初のパートは JSON 配列、二番目のパートはネストされた multipart/mixed ドキュメントです。ネストされたパートは XML、プレーンテキスト、PNG 画像です。

multipart/mixed:
  schema:
    type: array
    prefixItems:
    - type: array
    - type: array
      prefixItems:
      - type: object
      - type: string
      - {}
  prefixEncoding:
    - {} # Accept the default application/json
    - contentType: multipart/mixed
      prefixEncoding:
      - contentType: application/xml
      - {} # Accept the default text/plain
      - contentType: image/png

value および略式の example フィールドは、最終的なシリアライズ形と JSON（または JSON 互換 YAML）表現の間に差がない場合に、serializedValue（または externalValue） と同じ 意味 を持ちながらより便利な 構文 を許す意図で設計されています。application/json や任意の +json メディアタイプに対してこの構文を使用する場合、これらのフィールドは事実上 dataValue と同等に振る舞うため、安全に使用できます。

単一文字列から成るデータで、text/plain のように文字列が追加のエスケープを必要としないシリアライズターゲットの場合、これらのフィールドも安全に使用できます。

その他のシリアライズターゲットについては「JSON や YAML で自然に表現できる」という曖昧さや過去の例テーブルの誤りが、一貫性のないサポートと使用を招いています。実務上、非 JSON ターゲットに対しては value と略式 example の振る舞いが実装依存になりがちであるため、互換性を確保したい OAD 作成者は他のフィールドの使用を推奨します。

前節の注意点を念頭に置き、略式 example は Example Object が 1 つだけの場合に value の代わりに使用できることを踏まえ、どのフィールドを使うかのガイドラインは次のとおりです。

Schema Object によって検証されるように例を示すには:

• 検証スキーマに例を保ちたい場合は、Schema Object の examples 配列（JSON Schema draft 2020-12）を使用します。
  • OAS v3.0 以前との互換性が必要な場合のみ Schema Object の単体 example を使用します。
• 例をシリアライズの例として関連付けたい、またはスキーマから独立して保持したい場合は Example Object の dataValue を使用します。
  • OAS v3.1 以前との互換性が必要で、値が JSON や YAML で「自然に表現できる」場合のみ Example Object の value を使用します。

HTTP/1.1 メッセージを構築するためにどのようにシリアライズされるかを示すには:

• シリアライズが有効な Unicode 文字列として表現でき、正確な文字エンコーディングを示す必要がない場合は、Example Object の serializedValue を使用します。
  • value の文字列形式は、OAS v3.1 以前との互換性が必要な場合にのみ使用してください。
• それ以外のすべての値、または例を OpenAPI ドキュメントと分けて保持したい場合は、Example Object の externalValue を使用します。

serializedValue と externalValue はどちらもシリアライズ形を示さなければならず（MUST）、Media Type Objects では適切なメディアタイプの文書であり、Encoding Object の効果が適用されたものである必要があります。Parameter と Header オブジェクトで schema と style を使う場合は、何がシリアライズされた値に相当するかは Style Examples を参照してください。

次のいずれかが当てはまる場合、そのシリアライズは serializedValue に有効な Unicode 文字列として表現できます:

• 文字セットパラメータ charset をサポートし任意の Unicode エンコーディング（UTF-8, UTF-16 等）を示せるメディアタイプである場合。
• URI や HTTP フィールドのように Unicode エンコーディングを要求またはデフォルトとするフォーマットである場合。
• 全てのパートが上記のいずれかを満たす複合フォーマット（例: multipart/mixed で一部が application/json、他部が application/xml; charset=utf-8 の場合）である場合。

これらの場合、OAD の文字セット（JSON の相互運用文字セットとして UTF-8 を想定）から Unicode コードポイントへの変換およびその後のシリアライズ文字セットへの変換は定義されています。

externalValue の場合、文字セットが明示されておらずフォーマットやメディアタイプ規格でも決定できないときは、実装は UTF-8 を想定することがSHOULD です。

ツール実装は互換性を自動的に検証し、互換性がない場合に例の値を拒否することがMAY あります。スキーマ準備済みのデータ形式の例では、これは簡単です。

シリアライズ済みの例では、いくつかのフォーマットが同じデータに対して複数の有効な表現を許す場合があり、付録 B に示すシナリオが含まれます。シリアライズ済みの例を解析して得られたデータを検証することで曖昧さを解消できる場合もありますが、解析自体が曖昧になる場合もあり得ます。したがって、シリアライズ済み例の検証は最善努力の機能であることに注意してください。

YAML で記述する際、dataValue に対して JSON 構文を使用でき（noRating 例で示すように）必須ではありません。 この例は JSON に関する dataValue と serializedValue の振る舞いを示しますが、ほとんどの場合はデータ形式のみで十分です。

content:
  application/json:
    schema:
      type: object
      required:
      - author
      - title
      properties:
        author:
          type: string
        title:
          type: string
        rating:
          type: number
          minimum: 1
          maximum: 5
          multipleOf: 0.5
    examples:
      noRating:
        summary: A not-yet-rated work
        dataValue:
          author: A. Writer
          title: The Newest Book
      withRating:
        summary: A work with an average rating of 4.5 stars
        dataValue:
          author: A. Writer
          title: An Older Book
          rating: 4.5
        serializedValue: |
          {
            "author": "A. Writer",
            "title": "An Older Book",
            "rating": 4.5
          }

完全なバイナリデータは externalValue を使って示します:

content:
  image/png:
    schema: {}
    examples:
      Red:
        externalValue: ./examples/2-by-2-red-pixels.png

真偽値のシリアライズ方法に標準が存在しないため（付録 B 参照）、この例では特定のパラメータに対する真偽値のシリアライズを示すために dataValue と serializedValue を使用しています:

name: flag
in: query
required: true
schema:
  type: boolean
examples:
  "true":
    dataValue: true
    serializedValue: flag=true
  "false":
    dataValue: false
    serializedValue: flag=false

operationId は Operation Object で任意のフィールドであるため、代わりに URI 参照によって operationRef で参照されることがMAY あります。 これらの例はいずれも、操作のパステンプレートが曖昧にならないように Paths Object を通じて識別できる操作を参照している点に注意してください。

相対 URI 参照の 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 を使う場合、URI フラグメント内で JSON Pointer を使う際に「エスケープされたスラッシュ」(~1) が必要であり、波かっこ { と } はそれぞれ %7B と %7D として URL エンコードする必要がある点に注意してください。上の例での非エスケープ済みかつパーセントデコードされたパステンプレートは /2.0/repositories/{username} になります。

ランタイム式は参照される値の型を保持します。 式は文字列内に埋め込むことができ、その場合は式を波かっこ {} で囲みます。

これらのフィールドは content あるいは schema のいずれと共に使用することがMAY できます。

example と examples のフィールドは相互排他的です；検証要件に関するガイダンスは Working with Examples を参照してください。

このオブジェクトは Specification Extensions によって拡張されることがMAY あります。

より単純なシナリオでは、schema と style によってヘッダの構造と構文を記述できます。

schema を使ってヘッダをシリアライズする場合、URI パーセントエンコーディングはMUST NOT 適用されます；自動的に適用する RFC6570 実装を使用する場合は、その適用を取り消す必要があります。実装はヘッダの引用を試みるのではなく値をそのまま通過させることがMUST です。引用やエスケープのガイダンスは Appendix D を参照してください。

追加のガイダンスは Appendix C: Using RFC6570-Based Serialization を参照してください。

より複雑なシナリオでは、content フィールドがヘッダのメディアタイプとスキーマを定義し、その使用例を示すことができます。

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

OpenAPI Initiative は OAS ユーザーや他仕様によって定義されたフォーマットのための Format Registry を運営しています。登録済みフォーマットへの対応は厳密に OPTIONAL であり、ある登録フォーマットへの対応は他のフォーマットへの対応を意味しません。

format キーワードを伴わない型は JSON Schema の型定義に従います。特定の format を認識しないツールは MAY 型のみを使ってデフォルト処理を行い、format が指定されていないかのように扱うことがあります。 JSON Schema の検証の目的では、各フォーマットはそれが適用される JSON データ型の集合を指定すべきです。このレジストリではこれらの型が「JSON Data Type」列に示されています。

OAS によって定義されたフォーマットは次のとおりです：

Data Type の節で述べたとおり、type: number と type: integer の両方がデータモデル上は数値と見なされます。

JSON シリアライズされたデータは、JSON 表現とほぼ同等であり、JSON Schema データモデル は JSON 表現とほぼ等しいためです。 シリアライズされた UTF-8 の JSON 文字列 {"when": "1985-04-12T23:20:50.52"} は、名前が when で値が文字列 1985-04-12T23:20:50.52 のフィールドを持つオブジェクトを表します。

正確なアプリケーション形式はこの仕様の範囲外ですが、次のスキーマで示すことができます：

type: object
properties:
  when:
    type: string
    format: date-time

いくつかのアプリケーションは文字列をそのまま文字列として扱うかもしれませんが、他のアプリケーションは format を見て Python の datetime.datetime インスタンスや Java の java.time.ZonedDateTime に変換するかもしれません。 この仕様はデータがスキーマに従って有効であることと、annotations（例：format）が JSON Schema 仕様に従って利用可能であることのみを要求します。

非 JSON のシリアライズは対応するデータ形式と大きく異なることがあり、解析に複数のステップを要する場合があります。

“when” の例を続けると、オブジェクトを application/x-www-form-urlencoded としてシリアライズすると ASCII 文字列 when=1985-04-12T23%3A20%3A50.52 のようになります。 これはすべて文字列データであるため扱いやすく、JSON との違いは URI のパーセントエンコーディングと区切り構文（JSON の句読点や引用の代わりに = を使う点）だけです。

しかし、多くの非 JSON のテキストベースの形式は複雑であり、テキストをスキーマ対応のデータ構造に正しく解析するには適切なスキーマ群の検査が必要です。こうした形式にデータをシリアライズするには、検証済みデータを調べるか同等のスキーマ検査を行う必要があります。

スキーマを調査する際、起点となるスキーマが与えられたら、実装はそのスキーマとそこから $ref および allOf キーワードのみを辿って到達可能なすべてのスキーマを検査しなければなりません（MUST）。これらのスキーマは任意のインスタンスに適用されることが保証されます。 type を検索する場合に、type キーワードの値が型のリストであり、シリアライズ値がリスト内の複数の型として解析可能で、かつ他に見つかる type キーワードが実際に必要な型を識別しない場合、挙動は実装依存になります。 type を含まない Schema Objects は、他のキーワードが存在してもすべての型を許容すると見なされなければなりません（例：maximum は数値に適用されますが、インスタンスが数値であることを要求するものではありません）。

実装は oneOf や $dynamicRef のような他のキーワードのサブスキーマや参照先を調査しても良いですが（MAY）、曖昧さを解決しようとしてはなりません（MUST NOT）。 例えば anyOf を調査する場合、次のスキーマは数値型を明確に示しますが：

anyOf:
- type: number
  minimum: 0
- type: number
  maximum: 100

次のスキーマはそうではありません。なぜなら第二のサブスキーマがすべての型を許容するためです：

anyOf:
- type: number
- maximum: 100

これらの限定的なスキーマ検索要件により、検証済みデータにアクセスできるシリアライザは可能であればデータを検査しなければなりません（MUST）。ランタイムデータを扱わない実装（例：コードジェネレータ）や何らかの理由で検証済みデータにアクセスできない実装は、スキーマ検査にフォールバックしなければなりません（MUST）。

また JSON Schema では特定の型に適用されるキーワード（例：pattern は文字列、minimum は数値）は、そのデータが実際にその型であることを要求・暗示しないことを思い出してください。

これらのプロセスの例として、次の OpenAPI コンポーネントがあるとします：

components:
  requestBodies:
    Form:
      content:
        application/x-www-form-urlencoded:
          schema:
            $ref: "#/components/schemas/FormData"
          encoding:
            extra:
              contentType: application/xml
  schemas:
    FormData:
      type: object
      properties:
        code:
          allOf:
          - type: [string, number]
            pattern: "1"
            minimum: 0
          - type: string
            pattern: "2"
        count:
          type: integer
        extra:
          type: object

そして次のリクエストボディをデータ形式に解析する場合：

code=1234&count=42&extra=%3Cinfo%3Eabc%3C/info%3E

まず properties などのプロパティ定義キーワードをスキーマ内で検索し、それぞれのプロパティスキーマをそのプロパティの type キーワードを検索するための起点として使用する必要があります。順序は実装依存ですが例としては次のとおりです：

• #/components/requestBodies/Form/content/application~1x-www-form-urlencoded/schema （初期の起点スキーマ、$ref のみ）
• #/components/schemas/FormData（$ref を辿り properties を発見）
• #/components/schemas/FormData/properties/code（code プロパティの起点スキーマ）
• #/components/schemas/FormData/properties/code/allOf/0（allOf を辿り type: [string, number] を発見）
• #/components/schemas/FormData/properties/code/allOf/1（allOf を辿り type: string を発見）
• #/components/schemas/FormData/properties/count（count プロパティの起点スキーマ、type: integer を発見）
• #/components/schemas/FormData/properties/extra（extra プロパティの起点スキーマ、type: object を発見）

code に関しては最初に曖昧な type を見つけ、その後に別の type キーワードを見つけて二つの可能性のうち一方のみが有効であることが確定した点に注意してください。

この検査から、code は数値のように見える文字列であり、count はスキーマ検証の前に数値に解析する必要があることが判定されます。さらに extra は実際には info プロパティを含むオブジェクトの XML シリアライズであることがわかります。 つまりこのシリアライズのデータ形式は次の JSON オブジェクトに相当します：

{
  "code": "1234",
  "count": 42
  "extra": {
    "info": "abc"
  }
}

このオブジェクトをシリアライズするには Encoding Objects とプロパティを関連付ける必要があり、contentType フィールドのデフォルト値を決めるための調査が必要になる場合があります。検証済みデータが利用できない場合、スキーマ検査のプロセスは解析時と同じになります。

この例では code と count はプリミティブ型で encoding フィールドに現れないためプレーンテキストとしてシリアライズされます。しかし extra フィールドはオブジェクトであり、デフォルトでは JSON としてシリアライズされますが、encoding フィールドの extra エントリはそれを代わりに XML でシリアライズするよう指示しています。

OAS は raw（生）バイナリデータと encoded（エンコード済み）バイナリデータのいずれも記述できます。

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

次の表ではスキーマオブジェクトのキーワードをバイナリデータに使う方法を示すために image/png を例として用います。任意のバイナリメディアタイプ（例：application/octet-stream）でバイナリを示すのに十分です。

contentEncoding が示すエンコーディングはデータを 7 ビット ASCII テキストで表現するためにサイズを拡張するものであり、メッセージボディがどのように圧縮されているかを示す HTTP の Content-Encoding ヘッダとは無関係です。HTTP はエンコードされていないバイナリメッセージボディを許容するため、全体のメッセージボディが base64 等でエンコードされていることを示す標準の HTTP ヘッダは存在しません。

contentEncoding に base64url を使うと、（クエリ文字列や application/x-www-form-urlencoded 型のメッセージボディで必要な）URL エンコーディングが既にエンコード済みのバイナリデータをさらにエンコードする必要がなくなります。

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

• Media Type Object のキーとして
• Encoding Object の contentType フィールド内で

Schema Object が非 OAS 対応の JSON Schema 実装によって処理される場合、冗長であっても contentMediaType を含めることが有用な場合があります。ただし、contentMediaType が関連する Media Type Object や Encoding Object と矛盾する場合、contentMediaType は SHALL 無視されます。

ストリーミングバイナリペイロードについては Complete vs Streaming Content を参照してください。

format キーワード（デフォルトの format-annotation 語彙を使用する場合） や contentMediaType, contentEncoding, および contentSchema キーワード はデータに対する制約を定義しますが、直接検証されるのではなく注釈として扱われます。拡張検証はこれらの制約を適用する一つの方法です（MAY）。

readOnly と writeOnly キーワードは注釈です。JSON Schema は検証対象データがどのように使用されるかを認識しないためです。 これらのキーワードの検証は注釈、読み取りまたは書き込みの方向、および（該当する場合）フィールドの現在の値をチェックすることで行われることが MAY あります。 JSON Schema Validation Draft 2020-12 セクション9.4 はこれらのキーワードの期待動作を定義しており、リソース（「所有権を持つ権限」と記述される）は MAY readOnly フィールドを無視するかエラーとして扱うことができます。

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

readOnly の振る舞いは特に本仕様のバージョン 3.0 で指定されていたものと異なる点があることに注意してください。

OpenAPI 仕様は JSON Schema の allOf キーワードを使用してモデル定義の結合や拡張を可能にし、実質的にモデルのコンポジションを提供します。allOf は独立して検証されるオブジェクト定義の配列を取り、それらが組み合わさって単一のオブジェクトを構成します。

コンポジションはモデルの拡張性を提供しますが、モデル間の階層を意味するものではありません。

JSON Schema はまた anyOf と oneOf キーワードを提供しており、それぞれ少なくとも一つ、または正確に一つのスキーマが有効であることを定義できます。allOf と同様に、これらのスキーマは独立して検証されます。これらのキーワードは単一フィールドが複数の値の型を受け入れるポリモーフィズムを記述するために使用できます。

OpenAPI 仕様はポリモーフィズムのサポートを拡張して discriminator フィールド（値は Discriminator Object）を追加します。使用時、Discriminator Object は anyOf や oneOf のどのスキーマがモデルの構造を検証することが期待されるかを示すプロパティ名を指示します。 識別プロパティは MAY 必須または任意として定義できますが、任意として定義される場合、Discriminator Object はどの anyOf または oneOf のスキーマ、あるいは allOf 内で現在のスキーマを参照するどのスキーマが識別プロパティが存在しないときにモデルの構造を検証するかを指定する defaultMapping フィールドを含めなければなりません（MUST）。

継承インスタンスの識別プロパティの値を定義する方法は二つあります：

• スキーマ名を使用する。
• スキーマ名を上書きする — プロパティを新しい値で上書きします。新しい値が存在する場合、それがスキーマ名に優先します。

実装は JSON Schema の動的参照機能を使用してジェネリックまたはテンプレートデータ構造を定義することを SHOULD サポートするべきです：

• $dynamicAnchor は $dynamicRef が解決できる可能性のあるスキーマ群（デフォルトのプレースホルダスキーマを含む）を識別します。
• $dynamicRef はスキーマの起点から参照までのパス上で最初に見つかる一致する $dynamicAnchor に解決します（JSON Schema 仕様の説明による）。

例は下の Schema Object Examples セクションに含まれており、詳細は Learn OpenAPI サイトの “Dynamic References” ページを参照してください。

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

実装は各サブスキーマが const キーワードと title や description のような注釈を含む oneOf や anyOf を列挙型として追加情報付きで認識することを MAY サポートする場合があります。このパターンの正確な振る舞いは JSON Schema によって要求される範囲を超えて実装依存です。

xml フィールドは JSON 定義を XML に変換する際の追加定義を許します。 XML Object は利用可能なオプションに関する追加情報を含みます。

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
additionalProperties:
  type: string

文字列→モデルのマッピングの場合：

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

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

次の例は Pet モデルを示しており、petType プロパティによって猫か犬かを表現できます。各ペット種にはベースの Pet モデル以外の追加プロパティがあります。petType プロパティが存在しない、または cat や dog に一致しない値の場合、そのインスタンスは無効です。

components:
  schemas:
    Pet:
      type: object
      properties:
        name:
          type: string
      required:
        - name
        - petType
      oneOf:
        - $ref: '#/components/schemas/Cat'
        - $ref: '#/components/schemas/Dog'
    Cat:
      description: A pet cat
      type: object
      properties:
        petType:
          const: 'cat'
        huntingSkill:
          type: string
          description: The measured skill for hunting
          enum:
            - clueless
            - lazy
            - adventurous
            - aggressive
      required:
        - huntingSkill
    Dog:
      description: A pet dog
      type: object
      properties:
        petType:
          const: 'dog'
        packSize:
          type: integer
          format: int32
          description: the size of the pack the dog is from
          default: 0
          minimum: 0
      required:
        - packSize

次の例は前節の例を拡張し、Pet スキーマに Discriminator Object を追加しています。Discriminator Object は API の利用者へのヒントにすぎず、スキーマの検証結果を変更するものではないことに注意してください。

components:
  schemas:
    Pet:
      type: object
      discriminator:
        propertyName: petType
        mapping:
          cat: '#/components/schemas/Cat'
          dog: '#/components/schemas/Dog'
      properties:
        name:
          type: string
      required:
        - name
        - petType
      oneOf:
        - $ref: '#/components/schemas/Cat'
        - $ref: '#/components/schemas/Dog'
    Cat:
      description: A pet cat
      type: object
      properties:
        petType:
          const: 'cat'
        huntingSkill:
          type: string
          description: The measured skill for hunting
          enum:
            - clueless
            - lazy
            - adventurous
            - aggressive
      required:
        - huntingSkill
    Dog:
      description: A pet dog
      type: object
      properties:
        petType:
          const: 'dog'
        packSize:
          type: integer
          format: int32
          description: the size of the pack the dog is from
          default: 0
          minimum: 0
      required:
        - petType
        - packSize

allOf を使ってポリモーフィックなモデルを記述することも可能です。次の例は allOf と Discriminator Object を用いてポリモーフィックな Pet モデルを説明しています。

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