From aa48bead0dca1f7ea5bb716598dfeab9c9bc27d1 Mon Sep 17 00:00:00 2001
From: "Henry H. Andrews" <andrews_henry@yahoo.com>
Date: Mon, 9 Jun 2025 10:49:29 -0700
Subject: [PATCH 1/2] Example Object example updates

---
 src/oas.md | 143 +++++++++++++++++++++++------------------------------
 1 file changed, 63 insertions(+), 80 deletions(-)

diff --git a/src/oas.md b/src/oas.md
index 3df5572368..56dc93a5e7 100644
--- a/src/oas.md
+++ b/src/oas.md
@@ -2128,100 +2128,83 @@ With the Example Object, such values can alternatively be handled through the `e
 
 ##### Example Object Examples
 
-In a request body:
+###### JSON Examples
 
-```yaml
-requestBody:
-  content:
-    'application/json':
-      schema:
-        $ref: '#/components/schemas/Address'
-      examples:
-        foo:
-          summary: A foo example
-          value:
-            foo: bar
-        bar:
-          summary: A bar example
-          value:
-            bar: baz
-    application/xml:
-      examples:
-        xmlExample:
-          summary: This is an example in XML
-          externalValue: https://example.org/examples/address-example.xml
-    text/plain:
-      examples:
-        textExample:
-          summary: This is a text example
-          externalValue: https://foo.bar/examples/address-example.txt
-```
-
-In a parameter:
+When writing in YAML, JSON syntax can be used for `dataValue` (as shown in the `noRating` example) but is not required.
+While this example shows the behavior of both `dataValue` and `serializedValue` for JSON (in the 'withRating` example), in most cases only the data form is needed.
 
 ```yaml
-parameters:
-  - name: zipCode
-    in: query
+content:
+  application/json:
     schema:
-      type: string
-      format: zip-code
+      type: object
+      required:
+      - author
+      - title
+      properties:
+        author:
+          type: string
+        title:
+          type: string
+        rating:
+          type: number
+          minimum: 1
+          maximum: 5
+          multipleOf: 0.5
     examples:
-      zip-example:
-        $ref: '#/components/examples/zip-example'
-```
-
-In a response:
+      noRating:
+        summary: A not-yet-rated work
+        dataValue: {
+          "author": "A. Writer",
+          "title": "The Newest Book"
+        }
+      withRating:
+        summary: A work with an average rating of 4.5 stars
+        dataValue:
+          author: A. Writer
+          title: An Older Book
+          rating: 4.5
+        serializedValue: |
+          {
+            "author": "A. Writer",
+            "title": "An Older Book",
+            "rating": 4.5
+          }
+```
+
+###### Binary Examples
+
+This example shows both `externalDataValue` and `externalSerializedValue` to emphasize that no encoding is taking place, but it is also valid to show only one or the other.
 
 ```yaml
-responses:
-  '200':
-    description: your car appointment has been booked
-    content:
-      application/json:
-        schema:
-          $ref: '#/components/schemas/SuccessResponse'
-        examples:
-          confirmation-success:
-            $ref: '#/components/examples/confirmation-success'
-```
-
-Two different uses of JSON strings:
-
-First, a request or response body that is just a JSON string (not an object containing a string):
-
-```yaml
-application/json:
-  schema:
-    type: string
-  examples:
-    jsonBody:
-      description: 'A body of just the JSON string "json"'
-      value: json
+content:
+  image/png:
+    schema: {}
+    examples:
+      Red:
+        externalDataValue: ./examples/2-by-2-red-pixels.png
+        serializedDataValue: ./examples/2-by-2-red-pixels.png
 ```
 
-In the above example, we can just show the JSON string (or any JSON value) as-is, rather than stuffing a serialized JSON value into a JSON string, which would have looked like `"\"json\""`.
+###### Boolean Query Parameter Examples
 
-In contrast, a JSON string encoded inside of a URL-style form body:
+Since there is no standard for serializing boolean values (as discussed in [Appendix B](#appendix-b-data-type-conversion)), this example uses `dataValue` and `serializedValue` to show how booleans are serialized for this particular parameter:
 
 ```yaml
-application/x-www-form-urlencoded:
-  schema:
-    type: object
-    properties:
-      jsonValue:
-        type: string
-  encoding:
-    jsonValue:
-      contentType: application/json
-  examples:
-    jsonFormValue:
-      description: 'The JSON string "json" as a form value'
-      value: jsonValue=%22json%22
+name: flag
+in: query
+required: true
+schema:
+  type: boolean
+examples:
+  "true":
+    dataValue: true
+    serializedValue: flag=true
+  "false":
+    dataValue: false
+    serializedValue: flag=false
 ```
 
-In this example, the JSON string had to be serialized before encoding it into the URL form value, so the example includes the quotation marks that are part of the JSON serialization, which are then URL percent-encoded.
-
 #### Link Object
 
 The Link Object represents a possible design-time link for a response.

From f05df35833c3b592b6575bcf83242cf1031475e5 Mon Sep 17 00:00:00 2001
From: "Henry H. Andrews" <andrews_henry@yahoo.com>
Date: Wed, 11 Jun 2025 18:30:45 -0700
Subject: [PATCH 2/2] Don't use `externalDataValue` for binary

---
 src/oas.md | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/src/oas.md b/src/oas.md
index 56dc93a5e7..47d9a16913 100644
--- a/src/oas.md
+++ b/src/oas.md
@@ -2174,7 +2174,7 @@ content:
 
 ###### Binary Examples
 
-This example shows both `externalDataValue` and `externalSerializedValue` to emphasize that no encoding is taking place, but it is also valid to show only one or the other.
+Fully binary data is shown using `serializedDataValue`:
 
 ```yaml
 content:
@@ -2182,7 +2182,6 @@ content:
     schema: {}
     examples:
       Red:
-        externalDataValue: ./examples/2-by-2-red-pixels.png
         serializedDataValue: ./examples/2-by-2-red-pixels.png
 ```