Category Reference

JSON

기초 문법, 문자열과 숫자 규칙, API 구조, JSON Schema 검증까지 JSON의 핵심 흐름을 카드형 레퍼런스로 정리합니다.

Search cards

40 cards

Search titles, summaries, tags, and subcategories.

기초와 문법

8 cards

기초와 문법

JSON이란 무엇인가

JSON이 어떤 목적의 데이터 형식인지와 값 종류, 이식성, API와 설정 파일에서 널리 쓰이는 이유를 정리합니다.

{
  "name": "RefDock",
  "public": true,
  "version": 1,
  "tags": ["docs", "json"],
  "meta": null
}

기초와 문법

values와 literals

JSON이 허용하는 여섯 가지 values와 true, false, null literal의 규칙, 최상위 값 제한을 정리합니다.

[
  "text",
  42,
  true,
  null,
  { "x": 1 },
  [1, 2, 3]
]

기초와 문법

object와 member 규칙

object에서 key는 왜 문자열이어야 하는지, member 구분 규칙, 중복 key의 위험과 순서 해석 주의점을 정리합니다.

{
  "id": 101,
  "title": "JSON Basics",
  "published": true
}

기초와 문법

array와 순서

array가 ordered sequence라는 점, object와 array를 나누는 기준, 섞인 타입 사용 시 주의점을 정리합니다.

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

기초와 문법

string, number, escaping

큰따옴표 string, escape 규칙, 숫자의 선행 0 금지, NaN과 Infinity 불가 같은 JSON 기본 문법 함정을 정리합니다.

{
  "path": "C:\\temp\\data.json",
  "quote": "\"json\"",
  "count": 42,
  "ratio": 3.14,
  "exp": 1e6
}

기초와 문법

Common syntax errors

trailing comma, comment, 작은따옴표, 따옴표 없는 key처럼 자주 보이는 JSON 문법 오류와 비표준 확장 문법과의 혼동을 정리합니다.

흔한 오류 예시
- { "a": 1, }          trailing comma
- { a: 1 }             따옴표 없는 key
- { "a": 'x' }         작은따옴표 문자열
- { "a": 1 } // note   주석

기초와 문법

UTF-8 and Unicode

네트워크로 주고받는 JSON의 UTF-8 규칙, BOM 주의점, Unicode escape와 실제 문자 표현의 차이를 정리합니다.

{
  "lang": "한국어",
  "emoji": "😀",
  "escaped": "\uD83D\uDE00"
}

기초와 문법

comments와 JSON5 경계

표준 JSON에는 주석과 trailing comma가 없고, JSON5·JSONC 같은 확장 문법을 언제 별도 형식으로 다뤄야 하는지 정리합니다.

{
  "name": "refdock",
  "enabled": true
}

파싱과 직렬화

10 cards

파싱과 직렬화

JSON과 JavaScript object literal 차이

JSON과 JavaScript object literal이 비슷해 보여도 key 인용, 주석, trailing comma, undefined 같은 차이가 있다는 점을 정리합니다.

// JavaScript object literal
const obj = {
  user: "Kim",
  active: true,
  note: undefined,
};

// JSON text
const text = '{"user":"Kim","active":true}';

파싱과 직렬화

JSON.parse and JSON.stringify

JavaScript에서 JSON.parse와 JSON.stringify로 문자열과 값을 오가는 기본 흐름, replacer, reviver, 직렬화 제한을 정리합니다.

const text = '{"name":"Kim","score":42}';
const data = JSON.parse(text);

const pretty = JSON.stringify(data, null, 2);

파싱과 직렬화

Lines와 NDJSON

줄 단위 JSON 형식인 JSON Lines와 NDJSON의 구조, 일반 JSON 배열과의 차이, 로그·스트림 처리에서 주의할 점을 정리합니다.

{"id":1,"event":"login"}
{"id":2,"event":"purchase"}
{"id":3,"event":"logout"}

파싱과 직렬화

Canonical JSON과 stable hash

JSON을 서명하거나 hash에 넣을 때 공백, object member 순서, 숫자 표현 차이 때문에 결과가 흔들리는 문제와 canonicalization 기준을 정리합니다.

const a = '{"name":"Kim","id":1}';
const b = '{\n  "id": 1,\n  "name": "Kim"\n}';

// text 자체 hash는 다름
hash(a) !== hash(b);

// 같은 canonicalization 규칙을 적용한 뒤 hash해야 안정적
hash(canonicalize(JSON.parse(a))) === hash(canonicalize(JSON.parse(b)));

파싱과 직렬화

I-JSON 상호운용성 기준

I-JSON이 UTF-8, 중복 member, number 정밀도, 최상위 object 같은 제약을 통해 JSON 교환 안정성을 높이는 방식을 정리합니다.

I-JSON으로 교환 안정성을 높이는 기준

