JSON

프로그램 안에서 데이터는 서랍처럼 겹쳐 있습니다. 문서 하나에 제목이 있고 작성자가 있고 그 작성자 아래에 이름과 메일 주소가 또 들어 있는 식입니다. 그런데 이걸 다른 프로그램에 보내려면 한 줄짜리 글자로 눌러 담았다가 받는 쪽에서 다시 펴야 합니다. 눌러 담는 규칙을 양쪽이 똑같이 알고 있어야 하는데, 한동안은 그 규칙을 회사마다 자기 방식으로 만들었습니다.

그래서 연동 문서에 이런 문장이 실렸습니다. 첫 줄은 건너뛰고, 쉼표로 자른 다음 세 번째 칸이 금액이고, 금액이 비면 칸 자체가 없으니 그때는 네 번째 칸을 세 번째로 세라는 식입니다. 상대가 규칙을 조금 바꾸면 그쪽 연동만 조용히 깨졌고, 새 업체가 붙을 때마다 읽는 코드를 처음부터 새로 짰습니다.

앞서 나온 공용 형식은 XML 이었습니다. 값마다 여는 표시와 닫는 표시로 감싸는 방식이라 구조는 분명해졌지만, 같은 내용을 담는 데 글자가 두 배 가까이 들고 눈으로 훑기도 힘들었습니다. JSON 은 그 자리를 이어받으면서 표시를 기호 몇 개로 줄였습니다. 규칙이 적어 배우는 데 10분이면 충분하고, 받은 값을 그대로 화면에 띄워 놓고 어디가 잘못됐는지 사람이 찾을 수 있다는 점이 퍼진 이유입니다.

겹쳐 있는 구조를 잃지 않으면서 글자로만 적는 문제를 풉니다. 쓰는 기호는 넷뿐입니다.

1. 중괄호는 이름과 값의 묶음을 만듭니다. 이름은 큰따옴표로 감싸고 쌍점 뒤에 값을 적습니다.
2. 대괄호는 같은 종류가 여러 개 늘어선 목록을 만듭니다.
3. 값 자리에는 글자·숫자·참거짓·빈값이 들어갑니다. 글자만 큰따옴표로 감싸고 숫자는 그대로 적습니다.
4. 값 자리에 다시 중괄호나 대괄호를 넣어 몇 겹이든 겹칠 수 있습니다.

문서 하나를 적으면 이렇게 됩니다.

{
  "id": 1024,
  "title": "9월 정기 회의록",
  "done": true,
  "author": { "name": "지현", "email": "mia@pagedeck.io" },
  "tags": ["회의", "9월"]
}

여기서 두 번째 문제가 같이 풀립니다. 사람이 그대로 읽을 수 있다는 점입니다. 결제가 실패했을 때 태오는 오간 본문을 로그에서 꺼내 눈으로 봅니다. 금액 칸이 빈 글자로 왔는지, 아예 칸이 없는지를 그 자리에서 가릅니다. 기계만 읽는 형식이었다면 그 확인에 별도 도구를 붙여야 합니다.

세 번째는 언어를 가리지 않는다는 점입니다. 이름에 자바스크립트가 들어 있지만 규격 자체는 어느 언어에도 매여 있지 않습니다. 서버가 파이썬이고 앱이 스위프트여도 양쪽 모두 한 줄로 읽고 쓰는 기능을 기본으로 갖고 있습니다.

그래서 API 로 오가는 본문, 곧 페이로드 자리의 기본값이 됐습니다. REST 방식이든 GraphQL 방식이든 실려 오는 글자는 대개 JSON 입니다.

용도에 따라 다른 형식이 여전히 쓰입니다. 넷이 대표적입니다.

