JSON Schema, 한 페이지로

다른 JSON 문서의 모양을 묘사하는 JSON 문서

JSON Schema 자체가 JSON 이야. schema 문서를 하나 써두면 validator 가 그걸 데이터 문서에 대고 돌려서 '통과' 라고 하거나 어긴 목록을 돌려줘. 지금 쓰는 dialect 는 Draft 2020-12 야 (그냥 'JSON Schema' 라고 부르는 게 이거). Draft-07 이나 Draft-04 같은 옛 버전도 아직 여기저기 살아 있으니까, $schema URI 를 읽어서 어느 버전인지부터 확인해.

JSON Schema 가 주는 세 가지

검증 — 문서가 계약을 지키는지 확인해줘. API 경계, config 를 읽어들이는 자리, CI 에서 써.
IDE autocomplete — VS Code 가 schemastore.org 에서 schema 를 받아와서 package.json, tsconfig.json, .eslintrc.json, github-actions.yml 같은 파일에 autocomplete 와 설명을 띄워줘.
문서 — schema 가 곧 문서야. Redoc 같은 도구는 OpenAPI schema 를 돌아다닐 수 있는 사이트로 그려주고.

가장 작은 유용한 schema

'문자열 name 을 가진 아무 객체' 정도면 감을 잡기엔 충분해.

원칙: schema 는 안 그러면 코드 리뷰에서 사람이 눈으로 잡아야 할 규칙을 코드로 못 박아두는 자리야. 'name 은 필수, slug 는 이 regex 를 지킬 것, version 은 semver 를 따를 것' 같은 건 아무도 안 읽는 위키 페이지가 아니라 schema 에 있어야 해.

Code

가장 작은 유용한 schema·json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/user.schema.json",
  "title": "User",
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "age":  { "type": "integer", "minimum": 0 }
  },
  "required": ["name"]
}

Shell 에서 검증 (ajv-cli)·bash

# 한 번 설치
npm install -g ajv-cli

# schema 로 문서 검증
ajv validate -s user.schema.json -d data.json

# Strict mode + draft 2020-12
ajv validate --strict=true --spec=draft2020 -s user.schema.json -d data.json

Python 에서 검증 (jsonschema)·python

import json
from jsonschema import validate, ValidationError

schema = json.load(open('user.schema.json'))
data = json.load(open('data.json'))

try:
    validate(instance=data, schema=schema)
    print('valid')
except ValidationError as e:
    print(f'invalid: {e.message}')
    print(f'  at: {list(e.path)}')

Exercise

프로젝트 config 파일을 하나 골라 (tsconfig.json, package.json, .eslintrc 중 아무거나). 그 파일의 $schema URL 을 찾아봐. 널리 쓰이는 config 면 거의 다 있어. 브라우저로 열어서 JSON 으로 읽어보고. 평소 에디터가 해주던 autocomplete 중 얼마나 많은 부분이 사실은 JSON Schema 한 장이 하던 일이었는지 보게 될 거야.

다른 JSON 문서의 모양을 묘사하는 JSON 문서

JSON Schema 가 주는 세 가지

가장 작은 유용한 schema

Code

External links

Exercise

Progress

댓글 0