JSON Toolkit

JSON 배열과 객체 작성법: 구조와 중첩 입문

핵심 요약: JSON 의 두 가지 컨테이너를 한 번에 정리합니다. 객체는 필드를, 배열은 목록을 담당하며, 중첩 조합 방법, 언제 무엇을 쓸지, 숫자 키 가짜 배열·트레일링 콤마·작은따옴표 같은 세 가지 흔한 오류의 수정법까지 다룹니다.

초급약 6분 소요2026-11-20 발행2026-11-20 업데이트
JSON 배열과 객체 구조 입문 커버

JSON 이 제공하는 컨테이너는 두 가지뿐입니다. 객체는 "이름이 붙은 필드"를, 배열은 "순서가 있는 목록"을 담당합니다. 잘못 쓰이는 문제의 대부분은 따옴표와 콤마, 그리고 목록을 가짜 객체로 써버리는 데서 나옵니다.

하나: JSON 에 컨테이너는 두 가지뿐이다

API 가 아무리 복잡한 데이터를 반환해도, 끝까지 분해하면 두 가지 컨테이너와 여섯 종류의 값에 도달합니다. 객체(object)는 "키-값 쌍"의 집합으로 중괄호 {} 로 감싸고, 배열(array)은 순서대로 나열된 값의 목록으로 대괄호 [] 로 감쌉니다. 값은 문자열, 숫자, true/false, null 이 될 수 있고, 객체나 배열을 다시 중첩할 수도 있습니다. 객체 안에 배열, 배열 안에 객체 — 이 조합만으로 현실의 모든 데이터가 표현됩니다.

{
  "user": { "name": "Ada", "active": true },
  "roles": ["admin", "editor"],
  "lastLogin": null,
  "loginCount": 42
}

