JSON 작성법 - 6가지 데이터 타입·중첩 구조와 문법 규칙 정리

Q: JSON에 주석을 작성할 수 있나요?

작성할 수 없습니다. 표준 JSON 사양(RFC 8259)에는 //나 /* */, # 같은 주석 문법이 포함되어 있지 않습니다. 설정 파일에 주석을 남겨야 한다면 JSONC나 JSON5 확장 사양을 지원하는 도구를 사용하거나, "_comment": "설명 내용"처럼 관례적인 더미 키를 활용하는 방법이 있습니다.

Q: JSON의 마지막 요소 뒤에 쉼표(후행 쉼표)를 붙여도 되나요?

붙일 수 없습니다. 객체나 배열의 마지막 요소 뒤에 쉼표를 넣으면 거의 모든 JSON 파서에서 문법 오류(SyntaxError)가 발생합니다. 프로그래밍 언어의 배열 리터럴에서 복사해 올 때 특히 주의해야 합니다.

Q: JSON의 키는 반드시 큰따옴표로 감싸야 하나요?

네, 반드시 큰따옴표로 감싸야 합니다. JavaScript 객체처럼 {name: "Alice"}와 같이 작성하거나 작은따옴표를 쓴 {'name': 'Alice'}는 모두 올바른 JSON이 아닙니다. 반드시 {"name": "Alice"} 형태로 작성해야 합니다.

JSON의 문법 규칙은 매우 단순합니다. 사용할 수 있는 데이터 타입은 6가지이며, 데이터를 담는 컨테이너 구조는 객체와 배열 2가지뿐입니다. 그 외에는 몇 가지 규칙만 기억하면 됩니다. 그런데도 직접 손으로 작성할 때 실수가 자주 일어나는 이유는 JavaScript나 Python처럼 상대적으로 문법이 유연한 프로그래밍 언어의 작성 방식에 익숙해져 있기 때문입니다. 이 글에서는 JSON에서 사용할 수 있는 6가지 데이터 타입의 작성법과 문법 규칙을 코드 예제와 함께 정리합니다.

JSON 문법은 RFC 8259새 탭에서 열립니다와 ECMA-404새 탭에서 열립니다 표준 사양으로 정의되어 있으며, 두 사양의 문법 정의는 완전히 일치합니다. 이 가이드는 표준 사양의 규칙을 실무 예제와 함께 설명하고, 직접 작성할 때 자주 마주치는 오류 패턴과 해결 방법까지 함께 다룹니다.

JSON의 기본 개념이나 다른 데이터 형식과의 차이점에 대해서는 JSON이란? 글을 참고하세요.

작성한 JSON이 올바른 문법을 따르고 있는지 확인하고 싶다면 JSON 포맷터에 붙여넣어 보세요. 문법 오류가 있는 위치를 줄 번호와 함께 즉시 표시해 주며, 모든 처리는 브라우저 내부에서만 실행되므로 외부로 데이터가 전송되지 않습니다.

문자열(String)

문자열은 반드시 큰따옴표 "로 감싸야 합니다. 작은따옴표 '나 백틱(`)은 JSON 표준에서 사용할 수 없습니다.

{
  "greeting": "안녕하세요",
  "empty": ""
}

이스케이프 시퀀스

문자열 안에 특수 문자나 제어 문자를 포함해야 할 때는 백슬래시(\)로 이스케이프해야 합니다.

표기	의미
`\"`	큰따옴표
`\\`	백슬래시
`\/`	슬래시(이스케이프는 선택 사항)
`\b`	백스페이스(Backspace)
`\f`	폼 피드(Form feed)
`\n`	줄바꿈(Line feed)
`\r`	캐리지 리턴(Carriage return)
`\t`	탭(Tab)
`\uXXXX`	4자리 16진수 Unicode 코드 포인트

{
  "path": "C:\\Users\\Documents",
  "message": "첫 번째 줄\n두 번째 줄",
  "quote": "그는 \"전문가\"라고 불렸다"
}

백슬래시 이스케이프를 빠뜨리는 것은 흔한 구문 오류의 원인입니다. 특히 윈도우 파일 경로나 정규식 문자열에 들어가는 \는 반드시 \\로 이스케이프해야 합니다.

U+0000부터 U+001F까지의 제어 문자는 문자열 안에 그대로 넣을 수 없으며 반드시 이스케이프해야 합니다. 탭이나 줄바꿈을 리터럴 그대로 적으면 파싱 오류가 발생하므로 \t와 \n을 사용합니다.

유니코드 표현

