빠른 비교
| 목적 | keyword | 의미 |
|---|---|---|
| 모든 항목이 같은 규칙 | items | list validation |
| 앞쪽 항목마다 다른 규칙 | prefixItems | tuple validation |
| 남은 항목 제한 | items: false | tuple 길이 고정 |
| 최소·최대 길이 | minItems, maxItems | 항목 수 제약 |
| 중복 제거 | uniqueItems | 전체 값 중복 금지 |
{
"type": "array",
"prefixItems": [
{ "type": "number" },
{ "type": "number" },
{ "type": "string" }
],
"items": false
}배열 검증
items는 보통 같은 형태의 목록에 쓴다
items에 schema 하나를 두면 배열의 모든 항목이 같은 규칙을 따라야 합니다. 사용자 목록, 태그 목록, 좌표 목록처럼 항목 의미가 반복되는 데이터에 맞습니다.
{
"type": "array",
"items": { "type": "string" }
}이 schema는 모든 항목이 string인지 검사합니다. 첫 번째 항목과 두 번째 항목의 의미가 다르다면 items 하나만으로는 충분하지 않습니다.
prefixItems는 위치별 의미가 있는 배열에 쓴다
prefixItems는 배열 앞쪽 항목을 index별로 검증합니다. 예를 들어 [x, y, label]처럼 0번, 1번, 2번 항목의 의미가 다르면 tuple validation이 맞습니다.
{
"type": "array",
"prefixItems": [
{ "type": "number" },
{ "type": "number" },
{ "type": "string" }
]
}이 schema는 앞의 세 항목만 위치별로 검사합니다. 길이를 정확히 세 개로 제한하려면 items: false나 maxItems를 함께 써야 합니다.
draft에 따라 tuple 문법이 다르다
JSON Schema draft 2020-12에서는 위치별 배열 검증에 prefixItems를 씁니다. 예전 draft에서는 items에 schema 배열을 두고 additionalItems로 나머지를 제한하는 방식이 쓰였습니다. validator가 어떤 draft를 지원하는지 모르면 같은 schema가 다르게 해석될 수 있습니다.
선택 기준
| 데이터 형태 | 선택 |
|---|---|
| 태그 목록 | items |
| 주문 항목 목록 | items |
좌표 [x, y] | prefixItems + items: false |
RGB [r, g, b] | prefixItems 또는 items + 길이 제한 |
| 앞 몇 개만 고정, 뒤는 반복 | prefixItems + items |
| draft 호환성이 중요 | $schema 명시 |
주의할 점
tuple처럼 보이는 배열은 읽는 사람이 index 의미를 외워야 합니다. 공개 API에서는 { "x": 1, "y": 2 } 같은 object가 더 명확할 수 있습니다. 배열 tuple은 크기가 작고 의미가 널리 알려진 값에 제한하는 편이 안전합니다.
prefixItems를 쓰면서 길이를 제한하지 않으면 추가 항목이 들어와도 통과할 수 있습니다. 정확한 tuple 길이가 계약이라면 items: false나 maxItems를 함께 선언하세요.
참고 링크
1 sources