이 인식은 실무에서 유용합니다. 이해하기 어려운 JSON 을 만났을 때 첫 글자부터 읽지 말고, 가장 바깥쪽이 { 인지 [ 인지 먼저 확인하세요. 객체라면 필드로, 배열이라면 목록으로 읽고 한 겹씩 안으로 내려가면 구조를 파악할 수 있습니다. json.org 의 문법 다이어그램이 한 페이지에 담기는 이유도 바로 이것입니다. 두 구조와 재귀적 중첩만으로 표현력이 충분하기 때문입니다.

둘: 객체 작성법, 네 가지 엄격한 규칙

객체는 초보자의 오류가 가장 많이 집중되는 곳이지만, 규칙은 사실상 네 가지입니다.

  1. 키는 반드시 큰따옴표 문자열. {name: "Ada"} 도 {'name': 'Ada'} 도 올바르지 않으며, {"name": "Ada"} 로 써야 합니다. JavaScript 객체 리터럴은 벗겨진 키와 작은따옴표를 허용하지만 JSON 은 허용하지 않습니다. 두 것을 혼동하는 가장 흔한 지점입니다.
  2. 쌍 사이는 콤마로 구분하고, 마지막 쌍 뒤에는 콤마를 두지 않는다. {"a": 1, "b": 2,} 는 닫는 중괄호 위치에서 Unexpected token } 를 냅니다.
  3. 키는 유일해야 한다. RFC 8259 는 MUST 가 아닌 SHOULD 로 표현하며, 중복 키는 오류를 내지 않습니다. 그러나 첫 값을 취할지 마지막 값을 취할지는 파서 구현에 따라 달라지고, 언어마다 결과가 다를 수 있으므로 의존해서는 안 됩니다.
  4. 키의 순서에는 의미가 없다. {"a":1,"b":2} 와 {"b":2,"a":1} 은 같은 객체입니다. diff 도구와 비교 함수 모두 키 순서를 무시합니다. 순서가 필요한 데이터는 배열에 넣어야 합니다.

셋: 배열 작성법, 순서 자체가 데이터다

배열은 위치로 값을 저장하고 인덱스는 0 부터 시작합니다. ["admin", "editor"] 에서 "editor" 는 [1] 입니다. "순서에 의미가 있다"는 것이 배열과 객체의 본질적 차이입니다. 관련도 순으로 정렬된 검색 결과, 시간순 정렬된 조작 로그 — 이런 정보는 순서 안에만 존재하며, 객체로 바꾸는 순간 사라집니다.

실용적인 조언 두 가지. 첫째, 배열 요소는 가능한 한 동형으로 맞춥니다. [{"id":1},{"id":2}] 는 [1, "text", true] 보다 훨씬 다루기 쉽고, 후자는 문법상 올바르지만 소비 측 코드는 매 단계 형식 분기를 작성해야 합니다. 둘째, 빈 배열 [] 은 완전히 합법적인 값입니다. 목록형 필드에 아직 내용이 없을 때 null 대신 [] 을 반환하면, 소비자는 "존재하는가" 확인과 "비어 있는가" 확인을 한 번에 마칠 수 있습니다.

[
  { "city": "Tokyo", "population": 13960000 },
  { "city": "Delhi", "population": 16780000 }
]

넷: 중첩, 실제 API 의 네 가지 모양

실제 데이터는 두 컨테이너의 상호 중첩이며, 패턴은 대체로 네 가지로 수렴합니다.

모양 생김새 전형적인 상황
객체가 배열을 품는 형태 {"tags": ["a","b"]} 엔티티의 목록형 필드
배열이 객체를 품는 형태 [{"id":1},{"id":2}] 레코드 목록, 페이지네이션 결과
객체가 객체를 품는 형태 {"db": {"host": "..."}} 그룹화된 설정, 주소 정보
배열이 배열을 품는 형태 [[1,2],[3,4]] 행렬, 표의 행

전형적인 API 응답은 "껍데기는 객체, 내용물은 배열"의 형태를 취합니다.

{
  "code": 0,
  "data": {
    "items": [
      { "id": 1, "title": "first" },
      { "id": 2, "title": "second" }
    ],
    "page": 1,
    "total": 2
  }
}

중첩은 깊이를 자랑하기 위해 늘리는 것이 아닙니다. 삼사 층을 넘기면 값 접근 경로를 읽기 어려워지고, 소비 측 코드도 함께 비대해집니다. 항상 함께 나타나는 필드는 하위 객체로 묶어야 합니다. 예컨대 addrCity 와 addrZip 을 address: {city, zip} 으로 바꾸는 식입니다.

다섯: 객체인가 배열인가, 의사결정 표

질문 답 이유
모든 값에 이름이 있는가 객체 키로 조회하며, 필드 추가·삭제가 구조를 깨지 않는다
같은 종류 레코드의 나열인가 배열 순서에 의미가 있고 map/filter 할 수 있다
키로 빠르게 찾아야 하는가 키를 색인으로 삼은 객체 O(1) 직접 접근, 순회 불필요
하나의 실체의 여러 속성인가 객체 속성 사이에는 순서가 없다
추가·삭제되는 동질 항목인가 배열 길이가 자유롭게 늘어난다

하나의 안티패턴을 특별히 언급합니다. "0", "1", "2" 같은 연속 숫자 키를 가진 객체로 배열을 흉내 내는 방식입니다. 오류는 나지 않지만, 배열의 길이 의미와 반복 도구를 잃고, 소비 측은 Object.keys 를 정렬한 뒤 값을 꺼내는 부가 작업을 감당해야 합니다. 키가 연속 번호라면 그냥 배열로 쓰세요. 반대로 [{"key":"theme","value":"dark"}] 같은 키-값 쌍 목록은, 키가 동적이어서 사전에 선언할 수 없는 경우가 아니라면 객체 {"theme": "dark"} 이 더 낫습니다.

여섯: 세 가지 흔한 오류와 오류 메시지 대조

잘못된 표기 전형적인 오류 수정 방법
트레일링 콤마 {"a":1,} Unexpected token } 마지막 콤마 삭제
작은따옴표·벗겨진 키 {name:'Ada'} Unexpected token ' / Expected property name 키와 문자열 모두 큰따옴표로 통일
Python 리터럴 True/None Unexpected token T true/null 로 교체
숫자 키 가짜 배열 오류 없음, 의미 오류 진짜 배열로 재작성

