説明
オブジェクトスキーマの required はプロパティーの存在を要求し、properties はその値を制約します。同じ properties に必須名がなくても、追加プロパティーが許可されていたり、合成スキーマに定義があったりすれば有効な場合があります。存在条件と型定義は別のものです。
想定される影響
必須値の形式がどこにも定義されていないと、利用者が送る値を判断しにくく、型の検証も不十分になる場合があります。追加プロパティーの制限で必須名を禁止すると、制約が矛盾することがあります。
対処方法
参照・合成されたスキーマと additionalProperties を確認し、必要な値の型と説明を定義してください。実際に必須のプロパティーは required に維持し、ローカルな定義がないだけで任意に変えないでください。
例
OpenAPI 3.0 のオブジェクトスキーマの抜粋で、info と paths は省略しています。変更前も code と message は必須です。追加プロパティーを禁止していないため、message のローカルな定義がないだけで不正なスキーマになるわけではありません。
変更前
json
{
"openapi": "3.0.0",
"components": {
"schemas": {
"GeneralError": {
"type": "object",
"properties": {
"code": {
"type": "integer"
}
},
"required": [
"code",
"message"
]
}
}
}
}
変更後
json
{
"openapi": "3.0.0",
"components": {
"schemas": {
"GeneralError": {
"type": "object",
"properties": {
"code": {
"type": "integer"
},
"message": {
"type": "string"
}
},
"required": [
"code",
"message"
]
}
}
}
}
変更後は message に文字列型を追加します。存在条件を維持し、実際の API が要求する値の形式を明示する例です。