説明
allOf などの合成でスキーマが自分自身を直接参照すると、同じデータに対する処理が繰り返され、一部のツールで循環解決エラーや過剰な展開につながる場合があります。子プロパティーが親と同じ型を持つツリーなど、必要な再帰モデルがすべて不正なわけではありません。
想定される影響
文書ツールやコード生成ツールがモデルを処理できなかったり、検証に過剰な時間がかかったりする可能性があります。直接の再帰と意図した構造を区別できないと、データ仕様も理解しにくくなります。
対処方法
参照が同じスキーマとデータに戻るか確認してください。不要な直接参照は削除するか共通スキーマへ分離し、必要な再帰モデルは利用ツールが対応するか確認してください。変更後の制約が実際の仕様を維持することも確認してください。
例
OpenAPI 3.0 の合成スキーマの抜粋で、info と paths は省略しています。変更前の ExtendedErrorModel は allOf で自分自身を直接参照します。
変更前
json
{
"openapi": "3.0.0",
"components": {
"schemas": {
"ExtendedErrorModel": {
"allOf": [
{
"$ref": "#/components/schemas/ExtendedErrorModel"
},
{
"type": "object",
"properties": {
"rootCause": {
"type": "string"
}
}
}
]
}
}
}
}
変更後
json
{
"openapi": "3.0.0",
"components": {
"schemas": {
"ErrorModel": {
"type": "object",
"properties": {
"message": {
"type": "string"
}
}
},
"ExtendedErrorModel": {
"allOf": [
{
"$ref": "#/components/schemas/ErrorModel"
},
{
"type": "object",
"properties": {
"rootCause": {
"type": "string"
}
}
}
]
}
}
}
}
変更後は別の ErrorModel を参照し、直接の循環をなくしています。message の定義も追加しているため、実際のエラーモデルに合うか確認してください。