JSON Schema로 코딩의 품질을 높이는 방법

JSON은 데이터를 저장하고 전달하는 데 있어 가장 널리 쓰이는 형식이지만, 자유도가 너무 높다는 단점이 있다. 필드 이름을 잘못 적거나, 숫자여야 할 곳에 문자열을 넣는 실수는 비일비재하다. 이러한 휴먼 에러를 사전에 방지하고 데이터의 일관성을 유지하고 싶다면 JSON Schema를 도입해야 한다.

단순히 데이터 구조를 정의하는 것에 그치지 않고, VS Code와 같은 에디터와 결합했을 때 얻을 수 있는 강력한 이점들을 살펴보자.

 

 

JSON Schema를 사용하면 무엇이 좋아질까?

JSON Schema는 JSON 데이터의 구조를 정의하는 일종의 `설계도`다. 이 설계도를 작성하면 다음과 같은 이점을 얻는다.

  1. 자동 완성 및 툴팁 제공: 에디터에서 JSON을 편집할 때 사용 가능한 속성을 미리 보여주고, 각 속성이 무엇을 의미하는지 한글 툴팁으로 안내한다.
  2. 실시간 유효성 검사: 잘못된 데이터 타입을 입력하거나 필수 항목을 누락하면 에디터가 즉시 빨간 줄로 경고를 보낸다.
  3. 데이터 표준화: 프로젝트 팀원 모두가 동일한 데이터 구조를 따르도록 강제하여 협업 효율을 높인다.

VS Code에서 JSON Schema 툴팁과 자동 완성이 활성화된 모습
VS Code에서 JSON Schema 툴팁과 자동 완성이 활성화된 모습

 

핵심 키워드 이해

JSON Schema는 특정 데이터가 어떤 형태를 가져야 하는지 정의하는 약속이다. 가장 자주 사용되는 속성은 다음과 같다.

type (데이터 타입)

`type` 은 해당 데이터가 어떤 자료형이어야 하는지 명시한다.

  • 역할: 입력되는 값이 문자열인지, 숫자인지, 혹은 배열인지 검사한다.
  • 주요 값:
    • `string` : 텍스트 데이터 (예: 곡 제목, 아티스트)
    • `number` / `integer` : 숫자 또는 정수 데이터 (예: 가격)
    • `object` : 중괄호 `{}`로 둘러싸인 객체 데이터 (예: 앨범 정보 전체)
    • `array` : 대괄호 `[]` 로 이루어진 리스트 데이터 (예: 트랙 리스트)
    • `boolean` : `true` 또는 `false`

properties (속성)

`properties`는 객체(`object`) 안에 어떤 키(Key)들이 들어갈 수 있는지 정의하는 사전과 같은 역할을 한다.

  • 역할: 객체의 각 필드 이름을 정의하고, 해당 필드에 대한 추가적인 제약 조건을 연결한다.
  • 활용: 예를 들어 앨범 객체 내부에 `genre`, `price`라는 키가 존재해야 함을 이 키워드를 통해 선언한다.

description (설명)

`description`은 데이터 자체의 로직에는 영향을 주지 않지만, 개발자 경험 측면에서 매우 중요하다.

  • 역할: 해당 필드가 무엇을 의미하는지 사람이 읽을 수 있는 문장으로 설명한다.
  • 에디터 연동: VS Code와 같은 툴에서 해당 JSON 키 위에 마우스를 올리면 이 `description`에 작성한 내용이 툴팁으로 나타난다. 한글로 작성할 경우 협업하는 동료들이 API 명세서를 따로 보지 않아도 에디터 안에서 즉시 의미를 파악할 수 있다.

required (필수 항목)

`required`는 객체에서 반드시 포함되어야 하는 키(Key)의 목록을 정의한다.

  • 역할: 데이터 내에서 특정 필드가 누락되지 않도록 강제한다.
  • 특징: 필드 이름들을 배열(`[]`) 형태로 나열하며, 여기에 작성된 키가 JSON 파일에 없으면 에디터가 유효성 에러를 발생시킨다.

기본 스키마 구성하기

 

먼저 앨범(Album)과 트랙(Track) 정보를 담은 JSON 구조를 설계해보자. 이 과정에서 `enum`을 사용하여 장르를 제한하고, 정규표현식을 통해 곡 길이 포맷을 지정할 수 있다.

1. 앨범 정보 샘플 JSON (album.json)

`$schema` 속성을 통해 해당 JSON 파일이 어떤 스키마 파일을 참조할지 지정한다.

