JSON이란? 비개발자 사장님을 위한 기초 가이드

안녕하세요, 3Min API 개발을 이끌고 있는 yeonghyeon입니다.

지난 API 편에서 "API는 정해진 주소로 정해진 모양의 메시지를 주고받는 창구"라고 말씀드렸습니다. 그때 메시지의 모양 이야기는 일부러 뒤로 미뤄 두었는데, 오늘이 바로 그 마지막 퍼즐 조각입니다. 그릇(데이터베이스)과 통로(API) 사이를 실제로 오가는 "메시지"의 모양, JSON에 대한 이야기입니다.

오늘 글의 목표는 "문법을 외우기"가 아닙니다. "내 비즈니스의 한 사건을 JSON 한 덩어리로 적어 볼 수 있다"는 감각, 거기까지만 도달하면 충분합니다. 이 감각이 잡히면 앞으로 개발자·AI와 대화할 때 서로의 언어가 한 단계 가까워집니다. 사전지식은 필요 없습니다.

JSON이란 무엇인가

사전적 정의부터 짧게 보겠습니다. 위키백과는 JSON(JavaScript Object Notation)을 "속성-값 쌍과 배열 자료형으로 이루어진, 사람이 읽을 수 있는 텍스트를 사용해 데이터를 표현하는 개방형 표준 포맷"이라고 설명합니다.

한 줄로 정리하면 이렇습니다.

JSON = 시스템끼리 주고받을 데이터를 사람도 눈으로 읽을 수 있게 정해진 방식으로 적어 놓은 텍스트.

시스템끼리 메시지를 주고받는 방법에는 사실 JSON 말고도 XML, YAML, Protocol Buffers처럼 여러 선택지가 있습니다. 그런데 오늘날 웹 API가 압도적으로 JSON을 고르는 이유는 단순합니다. 사람도, 프로그램도 한눈에 이해할 수 있기 때문입니다. 프로그래머가 메모장에 열어도 읽히고, 서버가 파싱해도 빠릅니다. 이 두 가지를 동시에 잘하는 포맷이 흔치 않습니다.

왜 "약속된 모양"이 필요할까

지난 두 편에서 그릇(DB)과 통로(API)라는 도구가 생겼습니다. 그런데 도구가 있다고 해서 데이터가 저절로 흐르는 것은 아닙니다. 창구에 찾아온 사람이 그때그때 다른 종이에 아무 글씨나 적어서 내민다면, 직원은 단 한 건도 처리할 수 없을 것입니다.

그래서 은행은 입금 전표, 출금 전표, 송금 의뢰서처럼 양식을 미리 정해 둡니다. 같은 양식이어야 창구 직원이 빠르게 검증할 수 있고, 기록도 자동으로 남길 수 있습니다. API도 똑같은 이유로 "이 창구로 들어오는 메시지는 이러이러한 모양이어야 합니다"라는 약속을 미리 정해 둡니다. 그 "모양"을 적는 표준 문법이 JSON입니다.

JSON이 정착되기 전에는 시스템마다 메시지 형식을 제각각 정했습니다. 어떤 곳은 쉼표로 구분한 한 줄 텍스트를 썼고, 어떤 곳은 태그로 감싼 XML을 썼고, 어떤 곳은 자체 바이너리 포맷을 만들어 내부 문서로만 공유했습니다. 새 거래처가 생길 때마다 문서를 뒤지고 파싱 코드를 새로 짜야 했습니다. JSON이 사실상 표준이 된 지금은 "JSON으로 주고받읍시다"라는 한마디만으로 대부분의 협업이 시작됩니다.

엑셀로 이해하는 JSON

JSON 문법을 바로 보기 전에, 이미 익숙한 도구인 엑셀에서 출발하겠습니다. 엑셀 시트 한 장을 떠올려 보시기 바랍니다. 맨 위 한 줄은 컬럼 이름(상품명, 수량, 금액…)이고, 그 아래로는 한 줄(로우)이 한 건의 거래를 뜻합니다.

이 구조를 그대로 JSON으로 옮기면 아주 자연스럽게 연결됩니다.

• 엑셀의 컬럼 이름 → JSON의 키(key)
• 엑셀의 한 칸에 들어간 값 → JSON의 값(value)
• 엑셀의 로우 한 줄 → JSON의 객체 하나({})
• 엑셀의 여러 로우 → JSON의 배열([])

