From 019a7869285dd938b5ec0e719f061261622559a1 Mon Sep 17 00:00:00 2001
From: Yusuke Tsutsumi <yusuke@tsutsumi.io>
Date: Mon, 18 Nov 2024 22:09:14 -0800
Subject: [PATCH] fix(update): add json-merge-patch guidance for HTTP

After offline discussion, it was agreed upon that IETF RFC 7396 (JSON Merge Patch) is the more sensible choice for a partial update on an HTTP+JSON API. The rationale includes:

- can generally be expressed via protobuf field masks.
- aligns with the AEPs usage of resource-oriented guidance.
- aligns with an existing IETF standard, which as already been widely adopted.
---
 aep/general/0134/aep.md.j2   | 5 +++++
 aep/general/example.oas.yaml | 8 ++++----
 2 files changed, 9 insertions(+), 4 deletions(-)

diff --git a/aep/general/0134/aep.md.j2 b/aep/general/0134/aep.md.j2
index d2c75d46..d8e44abf 100644
--- a/aep/general/0134/aep.md.j2
+++ b/aep/general/0134/aep.md.j2
@@ -100,6 +100,11 @@ Update methods implement a common request pattern:
 
 {% sample '../example.oas.yaml', '$.paths./publishers.post.requestBody' %}
 
+- The method **must** adhere to the behavior specified in [IETF RFC 7396 - JSON
+  Merge Patch](https://datatracker.ietf.org/doc/html/rfc7396).
+- The method **must** support MIME types `application/merge-patch+json` to
+  adhere to IETF RFC 7396.
+
 {% endtabs %}
 
 ### Responses
diff --git a/aep/general/example.oas.yaml b/aep/general/example.oas.yaml
index dd36f7e2..e5f856ea 100644
--- a/aep/general/example.oas.yaml
+++ b/aep/general/example.oas.yaml
@@ -202,14 +202,14 @@ paths:
           type: string
       requestBody:
         content:
-          application/json:
+          application/merge-patch+json:
             schema:
               $ref: '#/components/schemas/publisher'
         required: true
       responses:
         '200':
           content:
-            application/json:
+            application/merge-patch+json:
               schema:
                 $ref: '#/components/schemas/publisher'
           description: Successful response
@@ -311,14 +311,14 @@ paths:
           type: string
       requestBody:
         content:
-          application/json:
+          application/merge-patch+json:
             schema:
               $ref: '#/components/schemas/book'
         required: true
       responses:
         '200':
           content:
-            application/json:
+            application/merge-patch+json:
               schema:
                 $ref: '#/components/schemas/book'
           description: Successful response