JSON Schema
JSON Schema is a vocabulary that allows you to annotate and validate JSON documents.
Benefits
- Describes your existing data format(s).
- Provides clear human- and machine- readable documentation.
- Validates data which is useful for:
- Automated testing.
- Ensuring quality of client submitted data.
Categories
- JSON Schema Store - 다양한 형식에 대한 JSON 스키마 저장소 (현재 716개)
Implementations
- Jsonschema - python library
Validation
JSON 스키마에서 사용할 수 있는 대표적인 검증 키워드는 다음과 같습니다:
-
type
- 유효한 데이터의 타입을 명시함. -
properties
- 유효한 데이터 이름과 값의 쌍들을 명시함. -
required
- 명시한 배열의 모든 요소를 프로퍼티로 가지고 있어야만 유효함. -
minimum
- 최솟값 이상의 숫자만 유효함. -
maximum
- 최댓값 이하의 숫자만 유효함. -
multipleOf
- 명시한 숫자의 배수만 유효함. -
maxLength
- 명시한 최대 길이 이하의 문자열만 유효함. -
minLength
- 명시한 최소 길이 이상의 문자열만 유효함. -
pattern
- 명시한 정규 표현식에 해당하는 문자열만 유효함.
수치형 범위 검증
다음과 같은 키워드를 사용하면 해당 숫자의 유효한 범위를 명시할 수 있습니다.
-
minimum
- 숫자가 가질 수 있는 최솟값 -
maximum
- 숫자가 가질 수 있는 최댓값 -
exclusiveMinimum
-true
이면, 해당 숫자가 가질 수 있는 최솟값으로minimum
키워드로 명시된 값을 포함하지 않고 검사합니다. -
exclusiveMaximum
-exclusiveMinimum
의maximum
버전.
다음 예제는 해당 데이터가 1보다 크거나 같고(n>=1) 10보다는 작은(n<10) 정수 또는 실수인지를 검사하는 예제입니다.
문자열 길이 검증
minLength
와 maxLength
키워드를 사용하여 해당 문자열의 길이가 유효한지를 검사할 수 있습니다.
이때 minLength
와 maxLength
키워드의 값은 0을 포함한 양수만을 사용할 수 있습니다.
다음 예제는 해당 문자열의 길이가 1보다 크고 4보다 작은지를 검사하는 예제입니다.
문자열 정규식 검증
객체의 필수 프로퍼티 검증
required
키워드를 사용하여 해당 객체가 반드시 가지고 있어야 하는 필수 프로퍼티를 명시할 수 있습니다.
만약 필수 프로퍼티가 하나 이상이라면, 배열을 이용하여 각 필수 프로퍼티의 이름을 나열하면 됩니다.
다음 예제는 해당 데이터가 객체이면서, 프로퍼티로 name과 family를 가졌는지를 검사하는 예제입니다.
{
"type": "object",
"properties": {
"name": {"type": "string"},
"family": {"type": "string"},
"age": {"type": "integer"},
"weight": {"type": "number"}
},
"required": ["name", "family"]
}
객체의 프로퍼티의 개수 검증
minProperties
와 maxProperties
키워드를 사용하여 해당 객체가 가질 수 있는 프로퍼티 개수의 최솟값과 최댓값을 명시할 수 있습니다.
다음 예제는 해당 데이터가 객체이면서, 프로퍼티를 1개나 2개만 가졌는지를 검사하는 예제입니다.
배열 요소 검증
items
키워드를 사용하여 해당 배열에 저장된 배열 요소에 대한 검증을 수행할 수 있습니다.
다음 예제는 해당 데이터가 배열이면서, 각 배열 요소가 모두 정수인지를 검사하는 예제입니다.
배열의 각각의 요소 순서대로 검증하는 예제:
{
"type": "array",
"items": [
{
"type": "string",
"maxLength": 5
},
{
"type": "string"
},
{
"type": "string"
}
]
}
위의 경우 세 개의 유효한 배열 요소 외에 추가로 다른 배열 요소를 가지고 있는 배열도 검증을 통과할 것입니다.
additionalItems
키워드의 값을 false
로 명시하면, 추가로 다른 배열 요소를 가지는 배열은 검증을 통과하지 못하게 됩니다.
{
"type": "array",
"items": [
{
"type": "string",
"maxLength": 5
},
{
"type": "string"
},
{
"type": "string"
}
],
"additionalItems": false
}
배열 길이 검증
minItems
와 maxItems
키워드를 사용하여 해당 배열이 가질 수 있는 길이의 최솟값과 최댓값을 명시할 수 있습니다.
다음 예제는 해당 데이터가 배열이면서, 가지고 있는 배열 요소가 3개부터 10개까지인가를 검사하는 예제입니다.
배열 중복 값 검증
uniqueItems
키워드를 사용하여 해당 배열에 저장된 배열 요소에 대한 중복 값 허용 여부를 명시할 수 있습니다.
uniqueItems
값이 true이면, 배열 요소의 값에 중복 값을 허용하지 않을 수 있습니다.
다음 예제는 해당 데이터가 배열이면서, 가지고 있는 배열 요소의 값이 중복되지 않는가를 검사하는 예제입니다.
불리언 검증
JSON은 불리언 true
와 false
대신에 숫자 1과 0을 대신 사용할 수 없으므로, 위의 예제에서 숫자 1과 0은 통과할 수 없습니다.
null 검증
type 키워드의 값을 null로 명시하면, 해당 데이터가 null인지를 검사해 줍니다.
열거형 데이터 검증
유효한 enum 값들은 배열을 사용하여 명시하며, 중복 값을 가질 수는 없습니다.
스키마 결합
JSON 스키마에서는 다음 키워드를 사용하여 여러 JSON 스키마를 결합할 수 있습니다.
allOf
배열에 나열된 스키마에 대한 검증을 모두 통과해야 합니다.
다음 예제는 해당 문자열 데이터의 길이가 3 이상이고 5 이하인지를 검사하는 예제입니다.
anyOf
배열에 나열된 하나 이상의 스키마에 대한 검증을 통과해야 합니다.
다음 예제는 해당 데이터가 문자열이나 숫자인지를 검사하는 예제입니다.
oneOf
배열에 나열된 오직 하나의 스키마에 대한 검증만을 통과해야 합니다.
다음 예제는 해당 데이터가 숫자이면서 3의 배수이거나, 아니면 숫자이면서 4의 배수인지를 검사하는 예제입니다.
두 스키마 중 오직 하나의 검증만을 통과하는 데이터만이 검증을 통과할 것입니다.
- 3, 6, 9와 같은 3의 배수는 통과
- 4, 8, 16과 같은 4의 배수는 통과
- 하지만 12, 24, 36과 같은 3과 4의 공배수는 검증을 통과할 수 없습니다.
not
다음 예제는 해당 데이터가 문자가 아닌지를 검사하는 예제입니다.
Metadata
스키마에 대한 정보를 나타내는 메타 데이터(metadata) 키워드는 다음과 같습니다.
-
title
-
description
-
default