필수 속성의 타입 정의 점검

설명

객체 스키마의 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가 요구하는 값의 형식을 명시하는 예시입니다.