101 lines
9.2 KiB
Markdown
101 lines
9.2 KiB
Markdown
---
|
|
title: "official-doc / RFC 7396 — JSON Merge Patch"
|
|
source_type: official-doc
|
|
url: https://datatracker.ietf.org/doc/html/rfc7396
|
|
archive_url:
|
|
vendor: IETF
|
|
related_branches: [feature-boundary-validation-mapping-contract]
|
|
related_projects: [ca-skeleton]
|
|
tags: [official-doc, ca-skeleton, api-design, json, merge-patch]
|
|
status: raw
|
|
confidence: high
|
|
created: 2026-05-28
|
|
last_reviewed: 2026-05-28
|
|
---
|
|
|
|
# RFC 7396 — JSON Merge Patch
|
|
|
|
> Layer: `raw/official-docs/` — IETF 공식 표준 RFC의 원문 발췌·출처 기록.
|
|
> 검증된 요약은 `/ingest` 후 `wiki/concepts/`에 `source-summary-template` 형식으로 별도 작성. 원본은 raw에 영구 보관.
|
|
|
|
## Parent / 활용 branch
|
|
|
|
> 이 자료는 혼자 존재하지 않는다. 아래 branch의 구현 결정의 근거로 보관됨.
|
|
|
|
| Branch | 이 자료가 정당화하는 결정 |
|
|
|---|---|
|
|
| [[raw/branch-notes/feature-boundary-validation-mapping-contract]] | PATCH 요청의 request DTO mapper가 `null` vs `absent` vs 빈 문자열을 구분해야 한다는 결정 (블라인드 B2). null = deletion 의 IETF normative semantics 근거 |
|
|
|
|
## 출처 / Source
|
|
|
|
- 원본 URL: https://datatracker.ietf.org/doc/html/rfc7396
|
|
- 평문 텍스트 URL: https://www.rfc-editor.org/rfc/rfc7396.txt
|
|
- 아카이브 URL: (미제공)
|
|
- 저자 / 조직: Paul Hoffman (VPN Consortium), James M. Snell — IETF Standards Track
|
|
- 발행일: October 2014
|
|
- 마지막 확인일: 2026-05-28
|
|
- RFC 번호: 7396 (Obsoletes: 7386)
|
|
- 카테고리: Standards Track, ISSN 2070-1721
|
|
|
|
## 왜 저장했는지 / Why archived
|
|
|
|
`feature-boundary-validation-mapping-contract` branch에서 식별된 블라인드 B2 — PATCH 요청 처리 시 request DTO의 record 기본값으로 mapping하면 `null`이 "삭제 의도"인지 "입력 누락"인지 구분 불가 — 를 정당화하기 위한 IETF normative source. RFC 7396은 JSON Merge Patch에서 `null`이 필드 삭제를 의미한다는 규범적 정의를 담고 있으며, partial-update mapper 설계 시 `null` vs `absent` 구분 정책의 표준 근거가 된다.
|
|
|
|
## 핵심 인용 / Key quotes (verbatim, 5개)
|
|
|
|
> [§1, lines 85-89] "A JSON merge patch document describes changes to be made to a target JSON document using a syntax that closely mimics the document being modified. Recipients of a merge patch document determine the exact set of changes being requested by comparing the content of the provided patch against the current content of the target document."
|
|
|
|
> [§1, lines 90-94] "If the provided merge patch contains members that do not appear within the target, those members are added. If the target does contain the member, the value is replaced. Null values in the merge patch are given special meaning to indicate the removal of existing values in the target."
|
|
|
|
> [§1, lines 137-140] "This design means that merge patch documents are suitable for describing modifications to JSON documents that primarily use objects for their structure and do not make use of explicit null values. The merge patch format is not appropriate for all JSON syntaxes."
|
|
|
|
> [§2, lines 189-193] "There are a few things to note about the function. If the patch is anything other than an object, the result will always be to replace the entire target with the entire patch. Also, it is not possible to patch part of a target that is not an object, such as to replace just some of the values in an array."
|
|
|
|
> [§4 IANA Considerations, line 269] "Subtype name: merge-patch+json"
|
|
|
|
## Claims Extracted / 추출된 주장
|
|
|
|
> 이 자료가 직접 말하는 것만 claim으로 분리한다. 내 프로젝트에 적용한 결론은 여기 쓰지 않는다.
|
|
|
|
| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|
|
|---|---|---|---|---|---|
|
|
| RFC7396-C1 | JSON Merge Patch 문서는 target JSON document에 가해야 할 변경사항을 기술하며, patch와 target을 비교하여 정확한 변경 집합을 결정한다 | [§1] "A JSON merge patch document describes changes to be made to a target JSON document using a syntax that closely mimics the document being modified." | `official-standard` | HTTP PATCH 메서드에서 JSON 부분 업데이트가 필요한 모든 상황 | 특정 서버 프레임워크가 이 시맨틱을 자동으로 처리함을 증명하지 않음 |
|
|
| RFC7396-C2 | merge patch에 존재하는 `null` 값은 target에서 해당 필드를 제거하라는 특별한 의미를 가진다 | [§1] "Null values in the merge patch are given special meaning to indicate the removal of existing values in the target." | `official-standard` | JSON Merge Patch (RFC 7396) 형식을 따르는 모든 PATCH 구현 | `null`이 Spring record의 기본값인 경우처럼, 클라이언트가 명시적으로 `null`을 보내지 않은 경우(absent field)는 이 규칙이 적용되지 않음 |
|
|
| RFC7396-C3 | merge patch 형식은 explicit null 값을 사용하지 않는 객체 구조 위주의 JSON 문서 수정에만 적합하며, 모든 JSON 문법에 적합하지 않다 | [§1] "This design means that merge patch documents are suitable for describing modifications to JSON documents that primarily use objects for their structure and do not make use of explicit null values. The merge patch format is not appropriate for all JSON syntaxes." | `official-standard` | merge patch 형식 선택 시 사전 적합성 판단 | RFC 6902 (JSON Patch) 대비 어느 것을 사용해야 하는지를 직접 권고하지 않음 |
|
|
| RFC7396-C4 | merge patch는 배열의 일부만 변경하는 것이 불가능하며, 객체가 아닌 target에 patch를 적용하면 target 전체가 patch로 교체된다 | [§2] "If the patch is anything other than an object, the result will always be to replace the entire target with the entire patch. Also, it is not possible to patch part of a target that is not an object, such as to replace just some of the values in an array." | `official-standard` | 배열 필드를 부분 수정해야 하는 모든 PATCH 시나리오 | RFC 6902로의 전환이 항상 올바른 대안임을 증명하지 않음 — 추가 평가 필요 |
|
|
| RFC7396-C5 | JSON Merge Patch 문서의 공식 MIME 미디어 타입은 `application/merge-patch+json`이다 | [§4] "Subtype name: merge-patch+json" | `official-standard` | HTTP Content-Type 헤더 및 Accept 협상에서 merge patch 형식 식별 | 특정 서버/클라이언트 라이브러리가 이 미디어 타입을 자동으로 지원함을 보장하지 않음 |
|
|
|
|
## Usage Boundaries / 적용 경계
|
|
|
|
- 이 자료가 직접 증명하는 것:
|
|
- `RFC7396-C2`: IETF normative 기준으로 JSON Merge Patch payload의 `null` 값은 필드 삭제를 의미한다
|
|
- `RFC7396-C1`: merge patch는 patch document를 target과 비교하여 변경 집합을 결정하는 방식이다
|
|
- `RFC7396-C4`: 배열의 일부 원소만 변경하는 용도로는 merge patch가 부적합하다 — 배열 전체가 교체된다
|
|
- `RFC7396-C3`: 명시적 null 값을 데이터 모델에서 사용하는 경우 merge patch 형식 자체가 부적합하다
|
|
- `RFC7396-C5`: `application/merge-patch+json`이 공식 등록된 미디어 타입이다
|
|
|
|
- 이 자료가 증명하지 않는 것:
|
|
- Spring MVC / Spring WebFlux 또는 임의의 프레임워크가 merge patch 시맨틱을 자동으로 처리함
|
|
- request DTO의 Java record 기본값(0, false, "")이 `absent`와 구별되는 방법 — 이는 프레임워크 레벨 구현 문제
|
|
- `Optional<T>` 또는 `@Nullable` 등 Java 타입 레벨에서 absent vs null 구분을 어떻게 표현하는지
|
|
- RFC 6902 (JSON Patch) 사용이 언제 더 적합한지에 대한 직접 권고
|
|
|
|
- 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
|
|
- ca-tmpl/ca-skeleton의 request DTO mapper가 `absent` field(JSON에 키 자체가 없는 경우)와 `null` field를 구분하는 구현 방법 — Java record constructor에서는 두 경우 모두 같은 기본값으로 수렴하므로 별도 처리 필요
|
|
- `Map<String, Object>` 또는 `JsonNode`를 사용한 partial-update command 설계가 ca-tmpl 아키텍처 계약과 충돌하지 않는지
|
|
- Spring의 `HttpMessageConverter` 또는 Jackson `ObjectMapper` 설정으로 absent vs null 구분이 가능한지 확인
|
|
|
|
## 메모 / Notes
|
|
|
|
- RFC 7396은 RFC 7386을 폐기(Obsoletes)함 — 인용 시 반드시 7396 사용
|
|
- Section 1의 예제: `"f": null` 전송 시 target에서 `f` 키 자체가 삭제됨. 이것이 B2 블라인드의 핵심 — Java record mapper가 absent field를 `null`로 채우면 의도치 않게 target 필드가 삭제된다
|
|
- merge patch vs RFC 6902 선택 기준: 배열 원소 개별 조작 또는 null로 실제 값을 설정해야 하는 경우 → RFC 6902 (JSON Patch) 고려 필요. 단, RFC 6902 raw는 별도 보관 필요
|
|
- Appendix A의 test case 표 `{"e":null} + {"a":1} = {"e":null, "a":1}` — 이미 target에 있는 `null` 값은 patch가 건드리지 않는 한 보존됨
|
|
|
|
## Related / 관련
|
|
|
|
- 같은 주제 관련 RFC: RFC 6902 (JSON Patch — 더 표현력이 높은 대안, 배열 원소 조작 가능) — raw 미보관
|
|
- 같은 주제 관련 RFC: RFC 5789 (PATCH Method for HTTP — 이 문서의 normative reference)
|
|
- 이 자료를 인용한 branch: [[raw/branch-notes/feature-boundary-validation-mapping-contract]]
|
|
- 이 자료를 인용한 wiki 요약: (생성 시 추가)
|