설명
객체 스키마의 required는 반드시 존재해야 할 속성 이름을 지정하고, properties는 각 속성의 형식과 제약을 정의합니다. 필수 속성이 같은 properties에 없다는 사실만으로 명세가 모순되지는 않습니다. 추가 속성이 허용되거나 allOf 등 다른 스키마에 정의가 있을 수 있습니다.
잠재적 영향
필수 필드의 형식이 어디에도 정의되지 않으면 문서 소비자가 필요한 값을 알기 어렵고 타입 검증이 부족할 수 있습니다. 반대로 추가 속성을 금지하면서 필수 이름도 허용하지 않으면 어떤 객체도 조건을 만족하지 못할 수 있습니다.
해결 방법
조합된 스키마와 additionalProperties까지 확인하고, 필요한 필수 속성의 타입과 제약을 적절한 위치에 정의하세요. 실제 필수 조건은 유지하고, 같은 properties에 없다는 이유만으로 required에서 제거하지 마세요.
예시
OpenAPI 3.0 객체 스키마 발췌입니다. info와 paths는 생략했습니다. 변경 전에도 name의 존재는 필수이며, 추가 속성을 금지하지 않았으므로 이 구조 자체가 모순은 아닙니다.
변경 전
json
{
"openapi": "3.0.0",
"components": {
"schemas": {
"Example": {
"type": "object",
"required": [
"name"
],
"properties": {
"age": {
"type": "integer"
}
}
}
}
}
}
변경 후
json
{
"openapi": "3.0.0",
"components": {
"schemas": {
"Example": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
},
"age": {
"type": "integer"
}
}
}
}
}
}
변경 후에는 name의 타입을 문자열로 지정합니다. 존재 조건에 형식 제약을 추가한 것이며, 기존의 유효한 다른 타입 값도 거부할 수 있으므로 실제 계약에 맞게 선택하세요.