스키마 조합의 직접 자기 참조 점검

설명

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 속성 정의도 추가되므로 실제 오류 모델에 맞는지 확인하세요.