Merge pull request 'Clarify validation example in README' (#6) from uw-clarify-readme into master

Reviewed-on: #6

README.md

@@ -115,13 +115,29 @@ given string value.
 
 In the test schema, we can see the following definition:
 ```json
-"Pubkey": {
+        "properties": {
-    "type": "string",
+            "from": {
-    "x-serialization": {
+                "allOf": [
-        "tags": ["ak", "ct"]
+                    { "$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.