모든 개발자가 알아야 할 JSON 포맷팅 모범 사례

JSON 구조의 기초

JSON(JavaScript Object Notation)은 구조화된 데이터를 표현하기 위한 경량 텍스트 포맷입니다. 이름에 JavaScript가 포함되어 있지만 실제로는 언어에 독립적이며 REST API부터 설정 파일까지 모든 곳에서 사용됩니다. 유효한 JSON 문서는 객체(중괄호로 감싼 키-값 쌍의 집합) 또는 배열(대괄호로 감싼 순서가 있는 목록) 중 하나입니다.

JSON의 여섯 가지 값 타입은 문자열, 숫자, 불리언(true/false), null, 객체, 배열입니다. JSON 객체의 모든 키는 큰따옴표로 감싼 문자열이어야 합니다. 작은따옴표나 따옴표 없는 식별자는 허용되지 않습니다.

일반적인 구문 오류

JSON은 엄격합니다. 구문 오류 하나만으로 전체 문서를 파싱할 수 없게 됩니다. 가장 자주 발생하는 실수들은 다음과 같습니다.

• 후행 쉼표: {"name": "Alice",} — 마지막 항목 뒤의 쉼표는 JSON에서 허용되지 않습니다(JavaScript에서는 유효하여 혼란을 일으킵니다).
• 작은따옴표 문자열: JSON은 큰따옴표를 요구합니다. {'key': 'value'}는 유효한 JSON이 아닙니다.
• 따옴표 없는 키: {name: "Alice"}는 JavaScript 객체 리터럴 구문으로, JSON이 아닙니다.
• 주석: JSON은 주석을 지원하지 않습니다. 설정 파일에 주석이 필요하다면 JSONC나 YAML을 고려하세요.
• Undefined와 NaN: 이 JavaScript 값들은 JSON에 존재하지 않습니다. null을 사용하거나 해당 필드를 생략하세요.
• 이스케이프되지 않은 제어 문자: 문자열 내의 줄바꿈은 실제 줄바꿈이 아니라 \n으로 작성해야 합니다.

가독성을 위한 포맷팅

네트워크로 전송되는 JSON은 페이로드 크기를 줄이기 위해 종종 최소화됩니다. 공백을 제거하는 것입니다. 하지만 설정 파일에 저장되거나 버전 관리에 커밋되는 JSON은 사람이 읽기 쉽도록 포맷해야 합니다. 표준 규칙은 다음과 같습니다.

• 들여쓰기 레벨당 2칸 또는 4칸(하나를 선택하고 일관성 유지)
• 객체의 키-값 쌍은 한 줄에 하나씩
• 여는 중괄호는 부모 키와 같은 줄에, 닫는 중괄호는 별도의 줄에
• 단순한 값의 배열은 짧다면 한 줄에 작성 가능

대부분의 편집기는 JSON을 자동으로 포맷할 수 있습니다. VS Code에서는 마우스 오른쪽 클릭 후 "문서 서식 지정"을 선택하거나 단축키 Shift+Alt+F를 사용하세요. 커맨드라인 사용자는 jq . input.json으로 JSON 파일을 예쁘게 출력할 수 있습니다.

명명 규칙

JSON 자체는 명명 규칙을 강제하지 않지만, API나 코드베이스에서 하나를 선택하고 일관성을 유지해야 합니다. 세 가지 일반적인 패턴은 다음과 같습니다.

• camelCase (firstName) — JavaScript API와 대부분의 REST 서비스에서 표준
• snake_case (first_name) — Python API와 PostgreSQL에서 일반적
• PascalCase (FirstName) — 일부 .NET 및 C# 환경에서 사용

단일 API에서 규칙을 혼용하면 혼란을 일으킵니다. 한 가지 규칙을 사용하는 API를 소비하지만 코드베이스는 다른 규칙을 사용한다면, 코드 전반에 임시 변환을 분산시키는 대신 전용 직렬화 레이어에서 변환을 처리하세요.

Null과 누락 필드 처리

JSON 객체는 값의 부재를 두 가지 방식으로 표현할 수 있습니다. 키가 null 값과 함께 존재하거나, 키 자체가 완전히 없거나. 이 두 가지는 서로 다른 의미를 갖습니다. 필드가 예상되지만 값이 없을 때(예: 사용자가 비워둔 중간 이름 필드)는 null을 사용하세요. 해당 레코드에 전혀 해당하지 않는 필드는 생략하세요. API 내에서 일관된 접근 방식을 결정하여 소비자가 무엇을 기대해야 할지 알 수 있게 하세요.

큰 숫자와 정밀도

JSON 숫자에는 정해진 크기 제한이 없지만, 많은 파서들이 이를 IEEE 754 배정밀도 부동소수점 값으로 역직렬화합니다. 즉, 2^53보다 큰 정수는 정확하게 표현될 수 없습니다. JSON에 큰 정수(데이터베이스 ID, 보조 통화 단위의 금액, 암호화 식별자)가 필요하다면 문자열로 표현하고 API에 이를 문서화하세요. 트위터의 트윗 ID와 관련된 유명한 함정이 바로 이 경우입니다.

JSON 검증

구문 검증(이것이 유효한 JSON인가?)을 넘어, JSON Schema를 사용하면 문서의 예상 형태를 정의할 수 있습니다. 어떤 필드가 필수인지, 그 타입은 무엇인지, 값의 범위 등을 지정합니다. ajv(JavaScript), jsonschema(Python) 같은 도구와 온라인 검증기는 JSON 문서를 스키마에 맞게 검사할 수 있습니다. 프로덕션 환경에서 게시하거나 소비하는 API에는 경계 지점에서 JSON Schema 검증을 구현하는 것이 좋습니다.

TheDailyUtils의 JSON 포맷터 및 검증기 같은 도구는 낯선 페이로드에서 구문 오류를 잡는 가장 빠른 방법입니다. 원시 JSON을 붙여넣으면 파싱 가능 여부와 오류 위치를 즉시 확인할 수 있습니다.

즉시 JSON 포맷 및 검증하기

무료 JSON 포맷터 열기 — JSON을 붙여넣어 예쁘게 출력하거나, 최소화하거나, 구문 오류를 수 초 안에 잡아내세요. 브라우저에서 실행되며 데이터는 비공개로 유지됩니다.