データ型

スキーマのデータ型は type キーワードによって定義されます（例：type: string）。OpenAPI は以下の基本型を定義しています

string（日付とファイルを含む）
数
整数
ブール値
配列
オブジェクト

これらの型は、名前は異なる場合がありますが、ほとんどのプログラミング言語に存在します。これらの型を使用することで、あらゆるデータ構造を記述できます。

なお、null 型は存在しません。代わりに、ベース型の修飾子として nullable 属性が使用されます。

追加の type 固有のキーワードを使用して、データ型をさらに詳細化できます（例：文字列の長さを制限したり、可能な値のenumを指定したりする）。

混合型

type は単一の値を取ります。type をリストとして指定することは OpenAPI では無効です（JSON Schema では有効ですが）。

1
# Incorrect
2
type:
3
  - string
4
  - integer

混合型は、代替型のリストを指定する oneOf および anyOf を使用して記述できます。

1
# Correct
2
oneOf:
3
  - type: string
4
  - type: integer

任意の型も参照してください。

数値

OpenAPI には number と integer の 2 つの数値型があります。number には整数と浮動小数点数の両方が含まれます。オプションの format キーワードは、ツールが特定の数値型を使用するためのヒントとして機能します。

`タイプ`	`フォーマット`	説明
数	–	任意の数値。
数	浮動小数点数	浮動小数点数。
数	ダブル	倍精度浮動小数点数。
整数	–	整数。
整数	int32	符号付き32ビット整数（一般的に使用される整数型）。
整数	int64	符号付き64ビット整数（`long`型）。

「17」のような数値を含む文字列は、文字列として扱われ、数値とはみなされません。

最小値と最大値

minimum および maximum キーワードを使用して、可能な値の範囲を指定します。

1
type: integer
2
minimum: 1
3
maximum: 20

デフォルトでは、minimum および maximum の値は範囲に含まれます。

1
minimum ≤ value ≤ maximum

境界値を除外するには、exclusiveMinimum: true および exclusiveMaximum: true を指定します。例えば、浮動小数点数の範囲を 0～50 と定義し、0 の値を除外することができます。

1
type: number
2
minimum: 0
3
exclusiveMinimum: true
4
maximum: 50

exclusiveMinimum および exclusiveMaximum の「exclusive」という単語は、対応する境界が *除外される* ことを意味します。

キーワード	説明
`exclusiveMinimum: false` または含まれない場合	値 ≥ `minimum`
`exclusiveMinimum: true`	値 > `minimum`
`exclusiveMaximum: false` または含まれない場合	値 ≤ `maximum`
`exclusiveMaximum: true`	値 < `maximum`

倍数

multipleOf キーワードを使用して、数値が別の数値の倍数でなければならないことを指定します。

1
type: integer
2
multipleOf: 10

上記の例は、10、20、30、0、-10、-20 などに一致します。multipleOf は浮動小数点数でも使用できますが、実際には浮動小数点演算の精度の制限により信頼性が低い場合があります。

1
type: number
2
multipleOf: 2.5

multipleOf の値は正の数値でなければなりません。つまり、multipleOf: -5 は使用できません。

文字列

文字列は次のように定義されます。

1
type: string

文字列の長さは minLength および maxLength を使用して制限できます。

1
type: string
2
minLength: 3
3
maxLength: 20

minLength または pattern が指定されていない限り、空の文字列 "" は有効な文字列であることに注意してください。

文字列のフォーマット

オプションの format 修飾子は、文字列の内容とフォーマットに関するヒントとして機能します。OpenAPI は以下の組み込み文字列フォーマットを定義しています。

date – RFC 3339, セクション 5.6 で定義されている完全日付表記。例： _2017-07-21_
date-time – RFC 3339, セクション 5.6 で定義されている日時表記。例： _2017-07-21T17:32:28Z_
password – UI に入力をマスクするようヒントを与える。
byte – Base64 エンコードされた文字。例： _U3dhZ2dlciByb2Nrcw==_
binary – バイナリデータ。ファイルを表すために使用されます（以下のファイルを参照）。

ただし、format はオープンな値なので、OpenAPI Specification で定義されていない形式であっても、次のような任意の形式を使用できます。

メール
uuid
uri
ホスト名
ipv4
ipv6
その他

ツールは format を使用して入力を検証したり、選択したプログラミング言語の特定の型に値をマッピングしたりできます。特定のフォーマットをサポートしていないツールは、format が指定されていない場合と同様に、デフォルトで type のみを使用する場合があります。

パターン

