접착제로서의 schema — 포맷 가로지르는 JSON Schema · Markup Quest

한 schema, 세 포맷

YAML 도 TOML 도 JSON 도 결국 같은 데이터 모델로 파싱돼. 그래서 JSON Schema 하나로 셋을 다 검증할 수 있어. 고칠 것도 없이 그대로. schema 를 한 번 써두면 validator 를 셋 중 어디에 겨눠도 같은 규칙이 똑같이 적용돼.

포맷 가로지르는 validator

check-jsonschema — Python 도구야. pip install check-jsonschema 로 깔고, JSON Schema 로 JSON 과 YAML, TOML 을 다 검증해.
ajv-cli + YAML loader — JSON 쪽에서 제일 빠른 validator 야. YAML 을 먹이려면 --data-stream 에 js-yaml 을 얹어.
spectral — OpenAPI 전용이야. YAML 이든 JSON 이든 spec 파일에 JSON Schema 규칙을 돌려줘.
에디터 schema 연동 — VS Code 의 YAML / JSON / TOML 확장이 전부 Schema Store 에서 schema 를 받아와서 autocomplete 와 실시간 검증을 붙여줘. 포맷은 안 가려.

규율로서의 schema-first

포맷은 팀이 편한 걸로 고르되, schema 만은 JSON Schema 로 써. 그 schema 가 진짜 기준점이 되고, 포맷은 필요할 때 변환하면 돼. 그리고 그 schema 하나에서 문서도, autocomplete 도, 타입도, 가짜 데이터 생성기도 뽑아낼 수 있어. 어디까지 뽑을지는 취향이고.

원칙: 경계에서 검증하고 안쪽에서는 믿어. 경계란 타입 없는 데이터가 시스템 안으로 들어오는 자리야. config 를 읽는 순간, API 요청을 받는 순간, 파일 업로드를 받는 순간. 거기서 JSON Schema 로 걸러내면, 그 뒤의 코드는 모양이 맞다고 마음 놓고 가정할 수 있어.

Code

한 schema, 다 검증·bash

# 설치
pip install check-jsonschema

# JSON 검증
check-jsonschema --schemafile config.schema.json config.json

# 같은 schema, YAML 검증
check-jsonschema --schemafile config.schema.json config.yaml

# 같은 schema, TOML 검증
check-jsonschema --schemafile config.schema.json config.toml

# URL 의 schema 로 검증 (Schema Store)
check-jsonschema --schemafile https://json.schemastore.org/github-action.json action.yaml

Schema 예시 — 다 같은 규칙 적용·json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "port":     { "type": "integer", "minimum": 1024, "maximum": 65535 },
    "host":     { "type": "string" },
    "log_level": { "enum": ["debug", "info", "warn", "error"] },
    "database": {
      "type": "object",
      "properties": {
        "url":       { "type": "string", "format": "uri" },
        "pool_size": { "type": "integer", "minimum": 1, "maximum": 100 }
      },
      "required": ["url"]
    }
  },
  "required": ["host", "port", "database"]
}

VS Code — 파일명으로 자동 적용 schema·json

// .vscode/settings.json
{
  "json.schemas": [
    { "fileMatch": ["my-config.json"], "url": "./config.schema.json" }
  ],
  "yaml.schemas": {
    "./config.schema.json": ["my-config.yaml", "my-config.yml"]
  }
  // TOML 은 Even Better TOML 확장 사용; 자체 설정으로 구성.
}

Exercise

관리 중인 config 를 설명하는 JSON Schema 를 하나 써. 그 schema 하나로 YAML 버전도, TOML 버전이 있으면 그것도, 그리고 일부러 깨뜨린 JSON 버전도 검증해봐. 그 검증 단계를 CI 에 넣고. 그러면 그 schema 가 사람과 포맷과 validator 셋 다 동의하는 계약이 돼.

접착제로서의 schema — 포맷 가로지르는 JSON Schema

한 schema, 세 포맷

포맷 가로지르는 validator

규율로서의 schema-first

Code

External links

Exercise

Progress

댓글 0