Issue #148 clarify two JTD validation paths in READMEs

- Root README: module table distinguishes interpreter (infrequent config) vs codegen (hot-path)
- json-java21-jtd/README: documents config-parsing use case, links to codegen
- json-java21-jtd-codegen/README: documents hot-path use case, links to interpreter
- jdt2jar/README: documents build-time pre-compilation bridging both paths
- All three sub-READMEs note JDK incubator future direction

Author: simbo1905

README.md

@@ -14,9 +14,9 @@ This repo is organized into the following modules:
 | Module | What it is | JDK |
 | --- | --- | --- |
 | `json-java21` | Core `java.util.json` backport (parser, immutable types, `Json` API) | 21+ |
-| `json-java21-jtd` | JSON Type Definition (JTD) validator implementing RFC 8927, with stack-machine interpreter and optional bytecode codegen interface (`JtdValidator`) | 21+ |
-| `json-java21-jtd-codegen` | Bytecode code generator for JTD schemas using JDK 24+ ClassFile API (JEP 484); generates Java 21-compatible `.class` files for ~9x faster validation | 24+ (auto-skipped on JDK 21) |
-| `jdt2jar` | Offline JTD-to-JAR compiler CLI and distroless container wrapper for build-time validator packaging | 24+ (auto-skipped on JDK 21) |
+| `json-java21-jtd` | JTD (RFC 8927) stack-machine interpreter — ideal for infrequent config parsing and one-time validation | 21+ |
+| `json-java21-jtd-codegen` | Bytecode code generator for JTD schemas — ahead-of-time compiled validators for repeated hot-path validation | 24+ (auto-skipped on JDK 21) |
+| `jdt2jar` | CLI + distroless container to pre-compile JTD schemas into standalone validator JARs (eliminates JDK 24+ runtime requirement) | 24+ (auto-skipped on JDK 21) |
 | `json-java21-jsonpath` | JsonPath query engine over `jdk.sandbox.java.util.json` values (Goessner-style: filters, slices, recursive descent, unions) | 21+ |
 | `json-compatibility-suite` | JSON Test Suite conformance reporter (tests against [nst/JSONTestSuite](https://github.com/nst/JSONTestSuite)) | 21+ |
 | `json-java21-api-tracker` | Daily upstream API drift detector — fetches OpenJDK sandbox sources, compares public API signatures, reports differences | 25+ |
@@ -336,7 +336,12 @@ Such vulnerabilities existed at one point in the upstream OpenJDK sandbox implem
 
 ## JSON Type Definition (JTD) Validator
 
-A complete JSON Type Definition validator is included (module: `json-java21-jtd`), implementing RFC 8927 with a stack-machine interpreter and optional bytecode codegen (JDK 24+).
+This repo includes two JTD validation paths for different use cases:
+
+- **Interpreter** ([`json-java21-jtd`](json-java21-jtd/README.md)) — stack-machine validator for infrequent config parsing and one-time validation. Runs on JDK 21+ with zero extra dependencies.
+- **Bytecode codegen** ([`json-java21-jtd-codegen`](json-java21-jtd-codegen/README.md)) — generates dedicated validator classes for repeated hot-path validation (~9x faster). Requires JDK 24+ at build time; generated classes run on JDK 21+.
+
+> `java.util.json` has entered the JDK incubator (`jdk.incubator.json`). Once the API stabilises in the JDK itself, generated bytecode validators can depend directly on future JDK classes with zero library overhead.
 
 ### Empty Schema `{}` Semantics (RFC 8927)
 
@@ -371,7 +376,7 @@ Jtd.Result result = validator.validate(schema, data);
 
 ## JTD to JAR Compiler (Optional)
 
-An optional `jdt2jar` CLI tool and distroless Docker image are available for offline JTD validator packaging. It compiles a JTD schema into a standalone validator JAR at build time, eliminating the JDK 24+ runtime requirement for generated validators. The generated JARs run on JDK 21+.
+An optional `jdt2jar` CLI tool and distroless Docker image are available for pre-compiling JTD schemas into standalone validator JARs at build time. This eliminates the JDK 24+ runtime requirement for generated validators — the JARs run on JDK 21+.
 
 See [`jdt2jar/README.md`](jdt2jar/README.md) for build instructions, container usage, and the pre-built image on GitHub Container Registry (`ghcr.io`).
 

jdt2jar/README.md

@@ -2,6 +2,16 @@
 
 `jdt2jar` compiles a JTD schema into a standalone validator JAR at build time. The generated JAR runs on JDK 21+ with no JDK 24+ runtime dependency.
 
+## Use Case
+
+This tool bridges the gap between the interpreter and codegen paths:
+
+- **Interpreter** ([`json-java21-jtd`](../json-java21-jtd/README.md)): ideal for infrequent config parsing — simple, no build step, runs on JDK 21+.
+- **Codegen** ([`json-java21-jtd-codegen`](../json-java21-jtd-codegen/README.md)): ideal for repeated hot-path validation — ~9x faster, but requires JDK 24+ at runtime.
+- **jdt2jar**: pre-compiles schemas into validator JARs at build time (using JDK 24+), then deploys them to any JDK 21+ runtime. Best for CI/CD pipelines, distroless containers, or environments where you want JIT-optimised validators without shipping a JDK 24+ runtime.
+
+> **Future note**: `java.util.json` has entered the JDK incubator (`jdk.incubator.json`). Once the API stabilises in the JDK itself, generated bytecode validators can depend directly on future JDK classes rather than this backport, making them even more efficient with zero library overhead.
+
 ## CLI
 
 ```bash

json-java21-jtd-codegen/README.md

@@ -2,6 +2,14 @@
 
 JTD schema-to-bytecode compiler using the JDK 24+ ClassFile API (JEP 484). Generates Java 21-compatible `.class` files at runtime for ~9x faster validation on hot paths.
 
+## Use Case
+
+This codegen module is optimised for **repeated hot-path validation** — event processing pipelines, API gateways, message brokers, or any scenario where the same schema validates thousands or millions of documents. The generated validator classes contain only the checks the schema requires (no interpreter, no AST, no runtime stack), and after sufficient invocations the JIT compiler inlines and optimises them to near-native speed.
+
+For **infrequent validation** (config loading, startup checks, one-off validation), the [interpreter-based validator](../json-java21-jtd/README.md) is simpler and avoids the codegen overhead entirely.
+
+> **Future note**: `java.util.json` has entered the JDK incubator (`jdk.incubator.json`). Once the API stabilises in the JDK itself, generated bytecode validators can depend directly on future JDK classes rather than this backport, making them even more efficient with zero library overhead.
+
 ## Requirements
 
 - **Build**: JDK 24+ (uses `ClassFile` API, JEP 484)

json-java21-jtd/README.md

@@ -2,6 +2,14 @@
 
 A Java implementation of the JSON Type Definition (JTD) specification (RFC 8927). JTD is a schema language for JSON that provides simple, predictable validation with eight mutually-exclusive schema forms.
 
+## Use Case
+
+This interpreter-based validator is optimised for **infrequent validation** — loading configuration files, validating resources at startup, or one-off schema checks. Because these operations run rarely, the validated classes are unlikely to be JIT-compiled, and the interpreter's simplicity keeps startup overhead low. After validation completes, the schema and document objects are typically discarded, so the JVM is not encumbered with loaded validator classes and can focus JIT effort on the application's hot path.
+
+For **repeated hot-path validation** (e.g., event processing, API gateways), consider the [bytecode codegen module](../json-java21-jtd-codegen/README.md) which generates dedicated validator classes that benefit from JIT optimisation over many invocations.
+
+> **Future note**: `java.util.json` has entered the JDK incubator (`jdk.incubator.json`). Once the API stabilises in the JDK itself, generated bytecode validators can depend directly on future JDK classes rather than this backport, making them even more efficient with zero library overhead.
+
 ## Features
 
 - **RFC 8927 Compliant**: Full implementation of the JSON Type Definition specification