Media Typeオブジェクト

各メディア タイプ オブジェクトは、そのキーによって識別されるメディア タイプのスキーマと例を提供します。

固定フィールド

フィールド名	タイプ	説明
スキーマ	スキーマオブジェクト	リクエスト、レスポンス、パラメータの内容を定義するスキーマ。
例	どれでも	メディアタイプの例。サンプル オブジェクトは、メディア タイプで指定された正しい形式である必要があります。exampleフィールドとexamplesフィールドは相互に排他的です。さらに、例を含むschema を参照する場合、example値はスキーマによって提供される例をオーバーライドするものとします(SHALL )。
例	Map[ string,オブジェクトの例| 参照オブジェクト]	メディアタイプの例。各サンプル オブジェクトは、メディア タイプおよび指定されたスキーマ (存在する場合) と一致する必要があります (SHOULD)。examplesフィールドとexampleフィールドは相互に排他的です。さらに、例を含む schemaを参照する場合、examples値はスキーマによって提供される例をオーバーライドするものとします(SHALL )。
エンコーディング	Map[ string,エンコーディング オブジェクト]	プロパティ名とそのエンコード情報の間のマップ。キーはプロパティ名であり、プロパティとしてスキーマ内に存在する必要があります。エンコーディング オブジェクトは、requestBodyメディア タイプがmultipartまたはapplication/x-www-form-urlencoded の場合にのみオブジェクトに適用されます。

このオブジェクトは、仕様拡張機能を使用して拡張できます。

Media Typeの例