pattern キーワードを使用すると、文字列値の正規表現テンプレートを定義できます。このテンプレートに一致する値のみが受け入れられます。使用される正規表現構文は JavaScript（より具体的には ECMA 262）のものです。正規表現は大文字と小文字を区別します。つまり、[a-z] と [A-Z] は異なる表現です。例えば、以下のパターンは 123-45-6789 形式の社会保障番号（SSN）に一致します。

1
ssn:
2
  type: string
3
  pattern: '^\d{3}-\d{2}-\d{4}$'

正規表現は ^…$ トークンで囲まれていることに注意してください。^ は文字列の先頭を意味し、$ は文字列の末尾を意味します。^…$ がないと、pattern は部分一致として機能します。つまり、指定された正規表現を *含む* 任意の文字列に一致します。例えば、pattern: pet は *pet*、*petstore*、*carpet* に一致します。^…$ トークンは厳密な一致を強制します。

ブーリアン

type: boolean は true と false の 2 つの値を表します。真値や偽値（例：「true」、「」、0、null）はブール値とはみなされないことに注意してください。

Null

OpenAPI 3.0 には JSON Schema のような明示的な null 型はありませんが、nullable: true を使用して値が null である可能性があることを指定できます。null は空の文字列 "" とは異なることに注意してください。

1
# Correct
2
type: integer
3
nullable: true
4

5
# Incorrect
6
type: null
7

8
# Incorrect as well
9
type:
10
  - integer
11
  - null

上記の例は、C# の nullable 型 int? や Java の java.lang.Integer にマップされる場合があります。オブジェクトでは、nullable なプロパティは optional なプロパティとは異なりますが、一部のツールでは optional なプロパティを null 値にマップすることを選択する場合があります。

配列

配列は次のように定義されます。

1
type: array
2
items:
3
  type: string

JSON Schema とは異なり、配列では items キーワードが必須です。items の値は、配列項目の型と形式を記述するスキーマです。配列はネストできます。

1
# [ [1, 2], [3, 4] ]
2
type: array
3
items:
4
  type: array
5
  items:
6
    type: integer

そしてオブジェクトを含めることができます。

1
# [ {"id": 5}, {"id": 8} ]
2
type: array
3
items:
4
  type: object
5
  properties:
6
    id:
7
      type: integer

項目スキーマはインラインで（前の例のように）指定することも、$ref を介して参照することもできます。

1
# Array of Pets
2
type: array
3
items:
4
  $ref: "#/components/schemas/Pet"

混合型配列

混合型配列は oneOf を使用して定義できます。

1
# ["foo", 5, -2, "bar"]
2
type: array
3
items:
4
  oneOf:
5
    - type: string
6
    - type: integer

oneOf はインラインのサブスキーマ（上記の例のように）と参照の両方を許可します。

1
# Array of Cats and Dogs
2
type: array
3
items:
4
  oneOf:
5
    - $ref: "#/components/schemas/Cat"
6
    - $ref: "#/components/schemas/Dog"

任意の型の配列は次のように定義できます。

1
type: array
2
items: {}

1
# [ "hello", -2, true, [5.7], {"id": 5} ]

ここで、{} は「任意の型」スキーマです（以下を参照）。items の次の構文は無効であることに注意してください。

1
# Incorrect
2
items:
3
  - type: string
4
  - type: integer
5

6
# Incorrect as well
7
items:
8
  type:
9
    - string
10
    - integer

配列の長さ

配列の最小長と最大長は次のように定義できます。

1
type: array
2
items:
3
  type: integer
4
minItems: 1
5
maxItems: 10

minItems がなければ、空の配列は有効とみなされます。

uniqueItems

uniqueItems: true を使用して、配列内のすべての項目が一意でなければならないことを指定できます。

1
type: array
2
items:
3
  type: integer
4
uniqueItems: true
5
# [1, 2, 3] – valid
6
# [1, 1, 3] – not valid
7
# [ ] – valid

オブジェクト

オブジェクトはプロパティと値のペアのコレクションです。properties キーワードはオブジェクトのプロパティを定義するために使用されます。プロパティ名をリストし、各プロパティのスキーマを指定する必要があります。

1
type: object
2
properties:
3
  id:
4
    type: integer
5
  name:
6
    type: string

ヒント: OpenAPI では、オブジェクトは通常、リクエストおよびレスポンスの定義にインラインで定義するのではなく、グローバルな components/schemas セクションで定義されます。

必須プロパティ

デフォルトでは、すべてのオブジェクトプロパティはオプションです。required リストで必須プロパティを指定できます。

