JSON Schema required와 additionalProperties를 함께 쓰는 방법
required에는 반드시 존재해야 할 속성 이름을 배열로 적고, properties에는 각 속성의 타입과 제약을 정의한 뒤, 선언하지 않은 키까지 막으려면 같은 객체 스키마에 additionalProperties: false를 둡니다. 중첩 객체는 각 단계에서 별도로 설정하고 조합 스키마는 unevaluatedProperties 사용 여부를 검토하세요.
필수 키를 선언하는 것과 허용 키 목록을 닫는 것은 서로 다른 검증입니다. 두 키워드를 역할대로 나누면 오타 난 필드가 조용히 통과하거나 정상적인 확장 필드가 갑자기 거부되는 문제를 줄일 수 있습니다.
먼저 보는 핵심 요약
- required는 객체에 속성이 존재하는지만 요구하며 값의 타입이나 빈 문자열 여부는 별도 스키마가 검사합니다.
- additionalProperties는 properties와 patternProperties가 다루지 않은 추가 속성의 허용 여부 또는 스키마를 정합니다.
- allOf 같은 조합과 중첩 객체에서는 평가 범위를 확인하고 사용 중인 JSON Schema draft를 명시해야 합니다.
required가 검사하는 범위
required의 값은 필수 속성 이름으로 이루어진 배열입니다. 해당 키가 존재하면 required 조건은 충족되지만 값이 문자열인지, null인지, 비어 있는지는 properties 아래의 타입과 길이 제약이 결정합니다. 선택 속성도 properties에 정의할 수 있으며 required 배열에 없으면 존재 자체만 선택 사항이 됩니다.
additionalProperties false가 막는 대상
객체에서 properties나 patternProperties로 평가되지 않은 이름의 속성을 거부합니다. required에 적지 않았다는 이유만으로 알려진 선택 속성을 막는 것은 아닙니다. 반대로 required와 properties만 선언하고 추가 속성 정책을 두지 않으면 스키마에 없는 키가 허용될 수 있습니다.
중첩 객체마다 정책을 다시 선언하는 이유
바깥 객체의 additionalProperties 설정은 안쪽 객체의 속성까지 자동으로 닫지 않습니다. profile 같은 중첩 값이 object라면 그 스키마 안에 properties, required, additionalProperties를 별도로 설계합니다. 외부 API처럼 확장 가능성이 필요한 구간은 false 대신 추가 값의 타입 스키마를 둘 수도 있습니다.
allOf 조합에서 예상치 못한 거부를 피하는 법
additionalProperties는 같은 스키마 객체에서 인식한 속성을 기준으로 동작하므로 다른 subschema에서 선언된 속성과 조합할 때 결과가 예상과 달라질 수 있습니다. 2020-12 draft의 unevaluatedProperties는 적용 가능한 subschema가 평가한 속성을 고려하도록 설계됐습니다. 사용하는 검증기의 draft 지원을 먼저 확인하세요.
단계별로 확인하는 방법
- 객체와 draft 선언하기
최상위 type을 object로 정하고 `$schema`에 검증기와 맞는 JSON Schema draft URI를 명시합니다.
- 속성 규칙 작성하기
properties에 허용할 키와 타입·형식·길이 등 값 제약을 정의합니다.
- 필수 키와 추가 키 정책 정하기
반드시 존재할 이름은 required에 넣고 알 수 없는 키를 막을 객체에 additionalProperties 정책을 둡니다.
- 성공·실패 사례 검증하기
정상 값, 필수 키 누락, 오타 키, null, 중첩 추가 키를 각각 넣어 검증 결과와 오류 경로를 확인합니다.
판단 기준을 한눈에 비교하기
| 확인 항목 | 판단 기준 |
|---|---|
| properties | 알려진 속성 이름별로 값에 적용할 스키마를 정의합니다. |
| required | 객체에 반드시 존재해야 하는 속성 이름을 배열로 지정합니다. |
| additionalProperties | 아직 평가되지 않은 추가 이름의 허용 여부나 값 스키마를 정합니다. |
| unevaluatedProperties | 조합된 subschema의 평가 결과까지 고려해 남은 속성을 제어할 때 검토합니다. |
실행 전 체크리스트
- 사용할 JSON Schema draft를 명시했나요?
- required 이름이 properties의 의도와 맞나요?
- 중첩 객체마다 추가 속성 정책을 따로 정했나요?
- 오타 키와 조합 스키마 사례를 실패 테스트에 넣었나요?
주의할 점
additionalProperties: false를 API 응답에 무조건 적용하면 제공자가 새 필드를 추가했을 때 기존 클라이언트가 갑자기 실패할 수 있습니다. 입력 계약을 닫아야 하는 구간과 앞으로 확장할 구간을 나누고, 스키마 draft와 검증기 동작을 함께 고정하세요.
함께 보면 좋은 글
자주 묻는 질문
required에 적으면 null도 거부되나요?
아닙니다. required는 키 존재를 검사합니다. null을 거부하려면 해당 properties 스키마의 type 등 값 제약에서 허용하지 않아야 합니다.
properties에 있으면 그 키는 자동으로 필수인가요?
아닙니다. properties는 값 규칙을 정의하며 존재를 강제하려면 이름을 required 배열에도 넣어야 합니다.
additionalProperties를 생략하면 추가 키가 거부되나요?
기본적으로 추가 속성을 허용할 수 있습니다. 닫힌 객체 계약이 필요하면 명시적인 정책과 검증 사례를 준비하세요.
모든 allOf 조합에 unevaluatedProperties를 써야 하나요?
항상 필요한 것은 아닙니다. 속성이 여러 subschema에 나뉘고 남은 키를 닫아야 할 때 유용하며 검증기의 2020-12 지원 여부를 확인해야 합니다.
근거와 출처
- JSON Schema 2020-12 Core 명세 — 1차 출처, 조회일 2026-08-30
- JSON Schema 2020-12 Validation 명세 — 1차 출처, 조회일 2026-08-30
도구에서 직접 확인하기
설명한 기준을 실제 값에 적용하려면 JSON Schema 검증기에서 작은 샘플부터 확인하세요. 원본과 결과를 나란히 비교한 뒤 실제 사용 환경에 적용하는 순서가 가장 안전합니다.
이 글은 알파카랩스 Utils의 개발 도구 도구와 함께 보는 정보성 가이드입니다. 규격과 외부 서비스 정책은 바뀔 수 있으므로 중요한 결정 전에는 연결된 공식 출처의 최신 내용을 다시 확인하세요.