Laravel Data Schemas Laravel Package

Technical Evaluation

Architecture fit. The package occupies a narrow seam: it reads declared Spatie Laravel Data classes and emits JSON Schema. That is a build-time projection, not a request-path dependency, so it is architecturally low-risk to trial and easy to isolate — it can be removed in a branch with no runtime fallout. It fits where Data classes are already the boundary contract (HTTP request/response bodies, AI tool inputs/outputs, event payloads, generated frontend types) and where one declaration is meant to drive schema, docs, and client types. The explicit doctrine — a declared Data class is the input, always — makes output deterministic and reproducible from source. The corollary is equally important: the package offers nothing for teams that still pass ad-hoc arrays or infer shapes from docblocks/runtime samples. In a TPM frame, this is a downstream enabler, not a driver; its value is strictly conditional on an existing standardization on Data classes.

Integration feasibility. Plausible but unproven. There is no evidence in the available material of an artisan command, a programmatic generator API, config publishing, or output-directory conventions. With 1 star and 0 dependents there is no public production record. Treat feasibility as "plausible pending spike": confirm the command/API surface, supported Spatie Data versions, PHP/Laravel bounds, and JSON Schema draft target before committing any roadmap slot. The integration itself (install package, point at Data classes, generate in CI) is simple in principle; the unknown is whether the projection and tooling are mature enough to wire in without surprises.

Technical risk. High, concentrated in maturity rather than concept:

• Bus factor / adoption risk. Single maintainer, effectively zero downstream usage. No signal on release cadence, issue responsiveness, or backward-compatibility discipline. Assume we become de facto maintainers if adopted.
• Upstream coupling. The package reflects Spatie Laravel Data internals (attributes, type resolution). Spatie Data evolves quickly; an upstream bump can silently change projection semantics.
• Statically unresolvable rules. exists, unique, DB-backed Rule::in, and closure rules cannot be faithfully projected into JSON Schema. If they are dropped silently, the schema under-specifies validation — a correctness risk that must be verified and, if present, documented as a known gap.
• Semantic gaps. PHP nullability vs JSON Schema required, unions, enums, nested/recursive DataCollection, and Optional all need explicit mapping decisions. Divergence here is where drift bugs live.
• Score context. Composite 0.105 with 1 star and 0 dependents is a "do not put on the critical path without fork-and-own" signal. Opportunity score 43.6 indicates the problem space is real even though the artifact is immature.

Key questions. (To be resolved in a 1–2 day spike, not by reading alone.)