{
  "$schema": "./album-schema.json",
  "albums": [
    {
      "genre": "K-Pop",
      "price": 15000,
      "tracks": [
        { "title": "첫 번째 노래", "artist": "아이돌 A", "duration": "03:30" },
        { "title": "두 번째 노래", "artist": "아이돌 A", "duration": "03:15" },
        { "title": "세 번째 노래", "artist": "아이돌 A", "duration": "04:02" }
      ]
    },
    {
      "genre": "Rock",
      "price": 21000,
      "tracks": [
        { "title": "첫 번째 노래", "artist": "밴드 B", "duration": "04:50" },
        { "title": "두 번째 노래", "artist": "밴드 B", "duration": "03:45" },
        { "title": "세 번째 노래", "artist": "밴드 B", "duration": "05:10" }
      ]
    }
  ]
}

2. 초기 스키마 정의 (album-schema.json)

`enum`을 사용하여 장르를 제한하고, pattern으로 곡 길이 포맷을 지정하는 등 상세한 제약 조건을 추가할 수 있다. 각 필드에 `description`을 한글로 추가하면 에디터에서 마우스를 올렸을 때 설명이 나타난다. 또한 `required`를 사용하여 필수 데이터 누락을 방지 할 수 있다.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "albums": {
      "type": "array",
      "description": "앨범 정보들이 담긴 리스트",
      "items": {
        "type": "object",
        "properties": {
          "genre": {
            "type": "string",
            "enum": ["K-Pop", "Rock", "Jazz", "Classical"],
            "description": "음악 장르 (K-Pop, Rock, Jazz, Classical 중 선택)"
          },
          "price": { "type": "number", "description": "앨범 판매 가격" },
          "tracks": {
            "type": "array",
            "description": "해당 앨범의 트랙 리스트",
            "items": {
              "type": "object",
              "properties": {
                "title": { "type": "string", "description": "곡 제목" },
                "artist": { "type": "string", "description": "아티스트 이름" },
                "duration": {
                  "type": "string",
                  "pattern": "^[0-9]{2}:[0-9]{2}$",
                  "description": "곡 길이 (00:00 포맷)"
                }
              },
              "required": ["title", "artist", "duration"]
            }
          }
        },
        "required": ["genre", "price", "tracks"]
      }
    }
  },
  "required": ["albums"]
}

 

definitions를 이용한 구조 개선

위의 방식은 구조가 복잡해질수록 가독성이 떨어지고 중복 코드가 발생한다. 이때 `$defs` (또는 `definitions`) 섹션을 사용하면 특정 데이터 구조를 변수처럼 정의하고 재사용할 수 있다. 이는 유지보수와 확장성 측면에서 매우 유리하다.

개선된 스키마 구조

트랙 정보를 별도로 분리하여 정의하고 `$ref`를 통해 참조하는 방식이다.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "albums": {
      "type": "array",
      "items": { "$ref": "#/$defs/albumItem" }
    }
  },
  "$defs": {
    "albumItem": {
      "type": "object",
      "description": "개별 앨범 데이터 구조",
      "properties": {
        "genre": { "type": "string", "enum": ["K-Pop", "Rock", "Jazz"] },
        "price": { "type": "number" },
        "tracks": {
          "type": "array",
          "items": { "$ref": "#/$defs/trackItem" }
        }
      },
      "required": ["genre", "price", "tracks"]
    },
    "trackItem": {
      "type": "object",
      "description": "개별 트랙 데이터 구조",
      "properties": {
        "title": { "type": "string", "description": "곡의 정식 제목" },
        "artist": { "type": "string", "description": "참여 아티스트 명" },
        "duration": {
          "type": "string",
          "pattern": "^[0-5][0-9]:[0-5][0-9]$",
          "description": "곡 재생 시간 (분:초)"
        }
      },
      "required": ["title", "artist", "duration"]
    }
  }
}

 

 

 

마무리

JSON Schema는 단순히 데이터 형식을 검사하는 도구를 넘어 개발자에게 편리한 편집 환경을 제공하는 가이드라인 역할을 한다. `properties`로 구조를 잡고, `type`으로 형식을 강제하며, `description`으로 친절한 툴팁을 제공하는 것만으로도 코드의 품질은 몰라보게 좋아진다. 특히 대규모 프로젝트에서 복잡한 설정 파일을 다룰 때 스키마의 존재 여부는 개발 생산성에 결정적인 차이를 만든다.

'Dev' 카테고리의 다른 글

VS Code: JSON 파일에서 컬러 피커(color picker)가 사라졌을 때 해결 방법  (0) 2026.01.12
Github Personal Access Token 발급 및 환경변수 등록 가이드  (1) 2025.10.03
VS Code 개발 생산성을 높이는 나만의 컬러 테마 3종 소개  (0) 2025.07.29
npx/uvx 사용 시 캐시 누적 문제와 해결 방법  (1) 2025.07.06

티스토리툴바