Toolypet - Developer Tools Collection

현대 웹 개발의 공용어, JSON

웹 개발자라면 하루에도 수십 번씩 JSON을 마주합니다. API 응답을 확인하고, 설정 파일을 수정하고, 데이터베이스에서 가져온 데이터를 가공하는 모든 순간에 JSON이 있습니다. JSON(JavaScript Object Notation)이 이토록 널리 쓰이는 이유는 단순합니다. 사람이 읽기 쉽고, 기계가 파싱하기 쉽고, 거의 모든 프로그래밍 언어에서 기본적으로 지원하기 때문입니다.

하지만 단순해 보이는 JSON도 막상 다루다 보면 예상치 못한 함정에 빠지기 쉽습니다. 작은 따옴표를 썼다가 파싱 에러를 만나거나, 마지막 쉼표 하나 때문에 한 시간을 디버깅하는 경험, 개발자라면 한 번쯤 있을 겁니다. 오늘은 JSON을 더 효과적으로 다루는 방법과 흔히 저지르는 실수들을 피하는 팁을 알아보겠습니다.

JSON의 기본 구조 이해하기

JSON은 두 가지 구조를 기반으로 합니다. 이름/값 쌍의 모음인 객체(Object)와 값의 순서가 있는 목록인 배열(Array)입니다. 이 두 구조만으로 거의 모든 복잡한 데이터를 표현할 수 있다는 점이 JSON의 매력입니다.

{
  "user": {
    "name": "김개발",
    "age": 28,
    "isActive": true,
    "skills": ["JavaScript", "TypeScript", "React"],
    "address": null
  }
}

JSON이 지원하는 데이터 타입은 문자열, 숫자, 불리언, null, 배열, 객체 이렇게 여섯 가지뿐입니다. JavaScript와 달리 undefined, 함수, Date 객체 같은 것은 JSON으로 직접 표현할 수 없습니다. 날짜를 다룰 때는 ISO 8601 형식의 문자열("2025-12-26T09:00:00Z")로 표현하는 것이 관례입니다.

개발자가 자주 범하는 JSON 실수들

경험 많은 개발자들도 종종 실수하는 부분들이 있습니다. 대부분 JavaScript의 객체 리터럴 문법과 혼동해서 발생하는 문제들입니다.

가장 흔한 실수는 작은 따옴표 사용입니다. JavaScript에서는 작은 따옴표와 큰 따옴표를 자유롭게 쓸 수 있지만, JSON에서는 오직 큰 따옴표만 허용됩니다. 이 규칙은 키(key)와 문자열 값 모두에 적용됩니다.

// 잘못된 예시 - 파싱 에러 발생
{ 'name': 'John' }

// 올바른 예시
{ "name": "John" }

두 번째로 많이 하는 실수는 마지막 쉼표(trailing comma)입니다. JavaScript나 TypeScript에서는 배열이나 객체의 마지막 요소 뒤에 쉼표를 남겨둬도 문제가 없고, 오히려 git diff를 깔끔하게 유지하기 위해 권장되기도 합니다. 하지만 JSON에서는 이것이 문법 오류입니다.

// 잘못된 예시
{
  "items": [
    "apple",
    "banana",
  ]
}

// 올바른 예시
{
  "items": [
    "apple",
    "banana"
  ]
}

주석을 사용하려는 시도도 자주 보입니다. JSON은 공식적으로 주석을 지원하지 않습니다. 설정 파일에 주석이 필요하다면 JSON5나 JSONC(JSON with Comments) 형식을 고려해보세요. VS Code의 설정 파일이 JSONC 형식을 사용하는 것도 바로 이런 이유 때문입니다.

지저분한 JSON을 읽기 쉽게 만드는 법

API 응답이나 로그에서 만나는 JSON은 대부분 한 줄로 압축되어 있습니다. 네트워크 전송 효율을 높이기 위한 당연한 조치이지만, 디버깅할 때는 눈이 아파옵니다. 이럴 때 JSON 포맷터가 필요합니다.

