숏컷 코드

[
  { "id": 1, "name": "Kim" },
  { "id": 2, "name": "Lee" }
]

문법

array는 순서 있는 sequence다 — 위치 자체가 데이터 의미의 일부가 된다

JSON array는 RFC 8259에서 "ordered sequence of values"로 정의됩니다. 즉 같은 요소라도 위치가 다르면 다른 데이터입니다. 이 특성이 object와 가장 큰 차이입니다. object는 key로 값을 찾고 순서에 의미가 없지만, array는 index로 값을 찾고 순서가 의미의 일부입니다. 정렬된 검색 결과, 처리 단계 목록, 좌표 쌍처럼 순서가 데이터의 핵심인 경우라면 object 대신 array가 올바른 선택입니다.

{
  "steps": ["draft", "review", "publish"],
  "user": { "name": "Kim", "role": "editor" }
}

object와 array를 구분하는 기준 — "이름으로 찾는가, 위치로 찾는가"

실무에서 object와 array를 선택하는 혼란은 대부분 접근 방식의 차이를 무시할 때 생깁니다. {"name": "Kim", "email": "kim@example.com"}처럼 각 값에 이름이 붙어야 의미가 분명한 데이터는 object가 맞습니다. ["draft", "review", "publish"]처럼 위치 자체가 의미를 가지거나 동일한 구조의 항목이 반복되는 데이터는 array가 맞습니다. array를 쓰는데 소비자가 "첫 번째 요소가 X"라는 규칙을 외워야 한다면, 그 의미를 object의 key로 명시하는 편이 낫습니다.

타입이 섞인 array는 검증과 소비 코드를 복잡하게 만든다

JSON spec은 array 항목의 타입을 제한하지 않습니다. 문자열, 숫자, object가 한 array 안에 공존할 수 있습니다. 그러나 실제 API와 설정 파일에서 mixed-type array는 소비 측에서 각 항목의 타입을 매번 확인해야 하고, JSON Schema의 items 키워드로 단일 규칙을 적용하기도 어렵습니다. 동일한 구조의 object를 반복하는 homogeneous array가 파싱, 검증, 문서화 모두에서 훨씬 다루기 쉽습니다.

중복 허용 여부와 빈 array는 별도로 설계해야 한다

JSON array는 중복 값과 빈 배열([]) 모두 허용합니다. 중복을 막아야 하는 경우(고유 태그 목록, 권한 목록 등)라면 JSON Schema의 uniqueItems: true를 선언하거나 서버 측 검증으로 보장해야 합니다. 빈 array와 null, 키 부재는 의미가 다릅니다. "tags": []는 태그가 없다는 명시이고, "tags": null은 알 수 없다는 의미이며, 키 자체가 없으면 정보가 전달되지 않은 상태입니다. 이 세 가지를 같은 의미로 처리하면 소비 코드에 묵시적 가정이 쌓입니다.

선택 기준

주의할 점

["draft", { "step": "review" }, 3]

spec상 가능하더라도 이런 mixed-type array는 소비 코드가 각 요소 타입을 계속 분기해야 합니다. 구조가 반복된다면 보통 같은 모양의 object array로 통일하는 편이 낫습니다.