예를 들어 주문 시트 한 줄이 아래 표처럼 생겼다고 해보겠습니다.

order_id	product	quantity	amount
A-2026-0001	Château Margaux 2020	2	480000

이 한 줄을 그대로 JSON 객체로 옮기면 다음과 같이 됩니다.

{
  "order_id": "A-2026-0001",
  "product": "Château Margaux 2020",
  "quantity": 2,
  "amount": 480000
}

이름 옆 콜론 하나, 항목 사이 쉼표 하나, 전체를 감싸는 중괄호 한 쌍. 규칙은 딱 이만큼입니다. 이 한 덩어리가 바로 엑셀의 한 줄과 동일한 정보를 담은 JSON 객체입니다.

그럼 엑셀이 있는데 왜 JSON이 따로 필요할까요. 차이는 계층과 가변성 두 가지입니다. 엑셀은 한 칸에 표를 또 넣기 어렵고, 로우마다 컬럼 구성이 달라지면 관리가 금세 망가집니다. 반면 JSON은 값 자리에 또 다른 객체나 배열을 자연스럽게 넣을 수 있고, 주문마다 달라질 수 있는 옵션 항목도 무리 없이 담깁니다. 엑셀이 "평면 장부"라면, JSON은 "필요할 때 폴더처럼 접히는 장부"에 가깝습니다.

와인샵 사장님의 주문서

지난 편 장면을 이어가 보겠습니다. 쇼핑몰에서 새 주문 한 건이 들어옵니다. 매장 POS와 협력 레스토랑도 같은 데이터베이스를 바라보고 있고, 그 사이를 이어주는 통로가 API였습니다. 자, 이 API 창구로 실제로 날아가는 메시지를 한 번 들여다보겠습니다.

쇼핑몰이 와인샵의 주문 생성 API에 이렇게 생긴 JSON 한 덩어리를 보냅니다.

{
  "order_id": "A-2026-0412",
  "customer": {
    "id": "C-00871",
    "name": "Alex",
    "email": "alex@example.com"
  },
  "items": [
    {
      "sku": "WINE-MARGAUX-2020",
      "name": "Château Margaux 2020",
      "quantity": 2,
      "unit_price": 240000
    },
    {
      "sku": "WINE-OPUS-2019",
      "name": "Opus One 2019",
      "quantity": 1,
      "unit_price": 520000
    }
  ],
  "total_amount": 1000000,
  "ordered_at": "2026-04-15T14:23:00+09:00"
}

이 한 덩어리 안에 누가(customer), 무엇을(items), 얼마에(total_amount), 언제(ordered_at) 샀는지가 전부 들어 있습니다. 앞서 말씀드린 "평면이 아니라 접히는 장부"가 무슨 뜻인지 여기서 바로 보이실 겁니다. 고객은 세부 항목(이름, 이메일)을 가진 하나의 덩어리이고, 주문 품목은 두 건짜리 목록입니다. 엑셀이었다면 고객 시트 따로, 주문 시트 따로, 주문상세 시트 따로 관리해야 했을 정보가 봉투 하나에 깔끔하게 들어가 있습니다.

API 창구는 이 봉투를 받자마자 "약속된 모양"에 맞는지 검사합니다. order_id가 비어 있거나, quantity에 숫자가 아닌 값이 들어오거나, customer 안에 email이 없으면 바로 거절합니다. 덕분에 데이터베이스에는 항상 같은 모양으로 주문이 쌓이고, 나중에 통계를 뽑거나 다른 시스템으로 내보낼 때도 헤매지 않게 됩니다.

결제가 끝나면 결제사는 와인샵의 또 다른 창구로 "이 주문의 결제가 성공했습니다"라는 JSON을 되돌려 보냅니다. 이렇게 상대 시스템이 먼저 알려주는 방식을 따로 웹훅이라고 부른다고 지난 편에서 말씀드렸습니다. 웹훅의 본문 역시 JSON입니다. 요청도 JSON, 응답도 JSON, 알림도 JSON. 시스템 사이를 오가는 거의 모든 메시지가 같은 포맷이라는 점이 지금의 인터넷을 이만큼 부드럽게 돌아가게 합니다.

