メインコンテンツまでスキップ

Schemaオブジェクト

Schemaオブジェクトを使用すると、入力データ型と出力データ型を定義できます。これらの型はオブジェクトである場合もありますが、プリミティブや配列である場合もあります。このオブジェクトは、JSON スキーマ仕様ドラフト 2020-12のスーパーセットです。

プロパティの詳細については、「JSON スキーマ コア」および「JSON スキーマの検証」を参照してください。

特に明記されていない限り、プロパティ定義は JSON スキーマの定義に従い、追加のセマンティクスは追加されません。JSON スキーマは、動作がアプリケーションによって定義されることを示します (注釈など)。OAS は、OpenAPI ドキュメントを使用するアプリケーションにセマンティクスの定義も委ねます。

プロパティ​

OpenAPI スキーマ オブジェクト言語は、JSON スキーマ ドラフト 2020-12汎用メタスキーマで指定されている語彙に加えて、OAS 基本語彙を必要とするものとして定義されています。

このバージョンの仕様の OpenAPI スキーマ オブジェクト言語は、URI https://spec.openapis.org/oas/3.1/dialect/base(「OAS 方言スキーマ ID」)。

次のプロパティは JSON スキーマ仕様から取得されていますが、その定義は OAS によって拡張されています。

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

OpenAPI 仕様の基本語彙は、次のキーワードで構成されています。

固定フィールド​

フィールド名タイプ説明
識別子識別子オブジェクトポリモーフィズムのサポートを追加します。識別子は、ペイロードの説明を満たす他のスキーマを区別するために使用されるオブジェクト名です。詳細については、「構成と継承」を参照してください。
XMLXMLオブジェクトこれはプロパティ スキーマでのみ使用できます (MAY)。ルート スキーマには影響しません。このプロパティの XML 表現を記述する追加のメタデータを追加します。
外部ドキュメント外部ドキュメントオブジェクトこのスキーマに関する追加の外部ドキュメント。
例どれでもこのスキーマのインスタンスの例を含む自由形式のプロパティ。JSON または YAML で自然に表現できない例を表現するには、文字列値を使用して、必要に応じてエスケープして例を含めることができます。
非推奨:このexampleプロパティは、JSON Schema examplesキーワードに代わって非推奨になりました。exampleの使用は推奨されず、この仕様の以降のバージョンでは削除される可能性があります。

このオブジェクトは仕様拡張で拡張できます 。ただし、前述したように、追加のプロパティではこのオブジェクト内のx-接頭辞を省略できます。

構成と継承 (ポリモーフィズム)​

OpenAPI 仕様では、JSON スキーマのallOfプロパティを使用してモデル定義を結合および拡張することができ、実質的にモデルの合成が可能になります。 allOfは、個別に検証されますが、一緒になって 1 つのオブジェクトを構成するオブジェクト定義の配列を受け取ります。

合成はモデルの拡張性を提供しますが、モデル間の階層を意味するものではありません。ポリモーフィズムをサポートするために、OpenAPI 仕様ではdiscriminatorフィールドが追加されています。使用すると、 discriminatorはモデルの構造を検証するスキーマ定義を決定するプロパティの名前になります。したがって、このdiscriminatorフィールドは必須フィールドでなければなりません。継承インスタンスの識別子の値を定義するには 2 つの方法があります。

  • スキーマ名を使用します。
  • プロパティを新しい値でオーバーライドして、スキーマ名をオーバーライドします。新しい値が存在する場合、これがスキーマ名より優先されます。そのため、指定された ID を持たないインライン スキーマ定義はポリモーフィズムで使用できません。

XMLモデリング​

xmlプロパティを使用すると、JSON 定義を XML に変換するときに追加の定義が可能になります。XML オブジェクトには、使用可能なオプションに関する追加情報が含まれています。

Schemaダイアレクトの指定​

ツールにとって、特定のリソースがどの方言またはメタスキーマで処理されるかを決定できることが重要です: JSON スキーマ コア、JSON スキーマ検証、OpenAPI スキーマ方言、またはカスタム メタスキーマ。

$schemaキーワードは任意のルート スキーマ オブジェクトに存在してもよく (MAY)、存在する場合は、スキーマを処理するときにどの方言を使用するかを決定するために使用しなければなりません (MUST)。これにより、デフォルトのドラフト 2020-12 サポート以外の JSON スキーマのドラフトに準拠するスキーマ オブジェクトを使用できるようになります。ツールはOASダイアレクトスキーマ idをサポートしなければならず (MUST )、追加の$schema値 をサポートしてもよい (MAY) 。

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

スキーマ オブジェクトが OAS ドキュメントではない外部リソース ( JSON スキーマ リソースなど) から参照される場合、そのリソース内のスキーマの$schemaキーワードの値はJSON スキーマ ルールに従わなければなりません (MUST )。

スキーマオブジェクトの例​

プリミティブサンプル​

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

シンプルモデル​

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

マップ/ディクショナリ プロパティを持つモデル​

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

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

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

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

例のあるモデル​

{  "type": "object",  "properties": {    "id": {      "type": "integer",      "format": "int64"    },    "name": {      "type": "string"    }  },  "required": [    "name"  ],  "example": {    "name": "Puma",    "id": 1  }}
type: objectproperties:  id:    type: integer    format: int64  name:    type: stringrequired:- nameexample:  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 discriminator 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 discriminator 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 discriminator 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 discriminator 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