Laravel Data Schemas Laravel Package

Product Decisions This Supports

• Standardizing on spatie/laravel-data as the contract layer. The package only pays off if Data classes are already how boundary shapes are declared. That makes it the argument (and the payoff) for a doctrine: one declared class drives the schema, the API docs, and generated client types — rather than three hand-maintained copies that drift.
• AI/LLM feature roadmap. Tool/function-calling definitions and structured outputs require JSON Schema. This projects an existing Data class into that schema instead of maintaining a parallel, hand-written one — the most compelling first use case because the manual alternative is precisely what silently rots.
• API contract publishing and frontend handoff. Generates machine-readable schemas that frontend/mobile teams turn into validators (Zod, Valibot) or types, replacing a wiki page that goes stale the moment a rule changes.
• Build vs. buy on a narrow capability. The scope is deliberately small: faithfully project a declared class. Buying/vendoring beats funding a bespoke generator — but the business case must include a maintenance line item, because 1 star and 0 dependents make this a reference implementation more than a dependency.
• Roadmap sequencing. Best treated as a bounded pilot: pick one domain (AI tool schemas, an internal API) and gate further investment on a fidelity spike, not on a company-wide rollout. Do not place it anywhere a generation failure blocks a release.
• Doctrine enforcement is a separate decision. The package explicitly does not enforce "every boundary shape must be a Data class." If you want coverage guarantees, budget for an architecture test/linter of your own — the package won't do it.

When to Consider This Package

Consider it when:

• Your codebase is already committed to spatie/laravel-data. If Data classes aren't the pattern today, this has nothing to project — adoption cost is really the cost of migrating to Data classes, which is a much bigger decision.
• You need JSON Schema specifically — AI tool definitions, structured outputs, frontend validators — not full OpenAPI documents.
• You need exactness more than breadth: validation rules, descriptions, examples, and nullability preserved as declared. That's the stated obligation and the only thing worth evaluating.
• You're willing to vendor or fork and own the generation path. At this maturity, treat it as code you own from day one.

Look elsewhere (or build) when:

• You need OpenAPI paths, auth, error envelopes, or multi-endpoint documentation. This is schema-level, not API-description-level.
• You need runtime validation; Laravel's validator already does that.
• You need a supported, SLA-backed dependency on a critical path. No adoption story survives a security review that frames a 1-star, 0-dependent package as production infrastructure.
• Your shapes live in arrays, docblocks, or runtime samples. The package deliberately refuses to infer — undeclared means nothing generated.
• Downstream consumers require a specific JSON Schema draft the package doesn't emit; you'd own the translation step anyway.

Recommendation: run a one-to-two-day spike on a real Data class with your nastiest rules (nested objects, enums, unions, nullables, examples, DB-backed rules like exists/unique). If the projection is faithful, adopt narrowly — AI tool schemas first, since the alternative there is manual drift. Otherwise, fork or walk away.

How to Pitch It (Stakeholders)

To executives: This is a small, MIT-licensed utility that turns our existing backend data definitions into JSON Schema — the format required for AI tool integrations, API documentation, and frontend validation. The strategic value isn't the package; it's that it makes "define the shape once, use it everywhere" actually enforceable, removing a recurring class of integration bugs and a parallel maintenance cost. It is early-stage software (single-digit stars, no dependents), so we should treat it as internalized code we can fork, not a vendor dependency: low cost, low lock-in, bounded scope, and no commitment until a short spike proves the output is exact.

To engineering: It projects declared spatie/laravel-data classes into JSON Schema, preserving validation attributes, descriptions, examples, and nullability. It deliberately does not infer shapes from arrays or docblocks — if a shape isn't a declared Data class, there is nothing to generate, so the discipline of declaring shapes is ours to enforce. It runs at build/CI time, not in the request path, so the integration is low-risk. Adopt only if we're already standardized on Data classes and need schema artifacts for AI tool definitions or frontend validators. Plan to vendor/fork it and own the generation path; wire a CI drift check so stale schemas fail loudly. Verify three things in the spike before committing: projection fidelity (attribute rules and rules(), nested/enum/union/nullable handling), how unrepresentable rules (exists, unique, closures) are surfaced rather than silently dropped, and the emitted JSON Schema draft. Fidelity of the projection is the one thing that matters — the rest we can absorb.