From b690c9de08580f08b6c53e795d3178419a50ec7d Mon Sep 17 00:00:00 2001
From: Mark Larah <mark@larah.me>
Date: Thu, 30 Apr 2026 02:00:56 -0500
Subject: [PATCH 1/4] Specify list mock semantics

---
 GAP-0/DRAFT.md | 38 ++++++++++++++++++++++++++++++++++++--
 1 file changed, 36 insertions(+), 2 deletions(-)

diff --git a/GAP-0/DRAFT.md b/GAP-0/DRAFT.md
index 72301c7..9716785 100644
--- a/GAP-0/DRAFT.md
+++ b/GAP-0/DRAFT.md
@@ -148,6 +148,26 @@ If `@mock` is applied to an operation definition (e.g. {"query"}), the entire
 response must be resolved from a _mock file_. No request should be sent to the
 server.
 
+When `@mock` is applied to a field selected beneath a list-typed field, the
+same _mock value_ is inserted into each corresponding item in the list. To
+represent distinct values for different list items, apply `@mock` to the
+list-typed field or to an enclosing field, and provide the list as part of the
+_mock value_.
+
+For example, this query inserts the same {"blurHash"} value for each item in
+{"menuItems"}:
+
+```graphql example
+query GetMenuItemPhotos {
+  business(id: "123") {
+    menuItems {
+      name
+      blurHash @mock(value: "LEHV6nWB2yk8pyo0adR*.7kCMdnj")
+    }
+  }
+}
+```
+
 **Example**
 
 The resulting operation that may be sent to a server as a result of applying all
@@ -271,8 +291,8 @@ A *mock variant* object may contain **only** the following keys:
 
 #### data
 
-:: {"data"} stores the *mock value*. It may be a scalar, object, or `null`,
-depending on what in the operation is being mocked.
+:: {"data"} stores the *mock value*. It may be a scalar, object, array, or
+`null`, depending on what in the operation is being mocked.
 
 The client inserts {"data"} directly under the {"data"} key of the operation's
 response — it must not be nested inside an additional {"data"} entry.