- UTF-8로 인코딩
- object member name은 중복 없이 생성
- 53비트 안전 정수 범위를 넘는 숫자는 string 검토
- timestamp는 명확한 date-time string 사용
- 프로토콜 최상위는 object를 우선 고려

파싱과 직렬화

application/json과 HTTP 전송

HTTP에서 JSON을 보낼 때 Content-Type, Accept, UTF-8, 파싱 오류, 응답 본문 유무를 어떻게 구분해야 하는지 정리합니다.

POST /api/orders HTTP/1.1
Content-Type: application/json
Accept: application/json

{
  "sku": "book-001",
  "quantity": 1
}

파싱과 직렬화

큰 number와 정밀도

JSON number가 문법상 유효해도 언어별 number 타입에서 정밀도가 달라질 수 있는 지점과 string 설계 기준을 정리합니다.

{
  "unsafeId": 9007199254740993,
  "safeId": "9007199254740993",
  "amountMinor": 129900,
  "amountDecimal": "1299.00"
}

파싱과 직렬화

보안과 parser limits

신뢰할 수 없는 JSON을 받을 때 eval 금지, 크기와 depth 제한, schema 검증, prototype pollution 방어를 어떻게 적용할지 정리합니다.

신뢰할 수 없는 JSON 처리
1. Content-Type과 body 크기를 먼저 확인한다
2. JSON parser로 파싱하고 eval은 쓰지 않는다
3. 최대 크기, 중첩 depth, array 길이를 제한한다
4. schema나 명시적 allowlist로 구조를 검증한다
5. __proto__, constructor, prototype 같은 위험 key를 merge 전에 차단한다

파싱과 직렬화

Streaming JSON과 incremental parsing

큰 JSON 문서를 한 번에 메모리에 올리지 않고 처리할 때 streaming parser, 배열 스트리밍, NDJSON을 구분하는 기준을 정리합니다.

전체 parse:
read all -> parse all -> use result

streaming parse:
read chunk -> parse token/event -> process item

파싱과 직렬화

Text Sequences

RFC 7464의 JSON Text Sequences가 RS(0x1E)와 LF로 여러 JSON text를 구분하는 방식과 JSON Lines, JSON 배열과의 차이를 정리합니다.

\x1e{"id":1,"event":"start"}\n
\x1e{"id":2,"event":"stop"}\n

데이터 설계 패턴

8 cards

데이터 설계 패턴

null vs missing

key가 아예 없는 경우와 null이 들어 있는 경우가 왜 다른 의미인지, API와 Schema에서 어떤 차이를 만드는지 정리합니다.

{ "nickname": null }

데이터 설계 패턴

중첩 구조 설계

JSON 데이터를 너무 평평하게도 너무 깊게도 만들지 않기 위한 중첩 구조 설계 기준과 반복 데이터 표현 원칙을 정리합니다.

{
  "user": {
    "id": 1,
    "profile": {
      "name": "Kim",
      "emails": ["a@example.com", "b@example.com"]
    }
  }
}

데이터 설계 패턴

API 응답 구조 설계

JSON API 응답에서 data, meta, error 같은 상위 구조를 어떻게 안정적으로 잡으면 좋은지와 확장성을 정리합니다.

{
  "data": {
    "id": 101,
    "title": "JSON Guide"
  },
  "meta": {
    "requestId": "req_123",
    "version": 1
  }
}

데이터 설계 패턴

Pointer와 JSON Patch

JSON 문서 안의 위치를 가리키는 JSON Pointer와 부분 변경을 전달하는 JSON Patch의 관계, path 문법, 실패 지점을 정리합니다.

[
  { "op": "replace", "path": "/profile/name", "value": "Kim" },
  { "op": "add", "path": "/tags/-", "value": "new" },
  { "op": "remove", "path": "/draft" }
]

데이터 설계 패턴

Merge Patch

JSON Merge Patch가 부분 수정 payload를 원본 문서와 비슷한 모양으로 표현하는 방식, `null` 삭제 규칙, JSON Patch와의 차이를 정리합니다.

PATCH /users/42 HTTP/1.1
Content-Type: application/merge-patch+json

{
  "name": "Kim",
  "profile": {
    "nickname": null
  }
}

데이터 설계 패턴

JSONPath query 기본

JSONPath로 JSON 안의 값을 선택하고 추출할 때 root, selector, filter, 결과 목록을 어떻게 이해해야 하는지 정리합니다.

$                         전체 JSON 값
$.store.book[0].title     첫 번째 책의 title
$['store']['book'][0]     bracket notation
$..title                  모든 descendant의 title
$.store.book[?@.price < 10]

데이터 설계 패턴

date-time 값 표현

JSON에 날짜와 시간을 넣을 때 RFC 3339 문자열, timezone, epoch number, date-only 값을 어떻게 구분해야 하는지 정리합니다.

