From ffa189b8858821830c835ce03d8adfdebac6397a Mon Sep 17 00:00:00 2001
From: Ulf Wiger <ulf@wiger.net>
Date: Thu, 14 May 2026 11:32:17 +0200
Subject: [PATCH] Clarify validation example in README

---
 README.md | 26 +++++++++++++++++++++-----
 1 file changed, 21 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 6f3e1db..534bbce 100644
--- a/README.md
+++ b/README.md
@@ -115,13 +115,29 @@ given string value.
 
 In the test schema, we can see the following definition:
 ```json
-"Pubkey": {
-    "type": "string",
-    "x-serialization": {
-        "tags": ["ak", "ct"]
-    }
+        "properties": {
+            "from": {
+                "allOf": [
+                    { "$ref": "#/components/schemas/Pubkey" },
+                    { "x-serialization": {
+                        "tags": ["ak"]
+                    }}
+                ]
+            }
+        }
+...
+    "Pubkey": {
+        "type": "string",
+        "x-serialization": {
+            "tags": ["ak", "ct"]
+        }
 ```
 
 Whenever the validator encounters an `x-...` property mapped to a validator fun,
 this fun is called with the value and the schema part of the property. The return
 value of the fun is ignored, and any normal return is treated as a validation success.
+
+The example illustrates a common pattern in OpenAPI specs, where entity references are
+used extensively. The `Pubkey` data type can have a more general `x-serialization`
+definition, where multiple key types are accepted, whereas a specialized use of the
+type can narrow the scope by accepting only a subset of the possible types.