JSON Schema(JSON 스키마)

JSON Schema는 유효한 JSON 문서가 어떤 모습이어야 하는지를 기술하는 표준 방식입니다. 어떤 속성이 있는지, 각 속성의 타입, 필수 여부, 허용되는 값과 형식을 정의합니다. 그러면 검증기(validator)가 실제 데이터를 스키마와 비교해 모든 위반 사항을 보고합니다. API 테스터에게는 “응답이 맞아 보인다”를 응답 전체 형태에 대한 하나의 반복 가능한 검사로 바꿔 줍니다. 현재 명세 버전은 draft 2020-12이며, draft-07도 여전히 매우 널리 쓰입니다.

예시

GET /users/{id}가 반환하는 사용자에 대한 스키마:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["id", "email", "role", "createdAt"],
  "properties": {
    "id": { "type": "integer", "minimum": 1 },
    "email": { "type": "string", "format": "email" },
    "role": { "enum": ["admin", "member", "viewer"] },
    "createdAt": { "type": "string", "format": "date-time" },
    "nickname": { "type": ["string", "null"] }
  },
  "additionalProperties": false
}

Node에서 Ajv로 검증하기(ajv/dist/2020은 draft 2020-12를 지원하고, ajv-formats는 email과 date-time을 추가합니다):

import Ajv2020 from 'ajv/dist/2020';
import addFormats from 'ajv-formats';

const ajv = new Ajv2020({ allErrors: true });
addFormats(ajv);
const validate = ajv.compile(userSchema);

if (!validate(responseBody)) {
  console.log(validate.errors);
}

Java에서는 REST Assured의 json-schema-validator 모듈이 .body(...) 안에서 쓸 수 있는 matchesJsonSchemaInClasspath("schemas/user.json")를 제공합니다. 새로운 키워드를 쓰기 전에 검증기가 어떤 draft를 지원하는지 확인하세요.

왜 중요한가

• 어설션 하나로 전체 형태를 커버합니다. 필드마다 검사를 작성하지 않아도 누락된 필드, 잘못된 타입, 예상치 못한 null을 잡아냅니다.
• 정보 유출을 잡아냅니다. "additionalProperties": false는 응답에 갑자기 passwordHash 같은 것이 포함되면 실패합니다.
• 계약을 문서화합니다. OpenAPI 명세는 요청과 응답 본문을 기술할 때 JSON Schema를 사용합니다.

흔한 실수

• 무엇이든 허용하는 스키마. required가 없는 스키마는 {}도 통과시킵니다. 필수 필드는 항상 나열하세요.
• format이 강제된다고 가정하기. 많은 검증기는 형식 검증을 켜지 않으면 format을 단순 주석으로 취급합니다.
• 스키마만 검증하기. 응답이 스키마와 일치해도 엉뚱한 사용자가 담겨 있을 수 있습니다. 중요한 데이터에 대해서는 값 어설션을 유지하세요.