Skip to content

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

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) 정수 또는 실수인지를 검사하는 예제입니다. 

{
    "type": "number",
    "minimum": 1,
    "maximum": 10,
    "exclusiveMaximum": true
}

문자열 길이 검증

minLength와 maxLength 키워드를 사용하여 해당 문자열의 길이가 유효한지를 검사할 수 있습니다.

이때 minLength와 maxLength 키워드의 값은 0을 포함한 양수만을 사용할 수 있습니다.

다음 예제는 해당 문자열의 길이가 1보다 크고 4보다 작은지를 검사하는 예제입니다. 

{
    "type": "string",
    "minLength": 1,
    "maxLength": 4
}

문자열 정규식 검증 

{
    "type": "string",
    "pattern": "[a-z]+"
}

객체의 필수 프로퍼티 검증

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개만 가졌는지를 검사하는 예제입니다. 

{
    "type": "object",
    "minProperties": 1,
    "maxProperties": 2
}

배열 요소 검증

items 키워드를 사용하여 해당 배열에 저장된 배열 요소에 대한 검증을 수행할 수 있습니다.

다음 예제는 해당 데이터가 배열이면서, 각 배열 요소가 모두 정수인지를 검사하는 예제입니다. 

{
    "type": "array",
    "items": {
        "type": "integer"
    }
}

배열의 각각의 요소 순서대로 검증하는 예제: 

{
    "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개까지인가를 검사하는 예제입니다. 

{
    "type": "array",
    "minItems": 3,
    "maxItems": 10
}

배열 중복 값 검증

uniqueItems 키워드를 사용하여 해당 배열에 저장된 배열 요소에 대한 중복 값 허용 여부를 명시할 수 있습니다.

uniqueItems 값이 true이면, 배열 요소의 값에 중복 값을 허용하지 않을 수 있습니다.

다음 예제는 해당 데이터가 배열이면서, 가지고 있는 배열 요소의 값이 중복되지 않는가를 검사하는 예제입니다. 

{
    "type": "array",
    "uniqueItems": true
}

불리언 검증 

{
    "type": "boolean"
}

JSON은 불리언 true와 false 대신에 숫자 1과 0을 대신 사용할 수 없으므로, 위의 예제에서 숫자 1과 0은 통과할 수 없습니다.

null 검증

type 키워드의 값을 null로 명시하면, 해당 데이터가 null인지를 검사해 줍니다. 

{
    "type": "null"
}

열거형 데이터 검증

유효한 enum 값들은 배열을 사용하여 명시하며, 중복 값을 가질 수는 없습니다. 

{
    "type": "string",
    "enum": ["웰시코기", "포메라니안", "푸들"]
}

스키마 결합

JSON 스키마에서는 다음 키워드를 사용하여 여러 JSON 스키마를 결합할 수 있습니다.

allOf

배열에 나열된 스키마에 대한 검증을 모두 통과해야 합니다.

다음 예제는 해당 문자열 데이터의 길이가 3 이상이고 5 이하인지를 검사하는 예제입니다. 

{
    "allOf": [
        {"minLength": 3},
        {"maxLength": 5}
    ]
}

anyOf

배열에 나열된 하나 이상의 스키마에 대한 검증을 통과해야 합니다.

다음 예제는 해당 데이터가 문자열이나 숫자인지를 검사하는 예제입니다. 

{
    "anyOf": [
        {"type": "string"},
        {"type": "number"}
    ]
}

oneOf

배열에 나열된 오직 하나의 스키마에 대한 검증만을 통과해야 합니다.

다음 예제는 해당 데이터가 숫자이면서 3의 배수이거나, 아니면 숫자이면서 4의 배수인지를 검사하는 예제입니다. 

{
    "oneOf": [
        { "type": "number", "multipleOf": 3 },
        { "type": "number", "multipleOf": 4 }
    ]
}

두 스키마 중 오직 하나의 검증만을 통과하는 데이터만이 검증을 통과할 것입니다.

  • 3, 6, 9와 같은 3의 배수는 통과
  • 4, 8, 16과 같은 4의 배수는 통과
  • 하지만 12, 24, 36과 같은 3과 4의 공배수는 검증을 통과할 수 없습니다.

not

다음 예제는 해당 데이터가 문자가 아닌지를 검사하는 예제입니다. 

{
    "not": {
        "type": "string"
    }
}

Metadata

스키마에 대한 정보를 나타내는 메타 데이터(metadata) 키워드는 다음과 같습니다.

  • title
  • description
  • default

See also

Favorite site