{
  "createdAt": "2026-05-23T09:30:00Z",
  "birthday": "1995-08-12",
  "expiresAt": "2026-05-23T18:30:00+09:00"
}

데이터 설계 패턴

versioning과 호환성

JSON API와 메시지 포맷을 바꿀 때 additive change, required field, enum 확장, unknown member 처리 기준을 정리합니다.

호환성이 높은 변경
- 새 optional field 추가
- 기존 field 의미 유지
- unknown member 무시 가능
- enum 확장은 소비자 준비 후 진행

호환성이 낮은 변경
- 기존 field 삭제 또는 rename
- optional field를 required로 변경
- value type 변경
- enum 값의 의미 변경

JSON Schema와 검증

14 cards

JSON Schema와 검증

Schema 기본

JSON Schema가 JSON 데이터의 모양과 제약을 기술하는 방식, type과 properties의 역할, instance와 schema 차이를 정리합니다.

{
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "age": { "type": "number" }
  },
  "required": ["name"]
}

JSON Schema와 검증

Required and additionalProperties

properties만 선언해도 필수가 되지 않는 이유와 required, additionalProperties로 object를 닫는 방식의 장단점을 정리합니다.

{
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "email": { "type": "string" }
  },
  "required": ["name", "email"],
  "additionalProperties": false
}

JSON Schema와 검증

array와 enum 제약

JSON Schema에서 array 항목 규칙을 items로 잡는 방법과 enum, const로 허용 값을 제한하는 방식을 정리합니다.

{
  "type": "object",
  "properties": {
    "status": {
      "enum": ["draft", "review", "published"]
    },
    "tags": {
      "type": "array",
      "items": { "type": "string" }
    }
  }
}

JSON Schema와 검증

oneOf, anyOf, allOf

JSON Schema에서 여러 schema를 조합하는 oneOf, anyOf, allOf의 차이와 선택 기준, 자주 생기는 검증 실패를 정리합니다.

{
  "oneOf": [
    {
      "properties": {
        "kind": { "const": "email" },
        "address": { "type": "string" }
      },
      "required": ["kind", "address"]
    },
    {
      "properties": {
        "kind": { "const": "sms" },
        "phone": { "type": "string" }
      },
      "required": ["kind", "phone"]
    }
  ]
}

JSON Schema와 검증

Schema $ref와 $defs

JSON Schema에서 반복되는 schema 조각을 `$defs`에 두고 `$ref`로 참조하는 방식, 내부 참조와 외부 참조의 기준을 정리합니다.

{
  "type": "object",
  "properties": {
    "shippingAddress": { "$ref": "#/$defs/address" },
    "billingAddress": { "$ref": "#/$defs/address" }
  },
  "$defs": {
    "address": {
      "type": "object",
      "properties": {
        "city": { "type": "string" },
        "zip": { "type": "string" }
      },
      "required": ["city", "zip"]
    }
  }
}

JSON Schema와 검증

format, pattern, range 제약

JSON Schema에서 문자열 길이와 정규식, `format`, 숫자 범위와 `multipleOf`를 어떤 기준으로 나누어 쓰는지 정리합니다.

{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "format": "email"
    },
    "code": {
      "type": "string",
      "pattern": "^[A-Z]{3}-[0-9]{4}$"
    },
    "age": {
      "type": "integer",
      "minimum": 0,
      "maximum": 130
    }
  }
}

JSON Schema와 검증

$schema와 dialect

JSON Schema에서 `$schema`가 어떤 draft와 dialect를 가리키고, validator 호환성 문제를 어떻게 줄이는지 정리합니다.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/schemas/user.schema.json",
  "type": "object",
  "properties": {
    "id": { "type": "string" }
  },
  "required": ["id"]
}

JSON Schema와 검증

조건부 JSON Schema

JSON Schema에서 `if`, `then`, `else`, `dependentRequired`, `dependentSchemas`로 값 사이 조건을 표현하는 기준을 정리합니다.

{
  "if": {
    "properties": {
      "country": { "const": "KR" }
    },
    "required": ["country"]
  },
  "then": {
    "required": ["postalCode"]
  },
  "else": {
    "properties": {
      "postalCode": { "type": "string" }
    }
  }
}

JSON Schema와 검증

Schema annotations

JSON Schema의 title, description, default, examples, deprecated, readOnly, writeOnly가 검증이 아니라 설명과 도구 힌트로 쓰이는 방식을 정리합니다.

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "description": "Current workflow state",
      "default": "draft",
      "examples": ["draft", "published"],
      "deprecated": false
    }
  }
}

JSON Schema와 검증

patternProperties와 동적 key

JSON Schema에서 동적으로 정해지는 object key를 patternProperties, propertyNames, additionalProperties로 검증하는 기준을 정리합니다.