{
  "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'

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

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

3.0 仕様とは対照的に、formatキーワードはスキーマのコンテンツ エンコーディングには影響しません。JSON スキーマには、スキーマの指定に使用できるcontentEncodingキーワードが用意されています。このContent-Encodingキーワードは、「base64」と「base64url」、およびRFC2045の「quoted-printable」を含む、 RFC4648で定義されているすべてのエンコーディングをサポートします。contentEncodingキーワードで指定されたエンコーディングは、リクエストまたは応答のヘッダー、またはマルチパート ボディのメタデータで指定されたエンコーディングとは独立しています。両方が存在する場合、最初に contentEncodingで指定されたエンコーディングが適用され、次にContent-Typeヘッダーで指定されたエンコーディングが適用されます。

JSON スキーマにはcontentMediaTypeキーワードも用意されています。ただし、メディアタイプがメディアタイプオブジェクトのキーまたはエンコーディングオブジェクトcontentTypeのフィールドによってすでに指定されている場合、contentMediaTypeキーワードが存在しても無視されます(SHALL)。

例:

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

# a PNG image as a binary file:content:    image/png: {}
# an arbitrary binary file:content:    application/octet-stream: {}

Base64 エンコードで転送されたバイナリ コンテンツ:

content:    image/png:        schema:            type: string            contentMediaType: image/png            contentEncoding: base64

ペイロードのセマンティクスを説明するContent-Type がimage/pngと残っていることに注意してください。JSON スキーマtypeとcontentEncodingフィールドは、ペイロードがテキストとして転送されることを説明しています。JSON スキーマcontentMediaTypeは技術的には冗長ですが、OpenAPI コンテキストを認識しない JSON スキーマ ツールでも使用できます。

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

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

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メディア タイプを使用する必要があります。

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

以下のmultipart/form-dataセクションに示すように、items の空のスキーマはapplication/octet-streamメディア タイプを示します。

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

RFC1866経由でフォーム URL エンコードを使用してコンテンツを送信するには、次の定義を使用できます。

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: {}

この例では、サーバーに渡されるときに、その内容はRFC1866に従って文字列化されなければなりません。さらに、addressフィールド複合オブジェクトは文字列化されます。

application/x-www-form-urlencodedコンテンツ タイプで複雑なオブジェクトを渡す場合、そのようなプロパティのデフォルトのシリアル化戦略は、Encoding Object のstyleプロパティに formとして記述されます。

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

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

multipart/form-dataリクエスト本文では、各スキーマ プロパティ、またはスキーマ配列プロパティの各要素が、 RFC7578で定義されている内部ヘッダーを持つペイロード内のセクションを受け取ります。multipart/form-dataリクエスト本文の各プロパティのシリアル化戦略は、Encoding Object関連付けられた .html ファイルで指定できます。

multipartタイプを渡すとき、転送されるコンテンツのセクションを区切るために境界を使用できます (MAY)。したがって、次のデフォルトContent-Typeがmultipartに定義されています。

• プロパティがプリミティブまたはプリミティブ値の配列である場合、デフォルトの Content-Type はtext/plainのとおりです。
• プロパティが複雑な場合、または複雑な値の配列の場合、デフォルトの Content-Type はapplication/jsonのとおりです。
• プロパティが contentEncoding付きのtype: stringの場合、デフォルトの Content-Type はapplication/octet-streamのとおりです。

JSON スキーマ仕様に従って、contentEncoding: identityが存在する場合、contentEncodingが存在しないcontentMediaTypeは扱われます。text/htmlをJSON 文字列になどにテキスト ドキュメントを埋め込む場合には便利ですが、ドキュメントが実際のメディア タイプの代わりにmultipart/form-data扱われるだけであるため、一部には役に立ちません。contentEncodingが必要ない場合、エンコーディング オブジェクトはcontentMediaTypeを使用せずに使用します。

例:

requestBody:  content:    multipart/form-data:      schema:        type: object        properties:          id:            type: string            format: uuid          address:            # default Content-Type for objects is `application/json`            type: object            properties: {}          profileImage:            # Content-Type for application-level encoded resource is `text/plain`            type: string            contentMediaType: image/png            contentEncoding: base64          children:            # default Content-Type for arrays is based on the _inner_ type (`text/plain` here)            type: array            items:              type: string          addresses:            # default Content-Type for arrays is based on the _inner_ type (object shown, so `application/json` in this example)            type: array            items:              type: object              $ref: '#/components/schemas/Address'

multipartリクエスト本文の一部のシリアル化を制御できるようにするために、encoding属性が導入されました。この属性は、およびリクエスト本文のmultipartとapplication/x-www-form-urlencodedにのみ適用されます。

{
  "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'

Encodingオブジェクト

単一のスキーマ プロパティに適用される単一のエンコード定義。

固定フィールド

フィールド名	タイプ	説明
コンテンツタイプ	string	特定のプロパティをエンコードするための Content-Type。デフォルト値はプロパティのタイプによって異なります。objectの場合はapplication/json、 arrayの場合は、 デフォルトは内部型に基づいて定義されます。その他すべての場合、デフォルトは application/octet-streamです。値には、特定のメディア タイプ (例: application/json)、ワイルドカード メディア タイプ (例: image/*)、または 2 つのタイプのカンマ区切りリストを指定できます。
ヘッダー	Map[ string,ヘッダー オブジェクト| 参照オブジェクト]	追加情報をヘッダーとして提供できるようにするマップ、例えば、Content-Disposition。 Content-Typeについては別途説明されており、このセクションでは無視されます。リクエスト本文のメディアタイプが でない場合、このプロパティは無視されるものとします (SHALL) multipart。
スタイル	string	特定のプロパティ値がその型に応じてどのようにシリアル化されるかを説明します。styleプロパティの詳細については、「パラメータ オブジェクト」を参照してください。動作は、デフォルト値を含むqueryパラメータと同じ値に従います。リクエスト本文のメディアタイプがapplication/x-www-form-urlencodedまたはmultipart/form-dataでない場合、このプロパティは無視されます。値が明示的に定義されている場合、contentType(暗黙的または明示的) の値は無視されます(SHALL)。
Explode	boolean	これが true の場合、 arrayかobject型のプロパティ値は、配列の値ごと、またはマップのキーと値のペアに対して個別のパラメーターを生成します。他のタイプのプロパティの場合、このプロパティは効果がありません。styleがformの場合、デフォルト値は trueです。他のすべてのスタイルの場合、デフォルト値はfalse です。リクエスト本文のメディアタイプがapplication/x-www-form-urlencodedまたはmultipart/form-dataでない場合、このプロパティは無視されます。値が明示的に定義されている場合、contentType(暗黙的または明示的) の値は無視されます(SHALL)。
許可予約済み	boolean	RFC3986:/?#[]@!$&'()*+,;= で定義されているように、パーセント エンコーディングなしでパラメータ値に予約文字を含めることを許可する必要があるかどうかを決定します。デフォルト値は ですfalse。リクエスト本文のメディアタイプがapplication/x-www-form-urlencodedまたはmultipart/form-dataでない場合、このプロパティは無視されます。値が明示的に定義されている場合、contentType(暗黙的または明示的) の値は無視されます(SHALL)。

このオブジェクトは、仕様拡張機能を使用して拡張できます。

Encodingオブジェクトの例

requestBody:  content:    multipart/form-data:      schema:        type: object        properties:          id:            # default is text/plain            type: string            format: uuid          address:            # default is application/json            type: object            properties: {}          historyMetadata:            # need to declare XML format!            description: metadata in XML format            type: object            properties: {}          profileImage: {}      encoding:        historyMetadata:          # require XML Content-Type in utf-8 encoding          contentType: application/xml; charset=utf-8        profileImage:          # only accept png/jpeg          contentType: image/png, image/jpeg          headers:            X-Rate-Limit-Limit:              description: The number of allowed requests in the current period              schema:                type: integer