JSON은 기본적으로 UTF-8 인코딩을 전제로 하므로 한글이나 이모지를 문자열 안에 직접 입력할 수 있습니다. 입력하기 어려운 특수 기호나 인코딩 문제를 피해야 하는 경우에는 \uXXXX 형식의 이스케이프를 사용할 수도 있습니다.

{
  "direct": "안녕하세요",
  "escaped": "\uc548\ub my\ud558\uc138\uc640"
}

숫자(Number)

숫자는 따옴표 없이 그대로 작성합니다. 정수, 소수(부동소수점), 음수, 지수 표기법(e/E)을 모두 지원합니다.

{
  "integer": 42,
  "negative": -10,
  "decimal": 3.14,
  "exponent": 1.5e3
}

1.5e3은 1500($1.5 \times 10^3$)을 의미합니다. 과학 기술 계산 데이터나 큰 단위의 수치를 다룰 때 사용됩니다.

숫자를 작성할 때 주의할 제약 사항은 다음과 같습니다.

선행 0(Leading zero)을 붙인 숫자(007, 012 등)는 사용할 수 없습니다. 7, 12로 작성해야 합니다.
16진수(0xFF)나 8진수(0o77) 표기는 지원하지 않습니다.
소수점 앞이나 뒤의 숫자를 생략할 수 없습니다(.5나 42.는 불가하며 0.5, 42.0으로 써야 합니다).
NaN(Not a Number)이나 Infinity는 JSON 표준 숫자가 아닙니다. 파싱 시 오류가 발생합니다.

// 아래는 모두 JSON에서 유효하지 않은 숫자 표현입니다
007
NaN
Infinity
.5