// 압축된 상태 (Minified)
{"users":[{"id":1,"name":"Alice","email":"alice@example.com"},{"id":2,"name":"Bob","email":"bob@example.com"}]}

// 포맷팅된 상태 (Beautified)
{
  "users": [
    {
      "id": 1,
      "name": "Alice",
      "email": "alice@example.com"
    },
    {
      "id": 2,
      "name": "Bob",
      "email": "bob@example.com"
    }
  ]
}

들여쓰기가 적용된 JSON은 데이터의 구조를 한눈에 파악할 수 있게 해줍니다. 중첩된 객체의 깊이를 시각적으로 확인할 수 있고, 배열의 각 요소가 어디서 시작하고 끝나는지도 명확합니다. 반대로 프로덕션에 배포할 때는 공백과 줄바꿈을 제거해 용량을 줄이는 것이 좋습니다. 큰 JSON 파일의 경우 압축만으로도 20-30%의 용량을 줄일 수 있습니다.

API 디버깅을 위한 실전 팁

터미널에서 API를 테스트할 때 curl과 jq의 조합은 강력한 무기가 됩니다. jq는 JSON을 처리하는 커맨드라인 도구로, 예쁘게 출력하는 것은 물론이고 데이터를 필터링하고 변환하는 것도 가능합니다.

# API 응답을 예쁘게 출력
curl -s https://api.example.com/users | jq '.'

# 첫 번째 사용자의 이름만 추출
curl -s https://api.example.com/users | jq '.data[0].name'

# 모든 사용자의 이메일 목록 추출
curl -s https://api.example.com/users | jq '.data[].email'

브라우저 개발자 도구에서도 JSON을 다룰 일이 많습니다. Network 탭에서 API 응답을 볼 때, Response 탭 대신 Preview 탭을 사용하면 자동으로 포맷팅된 JSON을 볼 수 있습니다. 하지만 복사해서 다른 곳에서 사용하려면 여전히 외부 도구가 필요합니다.

JSON Path로 복잡한 데이터 탐색하기

대규모 JSON 데이터에서 특정 값을 찾아야 할 때 JSON Path가 유용합니다. XPath가 XML을 탐색하는 것처럼, JSON Path는 JSON 데이터를 탐색하는 쿼리 언어입니다.

// 복잡한 JSON 구조
{
  "store": {
    "name": "온라인 서점",
    "books": [
      { "title": "자바스크립트 완벽 가이드", "price": 35000, "inStock": true },
      { "title": "리액트를 다루는 기술", "price": 32000, "inStock": false },
      { "title": "Node.js 교과서", "price": 28000, "inStock": true }
    ]
  }
}

// JSON Path 예시
$.store.books[*].title          // 모든 책 제목
$.store.books[?(@.inStock)].title   // 재고 있는 책 제목만
$.store.books[?(@.price < 30000)]   // 3만원 미만 책

이런 쿼리는 테스트 자동화나 데이터 검증에서 특히 유용합니다. Postman 같은 API 테스트 도구에서도 JSON Path를 지원하므로, 익혀두면 여러 곳에서 활용할 수 있습니다.

마무리하며

JSON은 단순한 형식이지만, 잘 다루면 개발 생산성을 크게 높일 수 있습니다. 적절한 도구를 사용해 가독성을 높이고, 유효성을 검사하고, 필요한 데이터를 빠르게 추출하세요. Toolypet의 JSON Formatter는 포맷팅, 압축, 문법 검증을 한 곳에서 처리할 수 있어 일상적인 JSON 작업을 훨씬 수월하게 만들어줍니다.

다음에 API 응답이 한 줄로 뭉쳐 있어서 답답할 때, 또는 파싱 에러가 났는데 어디가 문제인지 모르겠을 때, 생각나는 도구가 되었으면 좋겠습니다.