JSON 정렬(Pretty Print) 방법과 오류 해결 - 브라우저·jq·코드 예제

Q: JSON.stringify의 들여쓰기 인자에는 어떤 값을 넣을 수 있나요?

JSON.stringify(value, replacer, space)의 세 번째 인자 space에는 들여쓰기 공백 수(최대 10)를 나타내는 숫자나, 들여쓰기에 사용할 문자열("\t" 등)을 지정할 수 있습니다. 실무에서는 가독성과 파일 용량 균형을 위해 2를 가장 많이 사용합니다.

Q: 터미널에서 jq 없이 JSON을 정렬하려면 어떻게 하나요?

Python 3가 설치되어 있다면 추가 설치 없이 python3 -m json.tool 명령을 사용하거나, Node.js를 이용해 node -e 'console.log(JSON.stringify(JSON.parse(process.argv[1]), null, 2))' '{"a":1}' 형태로 정렬할 수 있습니다.

결론부터

브라우저에서 정렬: FormatArc의 JSON 포맷터에 붙여넣기만 하면 즉시 완료 (데이터는 브라우저 안에서만 처리됨)
터미널에서 정렬: echo '{...}' | jq . 또는 python3 -m json.tool
코드 안에서 정렬: JavaScript/Node.js에서는 JSON.stringify(data, null, 2)

세 가지 접근 방식을 차례대로 설명합니다. 자주 발생하는 구문 오류의 대처법과 상황별 도구 선택 기준도 함께 알아봅니다.

JSON 정렬(Pretty Print)이란

JSON(JavaScript Object Notation)은 웹 API 응답과 애플리케이션 설정 파일 등 시스템 간 데이터 교환에 가장 널리 쓰이는 표준 포맷 중 하나입니다.

하지만 전송 효율을 위해 압축(minify)된 한 줄짜리 JSON은 사람이 한눈에 구조를 파악하기 어렵습니다. 개발과 디버깅 과정에서 적절한 들여쓰기와 줄바꿈을 적용해 읽기 쉽게 정렬(pretty-print)하는 작업이 일상적으로 필요합니다.

자주 발생하는 JSON 구문 오류

JSON 문법은 두 가지 공식 사양인 RFC 8259새 탭에서 열립니다(IETF 표준)와 ECMA-404새 탭에서 열립니다(ECMA 표준)에 정의되어 있습니다. 두 표준은 동일한 구문을 규정하므로, 아래의 규칙들은 특정 포맷터의 독자적인 제약이 아니라 JSON 사양 자체에 따른 것입니다.

1. 후행 쉼표(trailing comma)

{
  "name": "example",
  "value": 42,
}

마지막 속성 뒤에 쉼표가 남아 있으면 유효한 JSON이 아닙니다. 일반 JavaScript 객체에서는 허용되지만 표준 JSON 사양에서는 엄격히 금지됩니다.

2. 작은따옴표(single quote)

{'name': 'example'}

JSON에서는 큰따옴표 "만 유효합니다. 작은따옴표 '는 사용할 수 없습니다.

3. 키의 따옴표 누락

{name: "example"}

JSON에서는 모든 객체 키(key)를 반드시 큰따옴표로 감싸야 합니다.

JSON 구문 오류 수정 요약표

자주 발생하는 구문 오류와 RFC 8259 / ECMA-404 사양에 따른 올바른 수정 방법을 정리한 표입니다.

오류 유형	잘못된 예	올바른 수정 방법
후행 쉼표(Trailing comma)	`{"a": 1,}`	마지막 값 뒤의 쉼표 삭제: `{"a": 1}`
작은따옴표	`{'a': 'b'}`	큰따옴표 사용: `{"a": "b"}`
키 따옴표 누락	`{a: 1}`	모든 키를 큰따옴표로 감싸기: `{"a": 1}`
주석	`{"a": 1} // note`	JSON은 주석을 지원하지 않음. 주석 삭제
선행 0(Leading zero)	`{"a": 01}`	숫자 앞의 0 제거: `{"a": 1}`
양의 부호(+)	`{"a": +1}`	숫자 앞의 `+` 제거: `{"a": 1}`
16진수 / 8진수	`{"a": 0x1F}`	10진수 표기만 허용: `{"a": 31}`
`NaN` / `Infinity`	`{"a": NaN}`	유효한 JSON 값이 아님. 숫자나 `null` 사용
undefined 값	`{"a": undefined}`	`undefined`는 JSON 값이 아님. `null` 사용
이스케이프되지 않은 제어 문자	`"..."` 안의 줄바꿈	문자열 안에서는 `\n`으로 이스케이프
이스케이프되지 않은 백슬래시	`{"a": "C:\path"}`	백슬래시 이스케이프: `{"a": "C:\\path"}`
값의 작은따옴표	`{"key": 'value'}`	문자열 값도 큰따옴표 필요: `{"key": "value"}`

JavaScript에서 JSON.stringify()로 정렬하기