1
type: object
2
properties:
3
  id:
4
    type: integer
5
  username:
6
    type: string
7
  name:
8
    type: string
9
required:
10
  - id
11
  - username

required はオブジェクトレベルの属性であり、プロパティ属性ではないことに注意してください。

1
type: object
2
properties:
3
  id:
4
    type: integer
5
    required: true # Wrong!
6

7
required: # Correct
8
  - id

空のリスト required: [] は無効です。すべてのプロパティがオプションである場合、required キーワードは指定しないでください。

読み取り専用および書き込み専用プロパティ

readOnly および writeOnly キーワードを使用して、特定のプロパティを読み取り専用または書き込み専用としてマークできます。これは、例えば、GET が POST で使用されるよりも多くのプロパティを返す場合に便利です。GET と POST の両方で同じスキーマを使用し、余分なプロパティを readOnly としてマークすることができます。readOnly プロパティはレスポンスに含まれますがリクエストには含まれず、writeOnly プロパティはリクエストで送信できますがレスポンスには含まれません。

1
type: object
2
properties:
3
  id:
4
    # Returned by GET, not used in POST/PUT/PATCH
5
    type: integer
6
    readOnly: true
7
  username:
8
    type: string
9
  password:
10
    # Used in POST/PUT/PATCH, not returned by GET
11
    type: string
12
    writeOnly: true

readOnly または writeOnly プロパティが required リストに含まれている場合、required は関連するスコープ（レスポンスのみ、またはリクエストのみ）にのみ影響します。つまり、読み取り専用の必須プロパティはレスポンスにのみ適用され、書き込み専用の必須プロパティはリクエストにのみ適用されます。

ネストされたオブジェクト

オブジェクトにはネストされたオブジェクトを含めることができます。

1
components:
2
  schemas:
3
    User:
4
      type: object
5
      properties:
6
        id:
7
          type: integer
8
        name:
9
          type: string
10
        contact_info:
11
          # The value of this property is an object
12
          type: object
13
          properties:
14
            email:
15
              type: string
16
              format: email
17
            phone:
18
              type: string

ネストされたオブジェクトを複数のスキーマに分割し、$ref を使用してネストされたスキーマを参照することができます。

1
components:
2
  schemas:
3
    User:
4
      type: object
5
      properties:
6
        id:
7
          type: integer
8
        name:
9
          type: string
10
        contact_info:
11
          $ref: "#/components/schemas/ContactInfo"
12

13
    ContactInfo:
14
      type: object
15
      properties:
16
        email:
17
          type: string
18
          format: email
19
        phone:
20
          type: string

自由形式のオブジェクト

自由形式のオブジェクト（任意のプロパティ/値ペア）は次のように定義されます。

1
type: object

これは以下と同等です。

1
type: object
2
additionalProperties: true

そして

1
type: object
2
additionalProperties: {}

プロパティの数

minProperties および maxProperties キーワードを使用すると、オブジェクトに許可されるプロパティの数を制限できます。これは additionalProperties や自由形式のオブジェクトを使用する場合に役立ちます。

1
type: object
2
minProperties: 2
3
maxProperties: 10

この例では、{"id": 5, "username": "trillian"} はスキーマに一致しますが、{"id": 5} は一致しません。

ファイル

OpenAPI 2.0 とは異なり、Open API 3.0 には file 型はありません。ファイルは文字列として定義されます。

1
type: string
2
format: binary # binary file contents

または

1
type: string
2
format: byte # base64-encoded file contents

これは、希望するファイル転送方法によって異なります。詳細については、「ファイルのアップロード」、「multipart リクエスト」、および「ファイルを返すレスポンス」を参照してください。

任意の型

型のないスキーマは、数値、文字列、オブジェクトなど、あらゆるデータ型に一致します。{} は任意の型スキーマの短縮構文です。

1
components:
2
  schemas:
3
    AnyValue: {}

説明を提供したい場合

1
components:
2
  schemas:
3
    AnyValue:
4
      description: Can be any value - string, number, boolean, array or object.

上記は以下と同等です。

1
components:
2
  schemas:
3
    AnyValue:
4
      anyOf:
5
        - type: string
6
        - type: number
7
        - type: integer
8
        - type: boolean
9
        - type: array
10
          items: {}
11
        - type: object

null 値を許可する必要がある場合は、nullable: true を追加します。

1
components:
2
  schemas:
3
    AnyValue:
4
      nullable: true
5
      description: Can be any value, including `null`.

お探しのものが見つかりませんでしたか？コミュニティに質問する
間違いを見つけましたか？お知らせください