1. XML — 값마다 이름표로 감싸는 형식입니다. 문서 안에 서식과 주석을 함께 담을 수 있어 금융·공공 기관 연동에는 지금도 남아 있습니다. 대신 같은 내용이 훨씬 길어집니다.
2. CSV — 쉼표로 칸을 나눈 표 형식입니다. 줄이 수십만 개인 매출 자료처럼 칸 구성이 고정된 데이터에 가볍고 빠릅니다. 겹친 구조는 담지 못합니다.
3. YAML — 들여쓰기로 구조를 나타내 기호가 거의 없습니다. 사람이 손으로 쓰고 고치는 설정 파일에 주로 씁니다. 빈칸 하나에 뜻이 달라져 주고받는 용도에는 위태롭습니다.
4. 프로토콜 버퍼 — 사람이 못 읽는 대신 크기가 작고 해석이 빠른 기계용 형식입니다. 서버끼리 초당 수만 번 주고받는 구간에 씁니다.

JSON 자체의 약점도 분명합니다. 주석을 달 수 없어서 설정 파일로 쓰면 각 칸이 무슨 뜻인지 옆에 적어 둘 자리가 없습니다. 날짜를 나타내는 칸이 따로 없어 글자로 적고 양쪽이 형식을 따로 합의해야 합니다. 그리고 이름을 매 줄 반복해 적으므로 같은 내용을 프로토콜 버퍼보다 서너 배 크게 실어 나릅니다.

"응답에서 amount 가 글자로 오는데 숫자로 바꿔 주실 수 있어요?"

받는 쪽에서 계산에 바로 못 쓰니 큰따옴표를 빼 달라는 요청입니다.

"본문이 JSON 이 아니라서 400 이 떨어지는 거예요."

서버가 기대한 형식과 실제로 보낸 형식이 달라 요청이 문턱에서 거절됐다는 뜻입니다.

"이건 JSON 이라 주석을 못 달아요. 설명은 문서에 적을게요."

파일 안에 설명을 남길 자리가 없으니 다른 곳에 적어 두겠다는 말입니다.

페이지덱이 결제 업체와 연동하던 주의 장면입니다. 태오가 결제 승인 응답을 받아 보니 금액 칸이 큰따옴표에 싸여 왔습니다. 문서에는 숫자라고 적혀 있었습니다. 태오는 응답 본문을 그대로 붙여 넣어 업체에 보냈고, 업체는 특정 통화에서만 글자로 나간다는 사실을 그날 확인했습니다. 오간 것이 사람이 읽을 수 있는 글자였기 때문에 어느 쪽 잘못인지 가리는 데 반나절이 걸리지 않았습니다.

이 확인이 왕복마다 반복되지 않게 하려면 OpenAPI 같은 규격 문서로 각 칸의 종류를 미리 적어 둡니다. JSON 은 모양만 정하고 내용은 정하지 않기 때문입니다.

자바스크립트에서만 쓰는 형식이라고 읽는 경우가 가장 많습니다. 이름에 그 말이 들어 있으니 자연스러운 오해입니다. 실제로는 자바스크립트가 값을 적던 문법에서 모양만 빌려 와 별도 규격으로 떼어 낸 것이고, 지금은 어느 언어에서도 기본 기능으로 읽고 씁니다. 이 오해를 그대로 두면 서버가 자바나 파이썬인 팀이 굳이 다른 형식을 고르고, 나중에 앱이나 웹을 붙일 때 변환하는 층을 하나 더 만들게 됩니다.

JSON 으로 주고받으면 형식이 맞춰진다고 여기는 것도 흔합니다. 양쪽이 같은 규격을 쓰니 그렇게 느끼기 쉽습니다. 하지만 JSON 이 정하는 것은 중괄호와 따옴표를 어떻게 찍느냐까지입니다. 어떤 이름의 칸이 있어야 하는지, 금액이 숫자인지 글자인지, 없어도 되는 칸이 무엇인지는 아무것도 정해 주지 않습니다. 그래서 문법상 완벽한 본문이 오갔는데도 받는 쪽이 계산을 못 하는 상황이 생깁니다. 형식이 맞았다는 말과 약속이 맞았다는 말은 다릅니다.