1. Which Spatie Laravel Data, PHP, and Laravel versions are supported, and are they pinned in composer.json?
2. Does it read attribute-based validation (#[Required], #[Max], #[Email]) and the rules() method, or only one — and what happens to rules it cannot represent?
3. What JSON Schema draft is emitted (draft-07 vs 2020-12), and is it configurable?
4. How are nested Data objects, DataCollection, enums, unions, Optional, and recursive types projected?
5. Is there an artisan command and/or programmatic generator, and is output diffable deterministically (stable key ordering) for CI drift checks?
6. What is test coverage, and are there fixture-based golden-file tests?
7. Does it emit $defs/definitions with $ref, or inline everything?
8. Who maintains it, and what is the release/issue history?

Integration Approach

Stack fit. Best fit is a Laravel 10/11 + PHP 8.1+ codebase already standardized on Spatie Laravel Data, where Data classes are the single declaration point for boundary shapes. There the package converts an existing convention into a second artifact (JSON Schema) at near-zero marginal cost. In codebases without that convention, the adoption cost is really the cost of migrating to Data classes — the package is downstream of that decision, not a driver. Do not let a package evaluation smuggle in a Data-class migration.

Migration path. Do not migrate anything for this package. Sequence:

1. Spike (1–2 days). Install in a branch, generate schemas for 5–10 representative Data classes (flat, nested, enum, union, nullable, collection, custom rule) and diff against hand-written schemas. This answers nearly every key question.
2. Pilot. Apply to one bounded domain — an internal API surface or an AI tool-schema set — and wire generation into CI as a drift check.
3. Vendor/fork decision. Given the maturity signals, if the spike passes, plan to vendor the package (or fork under our org) so we control fixes. Per the family convention, when vendoring into vendor/, check the vendored repo's AGENTS.md before editing through — relevant if we patch in place rather than fork.
4. Doctrine enforcement is ours. The package explicitly disclaims enforcing "every boundary shape must be a Data class." That requires our own architecture test or linter; budget for it separately or coverage degrades to whatever happened to be declared.

Compatibility. Primary surface is Spatie Laravel Data version alignment; secondary is the JSON Schema draft consumed downstream (API docs tooling, frontend validators, AI SDKs). Pin both explicitly. Treat any Spatie Data minor bump as requiring a schema-regeneration diff in CI. If downstream consumers expect draft-07 (common in OpenAPI 3.0 tooling) and the package emits 2020-12, that translation is ours to own.

Sequencing.

• Phase 0: Spike + golden-file fixtures; decision gate.
• Phase 1: CI generation + drift check on the pilot domain; no runtime dependency.
• Phase 2: Feed generated schemas into one downstream consumer (API docs or frontend type gen); measure fidelity.
• Phase 3: Broaden coverage; add the architecture test enforcing Data-class boundaries.
• Phase 4: Only if proven, promote to a maintained dependency (fork or upstream contributions).

Operational Impact

Maintenance. Low runtime maintenance, moderate artifact maintenance. The code runs at build/CI time — no servers, queues, or migrations. Real upkeep is (a) regenerating schemas when Data classes change, (b) tracking Spatie Data upgrades, and (c) owning the package if it stalls. With 0 dependents, assume we are the de facto maintainer of any fork; budget a small ongoing allocation, not zero. The package's own convention applies if we vendor: check the vendored AGENTS.md before editing through.

Support. MIT license, no commercial support, no active-community evidence. Escalation path is "read the source" — acceptable for a small, single-purpose package; unacceptable for a critical contract-generation dependency without a fork plan. Make this explicit in the adoption record so stakeholders understand the support posture rather than discovering it during an incident.

Scaling. Generation cost scales linearly with the number of Data classes and graph depth; for typical applications this is seconds, not minutes, and is entirely CI-side. The real scaling concern is organizational: as the number of Data classes grows, so does the surface that must be regenerated and diffed, so the CI drift check and stable output ordering become essential. Downstream, generated schemas scale well — static artifacts consumable by docs, clients, and AI tool registries.

Failure modes.

• Silent drift. Data class changes without regeneration → stale schemas → frontend/validator mismatch. Mitigation: CI drift check that fails on diff.
• Silent rule loss. exists/unique/DB-backed/closure rules cannot be projected; if dropped without warning, the schema under-specifies validation. Mitigation: verify in spike; maintain an explicit "not representable in JSON Schema" allowlist and document it.
• Upstream breakage. A Spatie Data change alters projection semantics. Mitigation: pin versions, golden-file tests, upgrade only with diff review.
• Semantic mismatch. PHP optional vs JSON Schema required, nullable vs type unions, enum representation, recursion. Mitigation: fixture tests per construct, reviewed by the owner of the downstream consumer.
• Abandonment. Upstream goes quiet mid-lifecycle. Mitigation: vendor/fork under our org before promoting to critical path; keep the generation path small enough to fork without regret.

Ramp-up. Engineering ramp-up is modest but not zero: the team must understand Spatie Data attributes, the mapping semantics to JSON Schema (especially required/nullable/Optional), and the drift expectations in CI. Budget roughly a day to run the spike, a sprint to productionize CI generation and golden files for one domain, and a follow-on increment to add the Data-class architecture test. The TPM gate is simple: only greenlight past the pilot if projection fidelity is exact on the nastiest real Data class — otherwise treat it as a reference implementation to borrow from, not a dependency to schedule around.