(참고: 표준 JSON에는 주석 문법이 없습니다. 위의 //는 설명을 위해 덧붙인 표기입니다.)

큰 정수의 정밀도 한계

JSON 사양 자체는 숫자의 정밀도 한계를 규정하지 않지만, 실무에서 쓰이는 대부분의 파서(JavaScript 내장 JSON.parse 포함)는 IEEE 754 배정밀도 부동소수점(double-precision)을 사용해 숫자를 해석합니다.

이로 인해 $2^{53}$(= 9,007,199,254,740,992)을 초과하는 64비트 정수는 파싱 과정에서 하위 비트가 반올림되어 정밀도 손실이 발생할 수 있습니다.

따라서 Twitter/X의 snowflake ID나 Discord ID, 데이터베이스의 64비트 정수 기본 키(PK)처럼 매우 큰 숫자를 다루는 API에서는 숫자 대신 문자열로 감싸서 전달하는 것이 표준적인 관례입니다.

{
  "safe_id": 9007199254740991,
  "snowflake_id": "9007199254740993"
}

클라이언트에서 JSON.parse를 거친 뒤 64비트 정수를 손실 없이 다루려면, 문자열 형태로 받아 BigInt 등으로 변환하는 방식이 안전합니다.

불리언(Boolean)

참과 거짓을 나타내는 true와 false 두 가지 값만 존재합니다. 반드시 모든 글자를 소문자로 작성해야 합니다.

{
  "isActive": true,
  "isDeleted": false
}

True, FALSE, yes, no, 1, 0 등은 JSON에서 불리언 값으로 인식되지 않습니다. Python(True/False)이나 YAML(yes/no)에서 데이터를 복사해 올 때 실수하기 쉬운 부분입니다.

null

값이 존재하지 않거나 비어 있음을 명시적으로 나타낼 때 null을 사용합니다. 불리언과 마찬가지로 반드시 소문자로 작성해야 합니다.

{
  "middleName": null,
  "deletedAt": null
}

빈 문자열 ""과 null은 의미가 다릅니다. "값은 존재하지만 빈 상태"인지, 아니면 "값 자체가 존재하지 않음"인지를 구분해야 하는 상황에서 null을 활용합니다. JavaScript의 undefined, Python의 None, Ruby의 nil은 JSON에 존재하지 않으므로 모두 null로 표현해야 합니다.

배열(Array)

대괄호 []로 감싸며, 각 요소를 쉼표 ,로 구분합니다. 배열은 순서가 있는 값의 목록입니다.

{
  "colors": ["red", "green", "blue"],
  "scores": [85, 92, 78],
  "flags": [true, false, true]
}

요소가 하나도 없는 빈 배열도 유효합니다.

{
  "items": []
}

문법상으로는 하나의 배열 안에 여러 데이터 타입을 섞어서 넣는 것도 가능합니다.

["text", 42, true, null]

하지만 실무에서는 하나의 배열 안에 동일한 타입의 데이터만 넣는 것이 관례입니다. 서로 다른 타입이 섞여 있으면 데이터를 받아 처리하는 프로그램 측의 로직이 불필요하게 복잡해지기 때문입니다.

객체(Object)

중괄호 {}로 감싸며, 키: 값 쌍을 쉼표 ,로 구분합니다. 키는 반드시 큰따옴표 "로 감싼 문자열이어야 합니다.

{
  "id": 1,
  "name": "상품A",
  "price": 1500
}

빈 객체도 유효한 JSON입니다.

{
  "metadata": {}
}

JSON 명세에서 객체는 키의 순서를 갖지 않습니다. {"a": 1, "b": 2}와 {"b": 2, "a": 1}은 의미상 동일합니다. 실제로는 대부분의 파서가 삽입 순서를 유지하지만, 키 순서에 의존하는 로직을 작성해서는 안 됩니다.

키 중복에 관한 주의점

JSON 표준 사양에서 동일한 객체 내 키 중복을 엄격하게 금지하지는 않지만, 중복된 키를 처리하는 방식은 파서 라이브러리마다 다릅니다.

{
  "name": "Alice",
  "name": "Bob"
}

대부분의 파서는 "나중에 정의된 값(Bob)"으로 덮어쓰지만, 첫 번째 값(Alice)을 유지하거나 파싱 오류를 발생시키는 파서도 있습니다. 따라서 시스템 간 상호운용성을 보장하려면 객체 안에 중복된 키를 만들지 않아야 합니다.

중첩 구조(Nesting)

JSON의 강력한 표현력은 객체와 배열을 자유롭게 중첩(Nesting)할 수 있는 구조에서 나옵니다.

객체 안의 객체

연관된 설정이나 세부 정보를 계층적으로 묶을 때 사용합니다.

{
  "user": {
    "name": "홍길동",
    "contact": {
      "email": "hong@example.com",
      "phone": "010-1234-5678"
    }
  }
}

배열 안의 객체

REST API 응답이나 데이터베이스 조회 결과 목록을 반환할 때 가장 자주 쓰이는 패턴입니다.

{
  "users": [
    {
      "id": 1,
      "name": "홍길동",
      "role": "admin"
    },
    {
      "id": 2,
      "name": "김영희",
      "role": "editor"
    }
  ]
}

객체 안의 배열

하나의 데이터 항목에 여러 개의 하위 태그나 리스트가 포함될 때 유용합니다.

{
  "order": {
    "id": "ORD-2026-001",
    "items": [
      { "product": "노트북", "quantity": 1 },
      { "product": "무선 마우스", "quantity": 2 }
    ],
    "tags": ["urgent", "electronics"]
  }
}

중첩 구조가 4~5단계 이상 지나치게 깊어지면 사람이 읽기 어렵고 코드에서도 접근 경로가 길어집니다. 중첩이 깊어질 때는 데이터 모델을 평탄화(Flat)할 수 있는지 검토하는 것이 좋습니다.

JSON 최상위(루트) 요소

JSON 문서의 최상위(Root)에는 객체 {} 또는 배열 []이 위치하는 것이 일반적입니다.

RFC 8259 표준 사양상으로는 문자열("hello"), 숫자(42), 불리언(true), null 같은 단일 원시값도 최상위 요소로 유효하지만, 실무에서 생성되고 교환되는 JSON 문서는 거의 대부분 객체나 배열로 시작합니다.

{
  "status": "success",
  "code": 200
}

[1, 2, 3, 4, 5]

공백 문자와 압축 포맷

JSON 파서는 토큰 사이에 들어가는 공백 문자(스페이스, 탭, 줄바꿈)를 무시합니다. 따라서 아래 세 가지 형태는 문법적으로 완전히 동일한 의미를 가집니다.

압축(Compact) 형태:

{"name":"홍길동","age":30}

정렬(Formatted) 형태:

{
  "name": "홍길동",
  "age": 30
}

불규칙한 공백 형태:

{
    "name"  :  "홍길동"  ,
    "age"   :  30
}

네트워크 전송이나 저장 공간 절약에는 불필요한 공백을 제거한 압축 형태가 유리하고, 개발자가 직접 확인하거나 설정을 편집할 때는 들여쓰기가 적용된 정렬 형태가 훨씬 읽기 편합니다.

자주 발생하는 문법 오류

직접 손으로 JSON을 작성하거나 수정할 때 자주 발생하는 오류 패턴을 정리합니다.

1. 후행 쉼표(Trailing Comma)

{
  "a": 1,
  "b": 2,
}

객체나 배열의 마지막 요소 뒤에 붙은 쉼표는 JSON 표준에서 허용되지 않습니다. JavaScript, TypeScript, Python 코드에서는 후행 쉼표가 허용되는 경우가 많아 코드를 복사해 붙여넣을 때 가장 빈번하게 발생하는 오류입니다(Unexpected token } 에러가 발생합니다). 에러 메시지 패턴과 구체적인 해결 방법은 JSON 후행 쉼표 오류 해결법에서 자세히 다룹니다.

