빠른 설정

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/schemas/user.schema.json",
  "type": "object",
  "properties": {
    "id": { "type": "string" }
  },
  "required": ["id"]
}

dialect 기준

$schema는 어떤 규칙으로 평가할지 선언한다

JSON Schema는 draft마다 keyword 의미와 지원 범위가 달라질 수 있습니다. $schema는 이 schema가 어떤 meta-schema, 즉 어떤 dialect를 기준으로 작성되었는지 validator와 사람에게 알려주는 선언입니다.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

$schema가 없으면 validator가 기본값을 가정할 수 있습니다. 이 경우 개발 환경과 CI, 서버 validator가 서로 다른 draft로 해석해 같은 schema가 다르게 동작할 수 있습니다.

draft 차이는 keyword 호환성 문제로 이어진다

JSON Schema에는 Draft 4, Draft 6, Draft 7, Draft 2019-09, Draft 2020-12처럼 여러 버전이 있습니다. 예를 들어 conditional keywords나 unevaluated 계열 keyword는 특정 draft 이후에 등장합니다. 오래된 validator에서 최신 keyword를 쓰면 무시되거나 오류가 날 수 있습니다.

schema 작성
  -> $schema 명시
  -> validator가 해당 draft 지원하는지 확인
  -> CI에서 같은 validator 버전 사용

schema 파일만 맞다고 끝나는 것이 아니라, 평가하는 도구까지 같은 dialect를 지원해야 합니다.

$id는 schema 식별과 참조 기준을 만든다

$schema가 평가 규칙을 가리킨다면, $id는 schema 자체의 식별자와 참조 기준을 만듭니다. 여러 schema를 $ref로 연결할 때는 $id가 안정적인 URI 역할을 합니다.

{
  "$id": "https://example.com/schemas/order.schema.json",
  "$defs": {
    "money": {
      "type": "object"
    }
  }
}

파일 경로만으로 참조가 돌아가게 만들면 배포 위치나 bundling 방식이 바뀔 때 깨질 수 있습니다. 공개 schema나 여러 서비스가 공유하는 schema에는 $id를 명확히 두는 편이 좋습니다.

custom vocabulary는 별도 dialect 설계다

JSON Schema는 custom keyword를 만들 수 있지만, 팀 내부에서만 해석되는 keyword를 일반 schema처럼 섞으면 다른 validator에서 의미가 사라질 수 있습니다. custom keyword가 필요하다면 해당 keyword를 이해하는 validator, meta-schema, 문서화가 함께 있어야 합니다.

체크포인트

주의할 점

특정 draft의 keyword를 썼다면 문서와 테스트에도 해당 draft를 남겨야 합니다. schema validation 실패보다 더 위험한 경우는 validator가 모르는 keyword를 조용히 무시해 검증이 느슨해지는 상황입니다.