위치 파악 요령 두 가지. 파서가 보고하는 위치는 보통 문제 문자의 뒤입니다. position 42 를 보면 한두 문자 거슬러 확인하세요. 또 한 줄로 붙은 큰 JSON 은 포매터로 줄바꿈을 한 뒤 찾는 것이 좋습니다. 행·열 번호는 문자 오프셋보다 훨씬 직관적입니다. 오류 메시지의 전체 역인조 표는 JSON 오류 메시지 역조회에, 단계별 점검 흐름은 JSON 파싱 오류 수정법에 정리되어 있습니다.

일곱: 쓴 다음에는 구조를 한 번 검증한다

직접 작성한 JSON 은 납품 전에 반드시 파서를 통과시켜야 합니다. 가장 가벼운 검증은 명령줄입니다.

python3 -m json.tool config.json > /dev/null && echo OK
jq empty config.json && echo OK

온라인에서는 내용을 JSON 포맷터 페이지에 붙여 넣으세요. 구문 오류는 행·열 위치와 함께 표시됩니다. 트리 뷰로 전환하면 각 층의 자료형이 한눈에 보여, 숫자가 문자열로 취급되지 않았는지, 배열 길이가 기대와 맞는지 확인할 수 있습니다. 비개발자에게 보여줘야 한다면, 배열 안에 객체가 담긴 구조는 JSON to 표 페이지에서 행과 열로 펼칠 수 있고, "이 데이터가 정돈된 레코드 목록인가" 검증도 동시에 끝납니다.

어떤 필드를 배열로 할지, 깊어진 중첩을 어떻게 재구성할지 같은 구조적 질문은 형식 모델링의 영역이며, 후속 내용은 여섯 가지 타입·숫자 정밀도와 인코딩 함정에 있습니다.

JSON 배열과 객체는 서로 변환할 수 있나요?

가능하지만 대등하지 않습니다. 객체를 배열로 바꾸면 보통 키가 값으로 변하며 키 기반 조회의 편의를 잃습니다. 배열을 객체로 바꾸려면 각 요소에 키를 만들어야 하는데, 그 키를 어디서 얻을지가 새로운 설계 문제입니다. 문법적인 이동만을 목적으로 하지 말고, 소비 측이 데이터를 어떻게 읽을지 먼저 정하세요.

객체의 키는 중복될 수 있나요?

문법상 가능합니다. RFC 8259 는 유일해야 한다(SHOULD)고만 말합니다. 그러나 JavaScript 는 마지막 값을 취하고 C 계열 일부 라이브러리는 첫 값을 취하는 등 동작이 일치하지 않습니다. 서명, diff, 해시 계산에서는 중복 키가 곧바로 결과 불일치를 만듭니다. 생성 측에서는 중복을 피하고, 소비 측에서는 출처를 알 수 없는 데이터를 신뢰할 수 없는 입력으로 다뤄야 합니다.

배열에 다른 타입의 값을 넣을 수 있나요?

문법상 가능하고 [1, "a", true] 는 합법적인 JSON 입니다. 그러나 이형 배열은 소비 측 코드가 모든 위치에서 타입 판정을 하도록 강제하고, Schema 로도 표현이 어렵습니다. 행렬이나 튜플처럼 위치 자체가 의미인 경우를 제외하면, 배열은 동형을 유지하는 것이 현명합니다.

{name:'json'} 이 검증을 통과하지 못하는 이유는?

JSON 은 키와 문자열 값 모두에 큰따옴표를 요구하기 때문입니다. {name:'json'} 은 JavaScript 객체 리터럴이지 JSON 이 아닙니다. {"name": "json"} 으로 고치면 검증을 통과합니다. 작은따옴표, 벗겨진 키, 주석을 허용하는 표기는 JSON5/JSONC 방언에 속하며, 표준 JSON.parse 가 아니라 전용 파서로 읽어야 합니다.