2. 작은따옴표 사용

{'name': '홍길동'}

JSON에서는 키와 문자열 값 모두 반드시 큰따옴표 "를 써야 합니다. 작은따옴표 '는 문법 오류입니다.

3. 키에 따옴표 생략

{name: "홍길동"}

JavaScript 객체 리터럴에서는 따옴표 없는 키가 허용되지만, JSON에서는 키를 반드시 큰따옴표로 감싸야 합니다.

4. 주석 작성

{
  // 이 주석은 문법 오류를 일으킵니다
  "name": "홍길동"
}

표준 JSON 사양에는 주석 문법이 정의되어 있지 않습니다. //, /* */, # 기호를 적으면 파서가 즉시 거부합니다. 주석이 필요한 설정 파일이라면 JSONC나 JSON5 확장 형식을 지원하는 환경을 사용해야 합니다. 자세한 대안과 활용법은 JSON 주석처리 방법을 참고하세요.

5. `undefined`와 `NaN` 사용

{
  "value": undefined,
  "result": NaN
}

JavaScript의 undefined와 NaN은 JSON 표준 값이 아닙니다. 값이 없는 상태는 null로 표기하고, 수치 계산 실패는 null 또는 문자열 "NaN"으로 명시해야 합니다.

6. 따옴표 없는 단독 문자열

hello

따옴표가 없는 일반 단어는 올바른 JSON이 아닙니다. 문자열로 쓰려면 "hello"와 같이 큰따옴표를 붙여야 합니다.

이러한 문법 및 파싱 오류의 원인과 해결 방법은 JSON 파싱 오류 해결 방법에서 자세히 다루고 있습니다.

빠른 참조(Quick Reference)

JSON에서 사용할 수 있는 모든 데이터 타입과 특징을 한눈에 정리한 표입니다.