{
  "type": "object",
  "patternProperties": {
    "^S_": { "type": "string" },
    "^I_": { "type": "integer" }
  },
  "additionalProperties": false
}

JSON Schema와 검증

prefixItems와 tuple validation

JSON Schema에서 array를 동일 타입 목록으로 볼지, 위치별 의미가 있는 tuple로 볼지 `items`와 `prefixItems` 기준을 정리합니다.

{
  "type": "array",
  "prefixItems": [
    { "type": "number" },
    { "type": "number" },
    { "type": "string" }
  ],
  "items": false
}

JSON Schema와 검증

unevaluatedProperties와 조합 schema

JSON Schema에서 `allOf`, `$ref` 같은 조합 뒤 남은 object member를 제한할 때 `additionalProperties`와 `unevaluatedProperties`를 구분합니다.

{
  "allOf": [
    { "$ref": "#/$defs/baseUser" }
  ],
  "properties": {
    "role": { "type": "string" }
  },
  "unevaluatedProperties": false
}

JSON Schema와 검증

contentEncoding과 media type

JSON Schema에서 문자열 안에 들어 있는 base64, JSON 문자열, 미디어 타입 힌트를 `contentEncoding`, `contentMediaType`, `contentSchema`로 표현하는 기준을 정리합니다.

{
  "type": "string",
  "contentEncoding": "base64",
  "contentMediaType": "image/png"
}

JSON Schema와 검증

$dynamicRef와 $dynamicAnchor

JSON Schema 2020-12의 `$dynamicRef`와 `$dynamicAnchor`가 정적 `$ref`와 달리 평가 중 dynamic scope를 이용해 재귀 schema 확장을 처리하는 방식을 정리합니다.

{
  "$dynamicAnchor": "node",
  "type": "object",
  "properties": {
    "children": {
      "type": "array",
      "items": { "$dynamicRef": "#node" }
    }
  }
}

Loading category cards

Preparing references and filters for this topic. 이 주제의 레퍼런스와 필터를 준비하고 있습니다.

const a = '{"name":"Kim","id":1}'; const b = '{\n "id": 1,\n "name": "Kim"\n}'; // text 자체 hash는 다름 hash(a) !== hash(b); // 같은 canonicalization 규칙을 적용한 뒤 hash해야 안정적 hash(canonicalize(JSON.parse(a))) === hash(canonicalize(JSON.parse(b)));

I-JSON으로 교환 안정성을 높이는 기준 - UTF-8로 인코딩 - object member name은 중복 없이 생성 - 53비트 안전 정수 범위를 넘는 숫자는 string 검토 - timestamp는 명확한 date-time string 사용 - 프로토콜 최상위는 object를 우선 고려

신뢰할 수 없는 JSON 처리 1. Content-Type과 body 크기를 먼저 확인한다 2. JSON parser로 파싱하고 eval은 쓰지 않는다 3. 최대 크기, 중첩 depth, array 길이를 제한한다 4. schema나 명시적 allowlist로 구조를 검증한다 5. __proto__, constructor, prototype 같은 위험 key를 merge 전에 차단한다

$ 전체 JSON 값 $.store.book[0].title 첫 번째 책의 title $['store']['book'][0] bracket notation $..title 모든 descendant의 title $.store.book[?@.price < 10]

호환성이 높은 변경 - 새 optional field 추가 - 기존 field 의미 유지 - unknown member 무시 가능 - enum 확장은 소비자 준비 후 진행 호환성이 낮은 변경 - 기존 field 삭제 또는 rename - optional field를 required로 변경 - value type 변경 - enum 값의 의미 변경

{ "oneOf": [ { "properties": { "kind": { "const": "email" }, "address": { "type": "string" } }, "required": ["kind", "address"] }, { "properties": { "kind": { "const": "sms" }, "phone": { "type": "string" } }, "required": ["kind", "phone"] } ] }

{ "type": "object", "properties": { "shippingAddress": { "$ref": "#/$defs/address" }, "billingAddress": { "$ref": "#/$defs/address" } }, "$defs": { "address": { "type": "object", "properties": { "city": { "type": "string" }, "zip": { "type": "string" } }, "required": ["city", "zip"] } } }

{ "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "code": { "type": "string", "pattern": "^[A-Z]{3}-[0-9]{4}$" }, "age": { "type": "integer", "minimum": 0, "maximum": 130 } } }

{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://example.com/schemas/user.schema.json", "type": "object", "properties": { "id": { "type": "string" } }, "required": ["id"] }

{ "if": { "properties": { "country": { "const": "KR" } }, "required": ["country"] }, "then": { "required": ["postalCode"] }, "else": { "properties": { "postalCode": { "type": "string" } } } }

{ "type": "object", "properties": { "status": { "type": "string", "description": "Current workflow state", "default": "draft", "examples": ["draft", "published"], "deprecated": false } } }