핵심 정리
{
"type": "object",
"properties": {
"name": { "type": "string" },
"age": { "type": "number" }
},
"required": ["name"]
}문법
schema는 규칙이고 instance는 데이터다 — JSON 파싱 성공과 schema 검증 통과는 다른 차원이다
JSON Schema는 JSON 데이터(instance)가 어떤 모양과 제약을 따라야 하는지 기술하는 별도의 JSON 문서입니다. JSON이 문법적으로 유효하다는 것(파싱 성공)과 특정 schema를 통과한다는 것은 다른 차원의 검증입니다. {"name": 42}는 유효한 JSON이지만, name이 string이어야 한다는 schema에서는 검증 실패입니다. 이 구분이 중요한 이유는 API나 설정 파일에서 "문법은 맞지만 의미가 잘못된" 데이터를 사전에 잡아내는 것이 JSON Schema의 역할이기 때문입니다.
type keyword는 기대하는 값 종류를 선언한다 — 선언하지 않으면 어떤 타입도 통과된다
JSON Schema에서 type은 가장 기본적인 제약입니다. "type": "string", "type": "number", "type": "object", "type": "array", "type": "boolean", "type": "null" 중 하나 또는 배열로 지정합니다. type을 선언하지 않으면 해당 위치에 어떤 타입의 값도 허용됩니다. null 허용이 필요하면 "type": ["string", "null"]처럼 배열로 명시해야 합니다. type만 선언해도 기본 타입 안전성을 확보하는 데 충분히 가치 있습니다.
{
"type": "object",
"properties": {
"score": { "type": ["number", "null"] }
}
}properties는 허용 필드를 설명할 뿐 필수를 의미하지 않는다 — 필수 여부는 required로 따로 선언해야 한다
JSON Schema에서 properties에 필드를 선언하는 것은 해당 필드의 규칙을 정의하는 것이지, 그 필드가 반드시 존재해야 한다는 의미가 아닙니다. 필수 여부는 required 배열로 별도 선언합니다. properties에 없는 필드가 instance에 있어도 기본적으로는 허용됩니다. 이 동작을 막으려면 additionalProperties: false를 선언해야 합니다. 이 세 가지(properties, required, additionalProperties)는 서로 다른 관심사를 각각 담당합니다.
즉 "필드 모양 설명", "필수 여부", "알 수 없는 필드 허용 여부"는 서로 다른 스위치입니다. 하나만 켜 두고 나머지도 자동으로 따라올 것이라 기대하면 검증이 느슨해집니다.
JSON Schema는 문서화 도구이기도 하다 — "이 필드가 있는지"만 확인하는 도구로 과소평가하면 안 된다
JSON Schema는 값의 종류, 허용 범위, 필수 필드, 추가 필드 차단, 배열 항목 구조, 문자열 포맷("format": "email") 등을 선언적으로 기술합니다. 검증 실행 외에도 IDE 자동완성, API 문서 생성, mock 데이터 자동 생성 도구가 schema를 소비합니다. "이 필드가 있는지"만 확인하는 단순 검증 도구로 쓰기보다, 값 타입과 범위, 배열 항목 규칙, 추가 필드 정책까지 함께 선언해야 실제로 쓸 만한 schema가 됩니다.
JSON 파싱만으로 알 수 있는 것
- 문법이 올바른가
JSON Schema로 추가로 검증하는 것
- 이 필드가 반드시 있어야 하는가 (required)
- 값 타입이 맞는가 (type)
- 선언되지 않은 필드를 허용하는가 (additionalProperties)
- 배열 항목이 일정한 구조를 따르는가 (items){
"type": "object",
"properties": {
"name": { "type": "string" },
"age": { "type": "number" }
},
"required": ["name"]
}체크포인트
| 상황 | 적합한 선택 |
|---|---|
| 문법 유효성 확인 | JSON 파서 (JSON.parse()) |
| 구조·타입 제약 검증 | JSON Schema (type, properties) |
| 필수 필드 보장 | required 배열 선언 |
| 알 수 없는 필드 차단 | additionalProperties: false |
| null 허용 필드 선언 | type 배열에 "null" 명시 |
주의할 점
properties만 선언하고 "왜 필수 검사가 안 되지?"라고 느끼는 경우가 많습니다. 필수 여부는
required, null 허용은 type 배열, 추가 필드 차단은 additionalProperties로 각각
선언해야 합니다. 이 세 가지는 서로 다른 관심사를 독립적으로 제어하므로 함께 선언해야
실질적인 검증 효과가 납니다.
{
"properties": {
"name": { "type": "string" }
}
}이 schema는 name 필드 규칙을 설명할 뿐, name이 반드시 있어야 한다고 말하지는 않습니다. required를 빼먹으면 "생각보다 많이 통과하는" schema가 됩니다.
파싱 성공과 schema 통과를 같은 의미로 보면 여기서 문제가 생깁니다. JSON parser는 문법만 보고, schema validator는 계약까지 봅니다.
참고 링크
3 sources