데이터 타입	예제	작성 시 주의 사항
문자열(String)	`"안녕하세요"`	반드시 큰따옴표 `"` 사용. 제어 문자는 `\` 이스케이프 필요
숫자(Number)	`42`, `3.14`, `-10`, `1.5e3`	선행 0 불가, 16진수 불가, `NaN`·`Infinity` 불가
불리언(Boolean)	`true`, `false`	소문자만 유효 (`True`, `FALSE` 불가)
null	`null`	소문자만 유효 (`None`, `undefined` 불가)
객체(Object)	`{"key": "value"}`	키는 반드시 큰따옴표 문자열. 후행 쉼표 금지
배열(Array)	`[1, 2, 3]`	대괄호 사용. 요소 간 쉼표 구분. 후행 쉼표 금지

JSON 정렬과 문법 검증

JSON 작성을 마쳤다면 파서에 전달하기 전에 문법 검증을 거치는 것이 안전합니다. 닫는 괄호 누락, 이스케이프 미처리, 후행 쉼표 등은 큰 파일에서 눈으로 찾아내기 어렵습니다.

JSON 포맷터를 사용하면 붙여넣기 한 번으로 들여쓰기 정렬과 문법 유효성 검사를 동시에 진행할 수 있습니다. 문법 오류가 있다면 문제가 발생한 줄 번호와 원인을 명확하게 안내합니다.

터미널이나 명령줄 환경(CLI)에서 빠르게 검증하고 싶다면 다음 명령어를 활용할 수 있습니다.

# Python 표준 라이브러리 활용
python3 -m json.tool < file.json

# jq 도구 활용
jq . file.json

두 도구 모두 문법이 올바르면 보기 좋게 정렬된 결과를 출력하고, 문법 오류가 있으면 오류가 발생한 위치를 알려 줍니다. JSON을 보기 좋게 정렬하는 방법은 JSON 정렬(Pretty Print) 방법을, curl로 API 응답을 받아 정렬하는 방법은 curl JSON pretty print 방법 4가지를 참조하세요.

데이터 모델이 유사한 YAML 작성법과 비교해 보고 싶다면 YAML 문법 가이드를 참조하세요.

JSON 작성 관습

JSON의 문법 자체는 고정되어 있지만, 다루기 쉽게 만들기 위한 관습이 있습니다.

들여쓰기는 공백 2칸이 가장 일반적입니다
구조가 비슷한 객체끼리는 키의 순서를 맞춥니다
키 이름은 camelCase나 snake_case 중 하나로 통일합니다
평평한 구조로 표현할 수 있다면 깊은 중첩은 피합니다

이러한 관습의 자세한 내용은 JSON 정렬의 기본을 참고하세요.

자주 묻는 질문

JSON에 주석을 작성할 수 있나요?

작성할 수 없습니다. 표준 JSON 사양(RFC 8259)에는 //나 /* */, # 같은 주석 문법이 포함되어 있지 않습니다. 설정 파일에 주석을 남겨야 한다면 JSONC나 JSON5 확장 사양을 지원하는 도구를 사용하거나, "_comment": "설명 내용"처럼 관례적인 더미 키를 활용하는 방법이 있습니다.

JSON의 마지막 요소 뒤에 쉼표(후행 쉼표)를 붙여도 되나요?

붙일 수 없습니다. 객체나 배열의 마지막 요소 뒤에 쉼표를 넣으면 거의 모든 JSON 파서에서 문법 오류(SyntaxError)가 발생합니다. 프로그래밍 언어의 배열 리터럴에서 복사해 올 때 특히 주의해야 합니다.

JSON의 키는 반드시 큰따옴표로 감싸야 하나요?

네, 반드시 큰따옴표로 감싸야 합니다. JavaScript 객체처럼 {name: "Alice"}와 같이 작성하거나 작은따옴표를 쓴 {'name': 'Alice'}는 모두 올바른 JSON이 아닙니다. 반드시 {"name": "Alice"} 형태로 작성해야 합니다.

JSON 파싱 오류가 발생했을 때 위치를 빠르게 찾는 방법은?

JSON 포맷터에 내용을 붙여넣으면 문법 오류가 발생한 줄 번호와 오류 메시지가 표시됩니다. 터미널 환경이라면 python3 -m json.tool < file.json 명령어로도 줄 번호가 포함된 오류를 즉시 확인할 수 있습니다.

정리

문자열은 반드시 큰따옴표 "로 감싸며, 특수 문자는 백슬래시(\)로 이스케이프합니다.
숫자는 따옴표 없이 적으며, 선행 0이나 NaN, Infinity는 허용되지 않습니다.
$2^{53}$을 초과하는 64비트 정수 ID는 정밀도 손실을 방지하기 위해 문자열로 전달하는 것이 안전합니다.
불리언(true, false)과 null은 반드시 소문자로만 작성합니다.
객체 {}의 키는 항상 큰따옴표가 붙은 문자열이어야 합니다.
배열 []과 객체 {}의 마지막 요소 뒤에는 후행 쉼표(trailing comma)를 남기지 않습니다.
작성을 마친 JSON은 JSON 포맷터를 통해 브라우저에서 안전하게 정렬하고 문법 오류를 검증할 수 있습니다.

다음에 읽을 글

JSON 포맷터 — JSON 검증과 정렬
JSON 파싱 오류 해결 방법 — 구문 오류가 발생했을 때
JSON 정렬의 기본 — 관습과 모범 사례
JSON이란 — JSON 전반의 개요와 쓰이는 곳
YAML 작성법 가이드 — 같은 데이터 모델의 들여쓰기 방식 문법

문자열(String)

이스케이프 시퀀스

유니코드 표현

숫자(Number)

큰 정수의 정밀도 한계

불리언(Boolean)

null

배열(Array)

객체(Object)

키 중복에 관한 주의점

중첩 구조(Nesting)

객체 안의 객체

배열 안의 객체

객체 안의 배열

JSON 최상위(루트) 요소

공백 문자와 압축 포맷

자주 발생하는 문법 오류

1. 후행 쉼표(Trailing Comma)

2. 작은따옴표 사용

3. 키에 따옴표 생략

4. 주석 작성

5. undefined와 NaN 사용

6. 따옴표 없는 단독 문자열

빠른 참조(Quick Reference)

JSON 정렬과 문법 검증

JSON 작성 관습

자주 묻는 질문

JSON에 주석을 작성할 수 있나요?

JSON의 마지막 요소 뒤에 쉼표(후행 쉼표)를 붙여도 되나요?

JSON의 키는 반드시 큰따옴표로 감싸야 하나요?

JSON 파싱 오류가 발생했을 때 위치를 빠르게 찾는 방법은?

정리

다음에 읽을 글

5. `undefined`와 `NaN` 사용