JSON 문법: 키·값·객체·배열

이제 문법을 아주 짧게 정리하겠습니다. JSON이 가진 규칙은 놀랄 만큼 적습니다. 이 네 가지만 알면 99%의 JSON을 읽을 수 있습니다.

1) 키-값 페어 — 가장 작은 단위

가장 기본은 "이름"과 "내용"을 콜론 하나로 묶은 한 쌍입니다. 이름은 반드시 큰따옴표로 감쌉니다.

"product": "Château Margaux 2020"

2) 값의 종류 — 네 가지 기본형 + 두 구조형

값 자리에 올 수 있는 것은 정해져 있습니다.

• 문자열: 큰따옴표로 감싼 글자. 예) "Alex"
• 숫자: 따옴표 없이 그대로. 예) 480000
• 참/거짓: true 또는 false (따옴표 없음)
• 비어 있음: null (값이 아직 없다는 뜻)
• 객체: 중괄호 {} 로 묶은 키-값 모음
• 배열: 대괄호 [] 로 묶은 값의 목록

3) 객체 {} — 키-값들의 묶음

여러 키-값 페어를 쉼표로 이어 붙이고 중괄호로 감싸면 객체 하나가 됩니다. 엑셀의 한 로우가 이 객체 하나에 대응됩니다.

{
  "name": "Alex",
  "email": "alex@example.com",
  "is_member": true
}

4) 배열 [] — 같은 모양의 나열

대괄호 안에 값을 쉼표로 나열하면 배열입니다. 엑셀의 여러 로우가 이 배열 하나에 대응됩니다.

[
  { "sku": "WINE-MARGAUX-2020", "quantity": 2 },
  { "sku": "WINE-OPUS-2019",    "quantity": 1 }
]

그리고 여기가 진짜 중요한 지점입니다. 방금 본 배열의 원소가 다시 객체라는 점을 눈치채셨을 겁니다. 값 자리에는 객체도, 배열도 다시 들어갈 수 있습니다. 이 재귀적 규칙 하나로 JSON은 아무리 복잡한 정보도 담아낼 수 있습니다. 와인샵 주문서처럼 "한 주문 안에 여러 상품이 있고, 각 상품 안에는 이름과 수량과 단가가 있고…"를 표현할 수 있는 이유가 바로 이것입니다.

정리하면 JSON은 "키-값이 기본이고, 그걸 객체로 묶고, 객체를 배열로 나열할 수 있다. 그리고 값 자리에 또 객체·배열이 들어올 수 있다." 이 한 문장이 전부입니다.

JSON은 어디에 쓰이나

와인샵 주문서 바깥에서도 JSON은 이미 우리 일상 깊숙이 들어와 있습니다. 눈에 띄지 않을 뿐입니다.

• 모바일 앱과 서버의 통신: 인스타그램 피드, 배달 앱의 가게 목록, 주식 앱의 시세 — 거의 전부 JSON으로 오갑니다.
• 설정 파일: VS Code 설정, 많은 개발 도구의 환경 파일이 JSON 형태입니다. 사람이 직접 열어 고칠 수 있게 하려고 JSON을 고릅니다.
• 공공데이터·오픈데이터: 정부와 공공기관이 개방하는 데이터 API 상당수가 JSON으로 응답합니다.
• SaaS 연동·웹훅: 결제사, 배송사, 메시지 플랫폼, 이메일 발송 서비스가 보내오는 알림은 전부 JSON 한 덩어리입니다.
• AI·LLM의 구조화 출력: ChatGPT·Claude 같은 모델에 "결과를 JSON으로 주세요"라고 부탁하면 곧바로 쓸 수 있는 형식으로 돌려줍니다. AI와 비즈니스 시스템을 잇는 공용어이기도 합니다.

JSON을 "형식이 자유로운 자료"라고 오해하시면 곤란합니다. 오히려 반대입니다. 채원씨가 먼저 쓴 데이터에도 계획이 필요하다에서 강조한 대로, JSON이 힘을 내려면 "이 엔드포인트의 JSON은 이러이러한 필드를 가진다"는 약속이 사전에 명확해야 합니다. 자유로운 것은 문법이지, 필드 구성이 아닙니다. 이 차이만 기억하시면 JSON을 둘러싼 오해 대부분이 사라집니다.

