説明
オブジェクトスキーマの required は、そのプロパティーの存在が必須であることを意味します。同じプロパティーに default を指定すること自体は禁止されていませんが、宣言だけで欠落した必須値が補われたり、検証に通ったりするわけではありません。値の適用はクライアント、サーバー、ツールの動作に依存します。
想定される影響
利用者がデフォルト値を見て必須値を省略したり、クライアントとサーバーが異なる段階で値を適用したりすると、検証の失敗や予期しないデータ処理につながる可能性があります。
対処方法
必須条件を実際の仕様に合わせ、どの処理がいつデフォルト値を適用するか記載してください。誤解を招く値は削除しつつ、有効なデフォルト値を一律に禁止しないでください。値がない場合のサーバーとクライアントの動作を確認してください。
例
OpenAPI 3.0 のオブジェクトスキーマの抜粋です。info と paths は省略しています。変更前も id はデフォルト値にかかわらず必須であり、両キーワードの組み合わせ自体は不正ではありません。
変更前
json
{
"openapi": "3.0.0",
"components": {
"schemas": {
"MyObject": {
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"default": "4056684e4e1347579362617ad82e5b4e"
}
}
}
}
}
}
変更後
json
{
"openapi": "3.0.0",
"components": {
"schemas": {
"MyObject": {
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string",
"default": "guest"
}
}
}
}
}
}
変更後は id のデフォルト値を削除し、任意の name に guest を指定しています。これは別の仕様上の選択であり、宣言だけで name が自動入力されるわけではありません。