JSON Schema, 한 페이지로

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

JSON Schema 자체가 JSON 이야. schema 문서 작성하고 validator 가 데이터 문서에 적용하면 'valid' 또는 위반 리스트 반환. 현재 dialect 는 Draft 2020-12 (그냥 'JSON Schema'). 이전 draft (Draft-07, Draft-04) 도 여기저기 — $schema URI 읽어서 어느 버전인지 알아.

JSON Schema 가 주는 세 가지

Validation — 문서가 계약 따르는지 확인. API 경계, config load, CI 에서 사용.
IDE autocomplete — VS Code 가 schemastore.org 에서 schema 읽어서 package.json, tsconfig.json, .eslintrc.json, github-actions.yml 등에서 autocomplete + 인라인 docs.
문서 — schema 가 docs. Redoc 같은 도구가 OpenAPI schema 를 navigation 가능한 사이트로 렌더링.

가장 작은 유용한 schema

'문자열 name 가진 아무 객체' 면 감 잡기 충분.

원칙: schema 는 그렇지 않으면 코드 리뷰에서 강제할 invariant 인코딩하는 곳. '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 마다 있어. 브라우저에서 schema URL 열고 JSON 으로 읽어. 에디터의 autocomplete 동작 중 얼마나 많은 부분이 그냥 JSON Schema 가 일하는 거였는지 봐.

JSON Schema, 한 페이지로

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

JSON Schema 가 주는 세 가지

가장 작은 유용한 schema

Code

External links

Exercise

Progress

댓글 0