Complete JSON Schema parity and safe reconstruction - #490
Merged
Conversation
Add the first user-facing guide for building, serializing, and reconstructing JSON schemas. Cover primitive and structured schemas, metadata, required and nullable properties, unions, any-of schemas, local references, and the supported reconstruction subset.
Preserve explicit null defaults independently from unset defaults, make required, nullable, and unique flags reversible, and retain valid empty enum values. Emit numeric property maps and list-shaped object defaults as JSON objects, validate final union and any-of output after nullability is applied, and preserve JSON encoding failures with JSON_THROW_ON_ERROR. Add focused regression coverage for every corrected type and wire shape.
Expose multi-type unions and constrained any-of alternatives through the JSON Schema factory and contract using concrete, Laravel-style return types. Normalize null union members into nullability, reject unsupported or non-string members without coercion, preserve member order, and support shared metadata and explicit defaults. Cover direct construction, closures, nullability, failure paths, and round trips.
Add JsonSchema::fromArray() and rebuild the supported JSON Schema 2020-12 subset without silently weakening recognized validation rules or malformed input. Resolve local references iteratively with per-operation caching, a bounded active path, and a bounded aggregate expansion count. Preserve representable null, composition, enum, default, object-map, and permissive-items forms while rejecting circular, remote, lossy, or structurally conflicting schemas. Exercise every supported type, nested and referenced schemas, exact round trips, resource bounds, invalid keyword values, unsupported assertions, integer limits, and composition failure paths.
Add the JSON Schema guide to the framework documentation navigation and link the package README to the canonical user documentation. Record the public differences from Laravel that developers must account for, including explicit null defaults, sum-type defaults, strict reconstruction failures, supported null and items forms, and bounded local reference expansion.
Mark the package complete in the framework audit checklist and route future readers to the dedicated JSON Schema plan and ledger entry. Record the accepted findings, rejected speculative mechanisms, lifecycle and performance assessment, regression coverage, upstream handoff, validation results, and final no-debt disposition.
Capture the verified Laravel parity surface, serializer and reconstruction defects, approved API improvements, bounded-reference design, and explicit anti-overengineering constraints. Describe the final implementation by owning boundary, include representative code, define the regression and full-gate validation plan, and preserve the completed audit decisions needed for future maintenance.
Rewrite the guide in the simple, direct prose used by first-party Laravel documentation while preserving the original baseline in commit history. Clarify reversible constraints, supported union members, serialization failures, reference limits, nullable one-of reconstruction, permissive array forms, malformed inputs, unsupported keywords, and valid schema forms the fluent builder cannot preserve.
…ectness-parity # Conflicts: # docs/plans/2026-07-12-0915-framework-coroutine-state-lifecycle-audit-ledger.md
…ectness-parity # Conflicts: # docs/plans/2026-07-12-0900-framework-coroutine-state-lifecycle-audit.md # docs/plans/2026-07-12-0915-framework-coroutine-state-lifecycle-audit-ledger.md
Reject nullable oneOf collapses when more than one branch can match null, including duplicate and reference-resolved null branches. Keep branch-local enums scoped inside nullable anyOf compositions and reject the corresponding oneOf form when flattening would change its meaning. Add counterfactual coverage for exact oneOf cardinality, deliberate anyOf overlap, enum ownership, references, structural siblings, annotations, and existing conflict diagnostics. Clarify the supported reconstruction boundary in the canonical guide and keep the package README limited to genuine additive API differences. Record the two upstream reconstruction defects under their durable audit findings. The checks remain bounded to explicit fromArray calls and add no shared state or request hot-path work.
|
Caution Review failedThe pull request is closed. ℹ️ Recent review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (31)
📝 WalkthroughWalkthroughThe JSON Schema package adds union and any-of APIs, bounded schema reconstruction, stricter serialization, explicit default tracking, object-shape normalization, documentation, audit records, and extensive regression tests. ChangesJSON Schema correctness
Estimated code review effort: 5 (Critical) | ~120 minutes Sequence Diagram(s)sequenceDiagram
participant JsonSchema
participant Deserializer
participant ReferenceResolver
participant Type
JsonSchema->>Deserializer: fromArray(schema)
Deserializer->>ReferenceResolver: resolve local $ref
ReferenceResolver-->>Deserializer: bounded schema
Deserializer->>Type: construct validated type
Type-->>JsonSchema: reconstructed Type
Possibly related PRs
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This completes the JSON Schema correctness and parity work. It adds first-party union and
anyOfbuilders, introduces bounded reconstruction throughJsonSchema::fromArray(), and fixes serializer behavior that could lose or change valid schema meaning.The result is a round-trippable fluent API for the subset Hypervel can represent. Unsupported or ambiguous input now fails directly instead of being weakened silently.
What changed
union()andanyOf()to the JSON Schema factory and public contract.JsonSchema::fromArray()for the supported JSON Schema 2020-12 subset.nulldefaults separately from an unset default.anyOfshape after nullability is applied.oneOfmatch cardinality and branch-local enum ownership.Design
Reconstruction is intentionally strict. Recognized validation keywords are either represented faithfully or rejected; they are never discarded. Local reference resolution is iterative and scoped to a single
fromArray()call, so it adds no shared worker state or request hot-path work.Nullable composition is handled according to its actual validation semantics.
oneOfinputs must retain exactly one null match.anyOfmay retain overlapping null branches, and enums owned by a non-null branch remain on that branch rather than being hoisted across the composition.The public changes are additive. Existing builders keep their current behavior, while union,
anyOf, explicit null defaults, and reconstruction become available through the same fluent conventions as the rest of the package.Validation
For more details, see:
docs/plans/2026-08-07-2015-json-schema-correctness-current-parity-and-bounded-reconstruction.mdSummary by CodeRabbit
New Features
anyOfcompositions.nulldefaults.Documentation
Bug Fixes