はじめに
OpenAPI ドキュメントで REST サーバの仕様を定義したくて、OpenAPI 仕様を調べてみたのですが、肝心の入出力するデータの定義部分が「このオブジェクトは、JSON Schema Specification Draft 2020-12 のスーパーセットです。」みたいな感じだったので、別途、まとめることにしました。
以下の仕様を OAS3.1 と呼ぶことにします。
Schama
全てのインスタンスに対する keyword
type
OAS3.1 では
OAS のデータ型は、JSON Schema Specification Draft 2020-12 でサポートされている型に基づいています。型としてintegerもサポートされており、小数部または指数部のない JSON 数値として定義されていることに注意してください。
JSON Schema Validation 6.1.1 では
String values MUST be one of the six primitive types ("null", "boolean", "object", "array", "number", or "string"), or "integer" which matches any number with a zero fractional part.
ということで、type 属性には、上記の 7 つが指定できます。
format
OAS3.1 では、integer に int32 と int64 を、number に float と double を、string に password を定義していました。JSON Schema Validation 7.3 と合わせて、type との関連も整理すると、
| type | format | コメント | OAS3.1 |
|---|---|---|---|
| null | |||
| boolean | |||
| object | |||
| array | |||
| number | float | 〇 | |
| number | double | 〇 | |
| string | date-time | RFC3339 例：2018-11-13T20:20:39+00:00 | |
| string | date | RFC3339 例：2018-11-13 | |
| string | time | RFC3339 例：20:20:39+00:00 | |
| string | duration | RFC3339 例：P3D | |
| string | RFC5321 | ||
| string | idn-email | RFC6531 | |
| string | hostname | RFC1123 | |
| string | idn-hostname | RFC5890 | |
| string | ipv4 | RFC2673 | |
| string | ipv6 | RFC4291 | |
| string | uri | RFC3986 | |
| string | uri-reference | RFC3986 | |
| string | iri | RFC3987 | |
| string | iri-reference | RFC3987 | |
| string | uuid | RFC4122 例：3e4666bf-d5e5-4aa7-b8ce-cefe41c7568a | |
| string | uri-template | RFC6570 | |
| string | json-pointer | RFC6901 例：#/foo/bar/ | |
| string | relative-json-pointer | relative-json-pointer | |
| string | regex | ECMA-262 | |
| string | password | 〇 | |
| integer | int32 | 符号付き 32 bit 整数 | 〇 |
| integer | int64 | 符号付き 64 bit 整数 | 〇 |
enum と const
JSON Schema Validation 6.1 で定義されています。上記の null を含むどの型の値でも良く、const は、候補が単一の enum と同じです。enum または const で指定されたいずれかの値に一致しなければなりません。
適用可能なキーワード（applicator）
| keyword | コメント |
|---|---|
| oneOf | この keyword に属する schema のうち、1 つだけが満たされなければならない |
| allOf | この keyword に属する schema の全てが満たされなければならない |
| anyOf | この keyword に属する schema のうち、どれか 1 つ以上が満たされなければならない |
| if | この keyword に属する schema が満たされた場合、then が、そうでない場合、else が満たされなければならない |
| then | |
| else | |
| not | Schema を満たす、満たさないの否定（なので、逆になる） |
注釈（annotation）
| keyword | コメント |
|---|---|
| title | 名称 |
| description | 説明 |
| default | デフォルトの値 |
| deprecated | 非推奨の場合は true |
| examples | 使用方法を示すためのサンプル |
| readOnly | 書き換え不可の場合は true |
| writeOnly | 入力が存在せず、出力のみの場合は true |
数値（number と integer）
検証（validation）
JSON Schema Validation 6.2 で定義されています。
| keyword | コメント |
|---|---|
| multipleOf | 指定した 0 より大きい数値の倍数である |
| maximum | 指定した数値以下である |
| exclusiveMaximum | 指定した数値未満である |
| minimum | 指定した数値以上である |
| exclusiveMinimum | 指定した数値より大きい |
文字列（string）
検証（validation）
JSON Schema Validation 6.3 で定義されています。
| keyword | コメント |
|---|---|
| maxLength | 指定した 0 以上の整数以下の文字数である。文字数の定義は RFC8259 |
| minLength | 指定した 0 以上の整数以上の文字数である |
| pattern | 指定された正規表現にマッチする。指定できる正規表現は ECMA-262 |
配列（array）
JSON の array は、順序付きの要素の集合である。各要素の型は異なってもよい。
適用できるキーワード（applicator）
| keyword | コメント |
|---|---|
| prefixItems | 配列の各要素は、この keyword に属する schema の配列のうち対応する順序の schema を満たさねばならない |
| contains | 配列の各要素のうち 1 つ以上は、この keyword に属する schema を満たさねばならない |
| items | 配列の各要素は、この keyword に属する schema を満たさねばならない |
検証（validation）
JSON Schema Validation 6.4 で定義されています。
| keyword | コメント |
|---|---|
| maxItems | 指定した 0 以上の整数以下の要素数である |
| minItems | 指定した 0 以上の整数以上の要素数である |
| uniqueItems | true の場合は全ての要素が異なる。false の場合は常に正しい。デフォルトは false |
| maxContains | JSON Schema Core 10.3.1.3 で定義される contains されたものが、指定された 0 以上の整数以下の要素数である |
| minContains | contains されたものが、指定された 0 以上の整数以上の要素数である |
オブジェクト（object）
JSON の object は、文字列が key の map である。map される value の型は異なってもよい。
適用できるキーワード（applicator）
| keyword | コメント |
|---|---|
| properties | この keyword には object が指定され、その object の key は、この keyword が属する object のプロパティ名として扱われ、そのプロパティ名と合致するプロパティは value の shema を満たさねばならない |
| patternProperties | この keyword は、properties の key が正規表現文字列であり、key の正規表現を満たすプロパティ名を持つプロパティは、value の schama を満たさねばならない |
| additionalProperties | この値が false の場合、properties または patternProperties を満たすプロパティのみが許される。true の場合は、任意のプロパティが追加されてよい。デフォルトは true |
| dependentSchemas | この keyword には object が指定され、その object の key に合致するプロパティ名のプロパティが存在している場合、この keyword が属する object は、value の schama を満たさねばならない |
| propertyNames | 全てのプロパティ名が、指定された schema を満たさねばならない |
検証（validation）
JSON Schema Validation 6.5 で定義されています。
| keyword | コメント |
|---|---|
| maxProperties | 指定された 0 以上の整数以下のプロパティ数のオブジェクトである |
| minProperties | 指定された 0 以上の整数以上のプロパティ数のオブジェクトである |
| required | 指定された文字列の配列の全ての要素を名前とするプロパティを持つオブジェクトである |
| dependentRequired | 特定のプロパティが存在する場合に必要となるプロパティ名の配列が指定されるので、その組み合わせを満たすオブジェクトである |
Discussion