지금까지의 정리 · 시리즈 마무리

3부작을 한 번에 묶어 보겠습니다.

• 1편 데이터베이스 — 비즈니스 데이터를 같은 모양으로 쌓아 두는 그릇을 만들었습니다.
• 2편 API — 그 그릇에 외부가 안전하게 다가갈 수 있는 통로(창구)를 세웠습니다.
• 3편 JSON — 그 창구를 오가는 메시지의 모양을 정해 두었습니다.

이 세 가지가 갖추어지는 순간, 여러분의 비즈니스는 처음으로 사람 손을 떠나서도 움직이는 시스템의 모습을 가지게 됩니다. 쇼핑몰에서 주문이 들어오면 JSON 한 덩어리로 API 창구를 통해 DB에 쌓이고, 결제사가 JSON 한 덩어리로 결제 결과를 알려오고, 매장 POS가 JSON 한 덩어리로 재고를 차감합니다. 사장님이 주무시는 동안에도 같은 약속 위에서 메시지들이 오갑니다. 자동화라는 말의 실체는 결국 이 세 약속의 조합입니다.

더 중요한 것은, 이 세 개념이 잡히고 나면 앞으로 만날 모든 새로운 용어(GraphQL, 이벤트 스트리밍, MCP, AI 에이전트…)가 이 뼈대 위에 얹히는 변주일 뿐이라는 점입니다. 뼈대가 서면 가지는 금방 따라옵니다.

오늘 바로 해볼 수 있는 것

시리즈 마지막인 만큼, 실습도 앞의 두 편과 이어지게 설계했습니다. 종이와 AI, 그리고 웹브라우저 하나면 충분합니다.

Action 1. 내 비즈니스의 한 사건을 JSON으로 적어 보기

지난 API 편에서 고르셨던 사건(예: 주문 생성, 예약 등록, 문의 접수) 하나를 꺼내 오시기 바랍니다. 거기에 담긴 항목을 그대로 JSON 한 덩어리로 옮겨 보시면 됩니다. 처음에는 평면으로만 적으셔도 좋고, 익숙해지시면 고객·상품처럼 덩어리가 커지는 부분은 객체 안의 객체로 접어 보시기 바랍니다.

{
  "reservation_id": "R-2026-0001",
  "customer": {
    "name": "Alex",
    "phone": "010-xxxx-xxxx"
  },
  "date": "2026-05-12",
  "party_size": 4,
  "note": "창가 자리 선호"
}

이 한 덩어리가 바로 "내 사업의 한 사건"을 시스템이 알아들을 수 있는 모양으로 옮긴 결과입니다. 개발자가 API 스펙을 잡을 때도 똑같은 장면에서 시작합니다.

Action 2. AI와 검증 사이트로 문법 확인하기

Action 1에서 적으신 JSON을 ChatGPT, Claude, Gemini 같은 AI에 붙여 넣고 이렇게 부탁해 보시기 바랍니다.

아래 JSON이 문법적으로 올바른지 검사해 주세요.
오타, 따옴표, 쉼표, 중괄호·대괄호의 짝이 맞는지 지적하고,
비개발자도 이해할 수 있는 말로 고쳐야 할 부분을 알려 주세요.

[여기에 Action 1의 JSON 붙여 넣기]

눈으로 추가 검증을 해보고 싶으시면 JSONLint 같은 공개 검증 사이트에 붙여 넣으시면 됩니다. 초록색 "Valid JSON" 표시가 나오면 문법은 통과입니다. 이 두 단계만 반복하셔도 JSON을 보는 눈이 빠르게 좋아집니다.

Action 3. 내 엔드포인트에서 형식을 깨뜨려 보기

지난 API 편의 퀵스타트를 따라 3Min API에서 첫 엔드포인트를 만드신 분이 계실 겁니다. 오늘은 그 엔드포인트의 상세 페이지로 돌아가서, 같은 엔드포인트에 두 가지 실험을 해보시기 바랍니다.

