From a4305d46885c6d63a7bde501f062e35bbb1bbd89 Mon Sep 17 00:00:00 2001
From: Ralf Handl <ralf.handl@gmail.com>
Date: Wed, 20 Aug 2025 10:27:03 +0200
Subject: [PATCH] Update README.md

- two bullet lists: schemas for validation and metaschemas
- correct file name for dialect
- correct $id pattern for dialect
- file dependency diagram
---
 src/schemas/validation/README.md | 19 +++++++++++++++++--
 1 file changed, 17 insertions(+), 2 deletions(-)

diff --git a/src/schemas/validation/README.md b/src/schemas/validation/README.md
index 2fdeb6999e..57501dfc51 100644
--- a/src/schemas/validation/README.md
+++ b/src/schemas/validation/README.md
@@ -21,12 +21,27 @@ We are [working on](https://github.com/OAI/OpenAPI-Specification/issues/4152) ho
 There are two schemas to choose from for versions 3.1 and greater, both of which have an `$id` that starts with `https://spec.openapis.org/oas/3.X/` and ends with the iteration date:
 
 * `https://spec.openapis.org/oas/3.X/schema/{date}`, source: `schema.yaml` — A self-contained schema that _does not_ validate Schema Objects beyond `type: [object, boolean]`
-* `https://spec.openapis.org/oas/3.X/meta/{date}`, source: `meta.yaml` — The vocabulary metaschema for OAS 3.X's extensions to draft 2020-12
-* `https://spec.openapis.org/oas/3.X/dialect/base/{date}`, source: `base.yaml` — The dialect metaschema that extends the standard `draft/2020-12` metaschema by adding the OAS "base" vocabulary
 * `https://spec.openapis.org/oas/3.1/schema-base/{date}`, source: `schema-base.yaml` — A schema that combines the self-contained schema and the "base" dialect schema to validate Schema Objects with the dialect; this schema does not allow changing `$schema` or `jsonSchemaDialect` to other dialects
 
+Two metaschemas define the OAS "base" dialect:
+
+* `https://spec.openapis.org/oas/3.X/meta/{date}`, source: `meta.yaml` — The vocabulary metaschema for OAS 3.X's extensions to draft 2020-12
+* `https://spec.openapis.org/oas/3.X/dialect/{date}`, source: `dialect.yaml` — The dialect metaschema that extends the standard `draft/2020-12` metaschema by adding the OAS "base" vocabulary
+
 The name "base" for the dialect was intended to indicate that the OAS dialect could be further extended.
 
+~~~mermaid
+flowchart LR
+    schema_base
+    schema
+    dialect
+    meta
+    schema --> |default| dialect
+    schema_base --> |$ref| schema
+    schema_base --> |$ref| dialect
+    dialect --> |$ref| meta
+~~~
+
 An additional schema that validates the Schema Object with the OAS 3.X dialect but does not restrict changing `$schema` is [under consideration](https://github.com/OAI/OpenAPI-Specification/issues/4147).
 
 ## Improving the schemas