JavaScript와 Node.js 환경에서는 내장 함수 JSON.stringify()의 세 번째 인자에 들여쓰기 공백 수를 전달하는 것만으로 정렬된 JSON을 얻을 수 있습니다.

const data = { name: "Alice", age: 30, roles: ["admin", "editor"] };

// 2칸 공백 들여쓰기로 정렬
console.log(JSON.stringify(data, null, 2));

출력 결과:

{
  "name": "Alice",
  "age": 30,
  "roles": [
    "admin",
    "editor"
  ]
}

두 번째 인자는 특정 속성을 필터링하거나 변환하는 replacer 함수 또는 배열입니다. 모든 속성을 그대로 유지하려면 null을 전달합니다.

탭(Tab) 문자로 들여쓰기하려면 다음과 같이 작성합니다.

JSON.stringify(data, null, "\t");

JavaScript에서 정렬할 때 주의할 점

JSON.stringify()는 단순한 객체에는 편리하지만, 프로덕션 코드나 복잡한 객체를 다룰 때 자주 마주치는 예외 상황이 있습니다.

순환 참조(Circular Reference)

객체가 자기 자신이나 부모 객체를 다시 참조하고 있으면 JSON.stringify는 TypeError: Converting circular structure to JSON 오류를 발생시킵니다. 이미 직렬화한 객체를 추적해 대체 문자열을 반환하는 replacer 함수로 안전하게 해결할 수 있습니다.

function safeStringify(value, space = 2) {
  const ancestors = [];
  return JSON.stringify(value, function (_key, val) {
    if (typeof val !== "object" || val === null) return val;
    while (ancestors.length && ancestors[ancestors.length - 1] !== this) {
      ancestors.pop();
    }
    if (ancestors.includes(val)) return "[Circular]";
    ancestors.push(val);
    return val;
  }, space);
}

DOM 트리, 상태 관리 라이브러리의 스토어, 또는 로거에서 request 객체를 다시 참조할 때 빈번히 발생하는 런타임 오류입니다.

toJSON()으로 출력 형식 제어하기

JSON.stringify는 각 값에 toJSON() 메서드가 구현되어 있으면 그 반환값을 사용합니다. Date 객체는 기본적으로 toJSON()을 갖고 있어 ISO 8601 문자열을 반환하지만, 커스텀 클래스에서도 동일한 방식으로 직렬화 형태를 정의할 수 있습니다.

class Money {
  constructor(amount, currency) {
    this.amount = amount;
    this.currency = currency;
  }
  toJSON() {
    return `${this.amount.toFixed(2)} ${this.currency}`;
  }
}
JSON.stringify({ price: new Money(19.9, "USD") }, null, 2);
// → { "price": "19.90 USD" }

직렬화 전에 별도의 변환 단계를 거치는 것보다 깔끔하며 들여쓰기도 그대로 유지됩니다.

replacer로 키 필터링 및 마스킹하기

두 번째 인자인 replacer는 민감한 키를 제외하거나 마스킹할 때도 유용합니다. API 응답 로그에서 비밀번호나 인증 토큰을 가려야 할 때 활용할 수 있습니다.

const redactKeys = new Set(["password", "apiKey", "authorization"]);
JSON.stringify(response, (key, value) => redactKeys.has(key) ? undefined : value, 2);

함수 대신 남겨둘 키의 배열을 전달할 수도 있습니다.

JSON.stringify(user, ["id", "email", "createdAt"], 2);

Prettier와 JSON.stringify의 구분 사용

CLI 도구인 Prettier는 TypeScript, CSS, Markdown, JSON 등 다양한 언어를 지원하는 코드 포매터입니다. 프로젝트에서 Prettier를 도입한 경우, .json 파일은 prettier --write file.json 명령으로 프로젝트 전체 규칙에 맞춰 일괄 정리할 수 있습니다.

반면 디버깅 로그 출력, API 응답의 일회성 확인, 메모리상 객체의 즉시 확인 등에는 JSON.stringify(data, null, 2)나 FormatArc의 JSON 포맷터가 훨씬 빠르고 설치도 필요 없습니다. 코드베이스 전체의 서식 통일에는 Prettier를, 일회성 확인 및 빠른 정렬에는 JSON.stringify나 온라인 도구를 사용하는 것이 적합합니다.

터미널(CLI)에서 JSON 정렬하기

jq 사용하기

jq는 경량 커맨드라인 JSON 처리 도구입니다. 파이프(|)로 JSON 문자열을 넘겨주기만 하면 바로 정렬됩니다.

echo '{"name":"Alice","age":30}' | jq .

Python 내장 모듈 사용하기

Python이 설치된 환경이라면 표준 라이브러리의 json.tool을 사용할 수 있습니다.

echo '{"name":"Alice","age":30}' | python3 -m json.tool

curl 응답 즉시 정렬하기

REST API를 디버깅할 때 curl과 jq를 연결하면 응답 데이터를 보기 좋게 출력할 수 있습니다.

curl -s https://api.example.com/data | jq .

