feat: validate generated models against source JSON Schema

CHANGELOG.md

@@ -6,6 +6,52 @@ when correcting output that was wrong or incomplete on the wire.
 
 ## [Unreleased]
 
+### Added
+
+- The 55-spec compile gate now generates deterministic JSON instances for
+  representable component schemas, validates them against the source JSON
+  Schema, hydrates and serializes the exact generated Rust models, validates
+  their output, and requires a stable second round trip. Targeted runs such as
+  `scripts/spec-compile.sh anthropic` use the same gate and report sample and
+  skip coverage.
+
+### Changed
+
+- **Breaking (generated API).** Structs used as discriminated-union variants
+  retain their discriminator fields, so constructing one directly now requires
+  the same tag its standalone component schema requires. Parent unions perform
+  explicit discriminator-directed Serde dispatch instead of stripping the
+  field and relying on an internally tagged derive. This keeps direct values,
+  arrays, and union payloads on one schema-valid wire shape.
+
+### Fixed
+
+- Required nullable fields serialize `None` as explicit JSON `null` instead of
+  omitting a key listed by the schema's `required` array. Nullable component
+  schemas referenced by a property now propagate that nullability to the field.
+- A composition nested as one branch of an outer `anyOf` is retained as a named
+  Rust union variant instead of being silently dropped.
+
+- Boolean subschemas (`true` and `false`) parse wherever JSON Schema 2020-12
+  allows one — a property, a `$defs` entry, `not`, `if`/`then`/`else`,
+  `contains`, `propertyNames`, `patternProperties`, `dependentSchemas`, a
+  `oneOf` branch. `properties: {extra: true}` is how a spec says "this key
+  exists, any value"; one of those anywhere in a document used to fail the whole
+  thing with "data did not match any variant of untagged enum Schema" (#63).
+
+  `true` generates `serde_json::Value` and `false` a value that cannot occur —
+  both reported as faithful by `--report-untyped`. In a union, a `true` branch
+  makes the union unconstrained and a `false` branch is dropped, so
+  `oneOf: [A, false]` is `A`.
+- Integer keywords written as decimals — `maxItems: 2.0`, which JSON Schema
+  permits and the 2020-12 suite exercises — are read as the counts they are
+  rather than rejecting the document. A fractional value like `2.5` is still an
+  error.
+
+  Together these take the vendored JSON Schema 2020-12 corpus from 38 parse
+  failures to zero, with no round-trip loss.
+
+
 ## [0.14.0] - 2026-08-27
 
 ### Added

CONTRIBUTING.md

@@ -90,6 +90,23 @@ The full corpus generates and compile-checks 55 OpenAPI documents and can take
 several minutes. CI runs a fast generation tier on pull requests and the full
 compile tier weekly or on manual dispatch.
 
+Compile runs also generate deterministic, schema-valid JSON samples for each
+representable component model. Each sample is independently validated against
+the source OpenAPI JSON Schema, hydrated into the generated Rust type,
+serialized, validated again, and round-tripped a second time to require a stable
+wire representation. Start with one production spec while iterating:
+
+```bash
+scripts/spec-compile.sh anthropic
+```
+
+The full `scripts/spec-compile.sh` command applies the same check across the
+55-spec compile suite. Its summary reports component and sample coverage plus
+explicit schema skips. Set `SPEC_COMPILE_SCHEMA_ROUNDTRIP=0` only when isolating
+an unrelated compile failure; parse-only runs skip model round trips because
+they do not compile generated Rust. Failed scratch crates and logs are retained
+under `tmp/spec-compile/`.
+
 ## Compatibility expectations
 
 Until 1.0, a minor release may correct generated Rust APIs that were incomplete

Cargo.toml

@@ -58,6 +58,7 @@ serde_path_to_error = "0.1.20"
 serde_yaml = "0.9"
 insta = { version = "1.41", features = ["yaml"] }
 tempfile = "3.0"
+uuid = { version = "1", features = ["serde"] }
 
 [features]
 default = ["cli"]
@@ -82,6 +83,11 @@ name = "file-beads"
 path = "src/bin/file-beads.rs"
 required-features = ["internal-tools"]
 
+[[bin]]
+name = "schema-roundtrip"
+path = "src/bin/schema-roundtrip.rs"
+required-features = ["internal-tools"]
+
 [lints.clippy]
 unwrap_used = "deny"
 expect_used = "warn"

README.md

@@ -727,6 +727,14 @@ cargo insta review        # review snapshot diffs
 scripts/spec-compile.sh   # generate + cargo-check every spec in specs/ (full corpus)
 ```
 
+`scripts/spec-compile.sh` also synthesizes valid JSON instances from each
+source component schema, hydrates the exact generated Rust model, serializes it
+back to JSON, validates that output against the same schema, and requires a
+stable second round trip. The summary reports tested components, generated
+samples, and explicit skips. Pass one or more spec names (for example,
+`scripts/spec-compile.sh anthropic`) for a focused trial before running the
+full 55-spec compile suite.
+
 The compile tiers are intentionally different:
 
 - Every pull request and push to `main` generates all 55 supported OpenAPI

examples/anyof_unions.rs

@@ -107,12 +107,13 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
             "  - {}: {:?}",
             name,
             match &schema.schema_type {
-                openapi_to_rust::analysis::SchemaType::Union { variants } => {
+                openapi_to_rust::analysis::SchemaType::Union { variants, .. } => {
                     format!("Union(variants: {})", variants.len())
                 }
                 openapi_to_rust::analysis::SchemaType::DiscriminatedUnion {
                     discriminator_field,
                     variants,
+                    ..
                 } => {
                     format!(
                         "DiscriminatedUnion(discriminator: {}, variants: {})",

examples/debug_beta_input.rs

@@ -21,6 +21,7 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
         if let openapi_to_rust::analysis::SchemaType::DiscriminatedUnion {
             discriminator_field,
             variants,
+            ..
         } = &schema.schema_type
         {
             println!("\nDiscriminator field: {discriminator_field}");

examples/discriminated_unions.rs

@@ -143,6 +143,7 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
                 openapi_to_rust::analysis::SchemaType::DiscriminatedUnion {
                     discriminator_field,
                     variants,
+                    ..
                 } => {
                     format!(
                         "DiscriminatedUnion(discriminator: {}, variants: {})",

examples/discriminator_mappings.rs

@@ -139,6 +139,7 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
                 openapi_to_rust::analysis::SchemaType::DiscriminatedUnion {
                     discriminator_field,
                     variants,
+                    ..
                 } => {
                     let variant_info: Vec<String> = variants
                         .iter()

examples/inline_objects.rs

@@ -118,6 +118,7 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
                 openapi_to_rust::analysis::SchemaType::DiscriminatedUnion {
                     discriminator_field,
                     variants,
+                    ..
                 } => {
                     let variant_info: Vec<String> = variants
                         .iter()
@@ -134,7 +135,7 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
                         variant_info.join(", ")
                     )
                 }
-                openapi_to_rust::analysis::SchemaType::Union { variants } => {
+                openapi_to_rust::analysis::SchemaType::Union { variants, .. } => {
                     let variant_info: Vec<String> =
                         variants.iter().map(|v| v.target.to_string()).collect();
                     format!("Union(variants: [{}])", variant_info.join(", "))

examples/openai_patterns.rs

@@ -102,7 +102,7 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
                 openapi_to_rust::analysis::SchemaType::Object { properties, .. } => {
                     format!("Object({} properties)", properties.len())
                 }
-                openapi_to_rust::analysis::SchemaType::Union { variants } => {
+                openapi_to_rust::analysis::SchemaType::Union { variants, .. } => {
                     let variant_info: Vec<String> =
                         variants.iter().map(|v| v.target.to_string()).collect();
                     format!("Union(variants: [{}])", variant_info.join(", "))

examples/server-anthropic-messages/src/main.rs

@@ -58,6 +58,7 @@ fn messages_unary() -> MessagesPostResponse {
         content: vec![gen::ContentBlock::TextBlock(gen::ResponseTextBlock {
             citations: None,
             text: "hello (unary)".into(),
+            r#type: gen::ResponseTextBlockType::Text,
         })],
         id: "msg_demo".into(),
         model: gen::Model::Custom("claude-demo".into()),

examples/server-openai-responses/src/main.rs

@@ -1,7 +1,7 @@
 //! Example: host a perfect-replica of OpenAI's `POST /v1/responses`.
 //!
 //! Exercises both branches of the typed response enum:
-//!   - `body.stream == Some(true)`  → `OkStream(Sse<...>)`
+//!   - `body.stream.flatten().unwrap_or(false)`  → `OkStream(Sse<...>)`
 //!   - otherwise                    → `Ok(Response)` (single JSON body)
 //!
 //! Run:
@@ -35,7 +35,7 @@ struct AppState;
 #[async_trait::async_trait]
 impl ResponsesApi for AppState {
     async fn create_response(&self, body: CreateResponse) -> CreateResponseResponse {
-        if body.stream == Some(true) {
+        if body.stream.flatten().unwrap_or(false) {
             create_response_streaming()
         } else {
             create_response_unary(body)

examples/test_nested_discriminators.rs

@@ -97,6 +97,7 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
                 openapi_to_rust::analysis::SchemaType::DiscriminatedUnion {
                     discriminator_field,
                     variants,
+                    ..
                 } => {
                     let variant_info: Vec<String> = variants
                         .iter()