1. 필드 구조를 바꿔 보기 — 필수 항목을 하나 추가하거나 이름을 바꾼 뒤, 새 JSON 모양으로 호출해 정상적으로 저장되는지 확인해 보시기 바랍니다.
2. 일부러 잘못된 JSON을 보내 보기 — 쉼표를 빼거나, 필수 필드를 비우거나, 숫자 자리에 글자를 넣고 호출해 보시기 바랍니다. API 창구가 어떤 에러로 되돌려주는지 눈으로 확인하는 것이 핵심입니다.

되돌아오는 에러 메시지의 의미와 대처법은 문제 해결 가이드에 정리해 두었습니다. "에러가 나면 당황"이 아니라 "에러 코드를 보고 원인을 좁힌다"로 바뀌는 순간, 여러분은 이미 시스템과 대화하는 언어를 익히신 것입니다.

👉 아직 엔드포인트가 없으시다면 — 3분 퀵스타트

3부작을 마치며 — 어디로 가시겠습니까

여기까지 오시면서 여러분은 세 가지 도구를 손에 넣으셨습니다. 비즈니스의 데이터를 쌓아 두는 그릇, 바깥과 안전하게 드나드는 통로, 그리고 그 통로 위를 오가는 메시지의 모양. 물론 이 세 주제 안에는 훨씬 더 깊은 세부가 있습니다. 그러나 오늘까지의 이해만으로도 여러분의 비즈니스를 IT 생태계 위에서 확장하고, 나아가 AI 시대에 대비할 뼈대는 충분히 갖춰졌습니다. 나머지 세부는 필요한 순간에 그 위로 얹으시면 됩니다.

여기서 "이건 개발자들이 하는 일 아닌가요?"라는 생각이 드실 수 있습니다. 하지만 요즘은 AI 덕분에 개발자와 비개발자의 경계가 예전보다 훨씬 흐려졌습니다. 제가 드리는 권유도 직접 코드를 쓰시라는 뜻이 아니라, IT가 움직이는 핵심 원리를 감각으로 익혀 두시라는 것까지입니다. 이 감각 위에서 좋은 도구들의 힘을 빌려 작은 API를 만들어 보고, 호출해 보고, 에러를 마주하며 고쳐 보는 순환이 시작됩니다. 이 순환이 쌓이면 어느 순간 "내 비즈니스의 이 부분도 자동화할 수 있겠는데"라는 생각이 자연스럽게 떠오릅니다. 이 감각이 바로 비즈니스를 더 넓은 시장으로 밀어내는 출발점입니다.

뼈대가 서고 나면 재미있는 일이 하나 생깁니다. 요즘 많이 들어 보셨을 자동화 도구들, 예를 들어 n8n, Zapier, Make 같은 서비스를 열어 보시면 이들이 모두 API + JSON + DB라는 같은 뼈대 위에서 움직인다는 사실이 한눈에 보이실 겁니다. "구글 시트에 한 줄 추가"는 구글이 제공하는 시트 API를, "지메일로 메일 발송"은 지메일 API를, "드라이브에 파일 업로드"는 드라이브 API를 호출하는 일일 뿐입니다. 이 도구들은 결국 이미 공개된 수많은 API를 JSON으로 엮어 주는 중개자입니다. 뼈대를 아시는 분은 같은 도구를 훨씬 더 주체적으로 쓰실 수 있습니다.

그럼 지금 무엇을 하셔야 할까요. 제 권유는 이렇습니다. 전체 흐름을 대략이라도 이해하셨다면, 바로 작게 적용하고, 실험하고, 부딪혀 보시기 바랍니다. 운영이 커지고 필요가 분명해지는 시점에 자체 시스템을 고민하셔도 늦지 않습니다. 지금은 과거 어느 때보다 작게 시작하기 좋은 시대입니다. 클라우드, 공개 API, LLM, 노코드 도구가 모두 그 시작을 받쳐 주고 있습니다.

AI와 비즈니스의 맞물림에 대한 더 넓은 시각이 필요하시다면, 소규모 비즈니스의 AI 준비 — 데이터, API, 그리고 지금 해야 할 것들이 이어지는 읽을거리로 도움이 되실 겁니다.

그릇, 통로, 메시지. 이 세 개의 약속 위에서 여러분의 비즈니스가 사람 손을 떠나 움직이기 시작합니다. 3부작을 끝까지 따라와 주셔서 고맙습니다.

---

← 이전 편: API란? 비개발자 사장님을 위한 기초 가이드