브라우저에서 안전하고 간편하게 정렬하기

FormatArc의 JSON 포맷터를 사용하면 프로그램 설치 없이 브라우저 안에서만 안전하게 JSON을 정렬할 수 있습니다. 모든 처리가 클라이언트 사이드에서 실행되므로 API 키나 사내 데이터가 외부 서버로 전송되지 않습니다.

사용 방법

입력란에 정렬할 JSON을 붙여넣습니다
"실행" 버튼을 누릅니다
정렬된 결과를 복사합니다

간단한 세 단계로 가독성 높은 JSON 결과를 얻을 수 있습니다.

FormatArc의 한국어 JSON 포맷터 화면에서 JSON을 정렬해 표시한 결과

정렬 전 JSON 유효성 검증

JSON 문법에 오류가 있으면 정렬 처리가 실패합니다. 주된 원인은 후행 쉼표, 작은따옴표, 따옴표 없는 키 등입니다. 설정 파일에 주석을 남기고 싶다면 JSONC나 JSON5 같은 대안 포맷을 검토할 수 있습니다. 큰 파일에서는 파서가 알려주는 문자 위치(position)만으로 실제 오류 지점을 찾기 어려운 경우가 많습니다.

FormatArc의 JSON 포맷터는 구문 오류가 발생한 줄 번호를 명확히 표시하므로 문제 위치를 빠르게 특정하고 수정할 수 있습니다. 자주 발생하는 파싱 오류의 원인과 해결 방법은 JSON 파싱 오류 해결 방법에서 자세히 다루고 있습니다.

Chrome 확장 프로그램으로 JSON 자동 정렬하기

브라우저에서 API 엔드포인트를 직접 열어보는 빈도가 높다면, 브라우저가 원시 JSON 응답을 자동으로 보기 좋게 표시해 주는 크롬 확장 프로그램(JSONView, JSON Formatter 등)을 활용하는 것도 좋은 방법입니다.

다른 데이터 형식과의 연계

JSON 정렬은 다양한 데이터 형식 간의 변환 작업과 함께 쓰이는 경우가 많습니다.

YAML과 JSON의 차이 — 설정 파일과 API 통신에서 어떤 형식을 선택해야 하는지의 기준
YAML을 JSON으로 변환하는 방법 — Kubernetes 설정이나 CI/CD 구성 파일 변환 (YAML JSON 변환기)
CSV를 JSON으로 변환하는 방법 — 스프레드시트 내보내기 데이터를 JSON 배열로 변환 (CSV JSON 변환기)
JSON 문법 가이드 — 유효한 표준 JSON 작성을 위한 기본 규칙
curl 응답의 JSON을 정렬하는 방법 — 터미널에서 API를 호출하고 결과를 jq나 python으로 즉시 확인

자주 묻는 질문

JSON.stringify의 들여쓰기 인자에는 어떤 값을 넣을 수 있나요?

JSON.stringify(value, replacer, space)의 세 번째 인자 space에는 들여쓰기 공백 수(최대 10)를 나타내는 숫자나, 들여쓰기에 사용할 문자열("\t" 등)을 지정할 수 있습니다. 실무에서는 가독성과 파일 용량 균형을 위해 2를 가장 많이 사용합니다.

후행 쉼표(trailing comma)나 작은따옴표가 있는 JSON을 바로 정렬할 수 있나요?

표준 JSON 파서는 구문 오류로 중단됩니다. FormatArc의 JSON 포맷터에서는 오류 발생 시 "Auto-fix" 기능을 통해 후행 쉼표나 주석을 자동으로 감지하고 제거한 뒤 표준 JSON으로 정렬할 수 있습니다.

터미널에서 jq 없이 JSON을 정렬하려면 어떻게 하나요?

Python 3가 설치되어 있다면 추가 설치 없이 python3 -m json.tool 명령을 사용하거나, Node.js를 이용해 node -e 'console.log(JSON.stringify(JSON.parse(process.argv[1]), null, 2))' '{"a":1}' 형태로 정렬할 수 있습니다.

FormatArc에 붙여넣은 데이터가 서버로 전송되나요?

전송되지 않습니다. FormatArc의 모든 데이터 변환 및 정렬 로직은 사용자의 브라우저(WebAssembly / JavaScript) 내에서만 실행되며 서버로 데이터를 전송하지 않아 기밀 데이터나 API 토큰도 안심하고 처리할 수 있습니다.

정리

JSON 정렬(Pretty Print)은 개발 및 운영 환경에서 데이터 구조를 파악하기 위한 필수 작업입니다
JavaScript 코드 내에서는 JSON.stringify(data, null, 2)로 간단히 정렬할 수 있습니다
CLI 환경에서는 jq . 또는 python3 -m json.tool을 활용하면 빠릅니다
자주 발생하는 오류인 후행 쉼표, 작은따옴표, 키 따옴표 누락을 주의해야 합니다
브라우저에서 안전하게 작업하고 싶다면 서버 전송이 없는 JSON 포맷터를 활용해 보세요