@@ -312,6 +332,20 @@ Not this:
 }
 ```
 
+For a list-typed field, {"data"} contains the list value directly:
+
+```json example
+{
+  "breakfast-menu": {
+    "data": [
+      { "name": "Pancakes", "price": "$8.00" },
+      { "name": "Waffles", "price": "$9.00" }
+    ],
+    "__path__": "business.menuItems"
+  }
+}
+```
+
 #### errors
 
 {"errors"} may contain an array of error objects conforming to the

From a4a98e900c923d17bdf6c2c59beb8a4e3cf1c784 Mon Sep 17 00:00:00 2001
From: Mark Larah <mark@larah.me>
Date: Thu, 30 Apr 2026 02:23:28 -0500
Subject: [PATCH 2/4] Update mock value for blurHash in GetMenuItemPhotos query

---
 GAP-0/DRAFT.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/GAP-0/DRAFT.md b/GAP-0/DRAFT.md
index 9716785..64f0adf 100644
--- a/GAP-0/DRAFT.md
+++ b/GAP-0/DRAFT.md
@@ -162,7 +162,7 @@ query GetMenuItemPhotos {
   business(id: "123") {
     menuItems {
       name
-      blurHash @mock(value: "LEHV6nWB2yk8pyo0adR*.7kCMdnj")
+      blurHash @mock(value: "L15hfK~ot5NL$_?GRjIV?vW?M{RP")
     }
   }
 }

From e3168cc87b2322175413d26ca43159d81acb88ac Mon Sep 17 00:00:00 2001
From: Mark Larah <mark@larah.me>
Date: Thu, 30 Apr 2026 02:33:47 -0500
Subject: [PATCH 3/4] Update DRAFT.md

---
 GAP-0/DRAFT.md | 40 ++++++++++++++++++++--------------------
 1 file changed, 20 insertions(+), 20 deletions(-)

diff --git a/GAP-0/DRAFT.md b/GAP-0/DRAFT.md
index 64f0adf..448676d 100644
--- a/GAP-0/DRAFT.md
+++ b/GAP-0/DRAFT.md
@@ -148,26 +148,6 @@ If `@mock` is applied to an operation definition (e.g. {"query"}), the entire
 response must be resolved from a _mock file_. No request should be sent to the
 server.
 
-When `@mock` is applied to a field selected beneath a list-typed field, the
-same _mock value_ is inserted into each corresponding item in the list. To
-represent distinct values for different list items, apply `@mock` to the
-list-typed field or to an enclosing field, and provide the list as part of the
-_mock value_.
-
-For example, this query inserts the same {"blurHash"} value for each item in
-{"menuItems"}:
-
-```graphql example
-query GetMenuItemPhotos {
-  business(id: "123") {
-    menuItems {
-      name
-      blurHash @mock(value: "L15hfK~ot5NL$_?GRjIV?vW?M{RP")
-    }
-  }
-}
-```
-
 **Example**
 
 The resulting operation that may be sent to a server as a result of applying all
@@ -231,6 +211,26 @@ TransformOperation(document, selectionSet) :
         remove it.
   1. Return {document}.
 
+**Lists**
+
+When `@mock` is applied to a selection which is a child of a list type, the
+client inserts the same _mock value_ in each corresponding array element in
+the repsonse.
+
+For example, this query inserts the same {"blurHash"} value for each item in
+{"menuItems"}:
+
+```graphql example
+query GetMenuItemPhotos {
+  business(id: "123") {
+    menuItems {
+      name
+      blurHash @mock(value: "L15hfK~ot5NL$_?GRjIV?vW?M{RP")
+    }
+  }
+}
+```
+
 # Mock Files
 
 :: A *mock file* is a `.json` file that maps each *mock variant id* to a

From 6a784ca1d871e88edb09280417d805822b46fb9a Mon Sep 17 00:00:00 2001
From: Mark Larah <mark@larah.me>
Date: Thu, 30 Apr 2026 02:52:29 -0500
Subject: [PATCH 4/4] Update DRAFT.md

---
 GAP-0/DRAFT.md | 29 ++++++-----------------------
 1 file changed, 6 insertions(+), 23 deletions(-)

diff --git a/GAP-0/DRAFT.md b/GAP-0/DRAFT.md
index 448676d..76ae88f 100644
--- a/GAP-0/DRAFT.md
+++ b/GAP-0/DRAFT.md
@@ -294,27 +294,9 @@ A *mock variant* object may contain **only** the following keys:
 :: {"data"} stores the *mock value*. It may be a scalar, object, array, or
 `null`, depending on what in the operation is being mocked.
 
-The client inserts {"data"} directly under the {"data"} key of the operation's
-response — it must not be nested inside an additional {"data"} entry.
-
-For example, when `@mock` is applied to an operation root, the *mock variant*
-should look like this:
-
-```json example
-{
-  "mock-id": {
-    "data": {
-      "business": {
-        "name": "The Great British Bakery",
-        "rating": 5.0
-      }
-    },
-    "__path__": "Query"
-  }
-}
-```
-
-Not this:
+The client merges {"data"} directly into the {"data"} field of the operation's
+response — it must not be nested inside an additional {"data"} entry in the
+_mock variant_:
 
 ```json counter-example
 {
@@ -332,11 +314,12 @@ Not this:
 }
 ```
 
-For a list-typed field, {"data"} contains the list value directly:
+When applying `@mock` to a field that returns a list type, {"data"} contains the
+list value directly:
 
 ```json example
 {
-  "breakfast-menu": {
+  "menu-items": {
     "data": [
       { "name": "Pancakes", "price": "$8.00" },
       { "name": "Waffles", "price": "$9.00" }
