Laravel Json Schema Request Laravel Package

Technical Evaluation

Architecture fit. wt-health/laravel-json-schema-request occupies the HTTP boundary layer, replacing or extending Laravel's FormRequest so that request payloads are validated against a JSON Schema document rather than an imperative rules() array. It fits cleanly where JSON Schema (or an OpenAPI/AsyncAPI contract that compiles to it) is already the source of truth: API-first services, public partner APIs, and event-ingress endpoints where the same schema is shared with consumers. It is a poor fit for teams whose validation logic is inherently procedural (conditional rules across DB state, Rule::unique, custom closures) — those must be re-expressed in schema or pushed into handler code.

Integration feasibility. Mechanically low-cost: a Composer require, extending the package's request base class, and publishing config. The real integration work is authoring and governing the schemas, plus adapting exception handling and test assertions, since Laravel's assertJsonValidationErrors / $errors bag semantics do not map one-to-one onto JSON Schema violation output.

Technical risk.

• v4.0.0 is a breaking major. Dropping Laravel 11 means any application still on L11 cannot take this release and will be stranded on v3.2.0 with no forward patches. This couples the package's upgrade cadence to Laravel's annual major cycle.
• Behavioral change in authorization failure. Returning 403 on failed authorize() is the Laravel-idiomatic behavior and is therefore a correctness improvement, but it is an observable contract change for any consumer (mobile client, partner integration, generated SDK, status-code-based retry logic) that was coded against the previous status. Treat this as an API-versioning event, not a bug fix.
• Supply-chain and bus factor. Small maintainer set with a history of infrequent, batched releases (v3.2.0 → v4.0.0). A single new contributor lands the entire major change. Acceptable for a utility library, not for something on the critical path of a regulated surface without a plan B.
• Transitive validator risk. Actual validation semantics come from whichever JSON Schema engine is underneath (draft version support, $ref resolution, format assertions). That dependency, not this package, dictates correctness and CVE exposure.

Key questions.

1. What is the exact Composer constraint in v4.0.0 — does it support Laravel 12 and 13, or 13 only? What is the PHP floor?
2. What status did failed authorization return before (401?), and is the change documented as breaking with a migration note?
3. Which JSON Schema draft(s) and which validator library, pinned how? Are remote $ref fetches disabled by default?
4. Is there a published upgrade guide and a CI matrix covering the supported Laravel/PHP combinations?
5. What is the error response shape on validation failure, and is it overridable/configurable?
6. Is there a SECURITY.md and a disclosure path? Who has release rights on the repo?

Integration Approach

Stack fit. Constrain to Laravel 12/13 applications on a modern PHP runtime. Do not attempt to backport; the maintainer has explicitly severed L11.

Migration path.

1. Inventory every request class that extends the package base and every consumer that asserts on the auth-failure status code.
2. Pin ^3.2.0 on all Laravel 11 services and record them as explicitly frozen — schedule their Laravel 12/13 upgrade rather than a package upgrade.
3. Upgrade Laravel first, package second. Move the host app to Laravel 12/13, verify the framework upgrade in isolation, then bump the package. Reversing the order produces a compound failure with ambiguous attribution.
4. Reconcile the 403 change before merge: update OpenAPI specs, generated clients, API docs, and any test fixtures asserting the old code. If an external consumer cannot change immediately, add a temporary exception-handler mapping at the app layer rather than delaying the upgrade indefinitely.
5. Re-baseline tests for the new validation error shape; replace assertJsonValidationErrors usage with assertions on the schema-violation payload.

Compatibility. Audit for other packages that type-hint or subclass Illuminate\Foundation\Http\FormRequest in ways that interact with the package's base class, and for any middleware or exception handler keyed on authorization status.

Sequencing. Dev branch → contract tests green (including a negative-path test asserting 403) → staging with production-shaped payloads → production. Keep the release behind a feature flag only if the request classes are numerous enough that rollback-by-redeploy is impractical.

Operational Impact

Maintenance. Low ongoing code maintenance, non-trivial governance maintenance. Schemas become versioned artifacts requiring review, ownership, and a deprecation policy. Expect one forced major upgrade per year, timed to Laravel's release cadence, plus a 6–12 month tail of lagging services. Budget roughly one engineer-week per annual cycle across the fleet.

Support. Community-only: GitHub issues, no SLA, no vendor. Escalation path is "read the source" — the package is small enough that this is viable. Identify and document an internal owner who can patch a fork if the upstream stalls.

Scaling. Validation is CPU-bound and synchronous in the request path. JSON Schema validation is generally more expensive than Laravel's rule engine, and cost scales with schema size and $ref graph depth. Mitigate by compiling/caching schema objects per endpoint, keeping schemas flat, disabling remote reference resolution (also an SSRF and latency hazard), and capping request body size at the edge. Load-test representative endpoints before wide rollout rather than assuming parity with the previous validator.

Failure modes.

• Contract blast radius: a single bad schema deployment can reject all traffic to an endpoint or, worse, silently accept malformed payloads. Schema changes need the same review rigor as migrations.
• Uncaught validator exceptions surfacing as 500s instead of 422s if the exception mapping is incomplete.
• Client mis-handling of 403 — retry storms or spurious logout flows if auth-failure handling assumed 401.
• Stranded L11 services accumulating unpatched security exposure once upstream stops backporting to v3.
• Remote $ref fetch causing outbound calls to attacker-influenced URLs.

Ramp-up. Engineers must learn JSON Schema (draft semantics, oneOf/anyOf pitfalls, additionalProperties) rather than Laravel's rule DSL, and must internalize that error messages are machine-oriented and less human-friendly by default. Plan ~1–2 days per engineer plus a shared internal style guide for schema authoring; without it, schema quality will diverge across teams faster than rule-based validation ever did.