Json Schema Extractor Laravel Package

Product Decisions This Supports

• API contract strategy (schema-first vs. code-first). This package bets on "your DTOs are the schema." It lets a team with an existing typed PHP domain model emit JSON Schema without maintaining a parallel YAML/JSON artifact. That directly informs whether we standardize on code-first contracts or keep a hand-authored spec as the source of truth.
• OpenAPI / public API documentation pipeline. A JSON Schema generator is the engine behind request/response bodies in an OpenAPI 3.1 document. If we are building or refreshing partner-facing docs, this is a candidate for the "DTO → schema → spec" leg of the pipeline.
• Client SDK and codegen roadmap. JSON Schema is the lingua franca for TypeScript/Java/Swift client generators. Reliable schema extraction unblocks auto-generated SDKs, which is usually a multi-quarter roadmap item sold as "faster partner integration."
• Contract testing and breaking-change detection in CI. Once schemas are generated deterministically, they can be committed and diffed per PR. That turns "did we break the API?" from a review checklist into an automated gate — a concrete reliability OKR.
• Single source of truth for validation. The same metadata that drives runtime validation (Laravel rules, Symfony constraints, attributes) can drive published schemas. This reduces the classic drift between what the docs claim and what the API accepts — a recurring source of support tickets and partner escalations.
• LLM tool / function-calling schemas (emerging). JSON Schema is the contract format for tool definitions in agentic features. A metadata-driven extractor is a cheap way to expose internal DTOs as callable tools without hand-writing schemas per endpoint.
• Event and webhook schema governance. The same generation step can produce schemas for outbound webhooks or message payloads, supporting versioning policy decisions for async contracts.
• Build vs. buy signal. With 4 stars and zero dependents, this is not a buy decision in the procurement sense — it is a "adopt the pattern, vendor the code" decision. The PM takeaway is to compare the cost of a thin internal extractor against the cost of a mature bundle, not against a support contract that does not exist.

When to Consider This Package

Consider it when:

• The codebase is PHP 8.x+ with real, typed DTOs already carrying metadata — attributes, validation constraints, docblocks, or serializer mappings. The value proposition collapses if the DTOs are untyped arrays.
• The deliverable is schema generation specifically (OpenAPI bodies, codegen input, contract fixtures), not schema validation at runtime.
• The "modular" architecture is genuinely useful to you — i.e., you have custom metadata or domain-specific annotations and expect to write your own extractor. If you only need vanilla output, modularity is overhead.
• You are willing to treat the package as source you can fork and pin. MIT license plus a small surface area makes that realistic; a vendor who abandons it costs you a day, not a migration.
• The blast radius is internal or low-traffic: internal tooling, admin APIs, pre-release docs, agent tool definitions.

Look elsewhere when:

• The API is public and revenue-adjacent. With 4 stars, 0 dependents, and essentially a single maintainer, there is no production signal and no support path. For a partner-facing contract, use the established path: swagger-php / nelmio/api-doc-bundle for OpenAPI, or the schema facilities in spatie/laravel-data if you are Laravel-native — both have years of edge-case hardening you will otherwise reimplement.
• You need broad JSON Schema draft coverage. Edge cases (composition, $ref resolution, discriminators, nullable unions, format assertions) are where young generators fail, and where "it worked on our demo DTO" stops being reassuring.
• You need schema validation, not just generation. Reach for opis/json-schema or justinrainbow/json-schema; do not stretch an extractor into a validator.
• Your team has no PHP schema depth. Debugging generator output requires reading the spec. If nobody owns that, the total cost of ownership is higher than a hosted or bundled alternative.
• You need a committed release cadence or CVE response. A single-maintainer project with a 2026-08-08 release is active but unproven; there is no track record of timely security response.

Recommended posture: a timeboxed spike (1–2 sprints), run in parallel against spatie/laravel-data or swagger-php on your three gnarliest DTOs. Decide on output fidelity and diff stability, not on the README.

How to Pitch It (Stakeholders)

To executives (one paragraph): We have an opportunity to stop maintaining API documentation by hand. Because our PHP data objects already describe their own fields and constraints, a generator can derive the published API schema directly from the code, which means our docs and SDKs cannot silently drift from reality. The candidate library is a small, MIT-licensed, single-maintainer project — genuinely useful, but with no production track record. So the recommendation is not "adopt it company-wide"; it is "fund a short, bounded evaluation against the established alternative, and pick on evidence." The upside is reduced manual documentation cost, faster partner onboarding via generated SDKs, and automated breaking-change detection in CI. The downside is capped at a couple of engineer-weeks because the license lets us vendor the code if the project stalls.

To engineering: This is a thin, extensible adapter over metadata you already maintain — attributes, constraints, serializer mappings — with a pluggable extractor model so we can add our own mappings without forking the core. It generates JSON Schema; it does not validate, and it does not replace our OpenAPI tooling. Treat it as a pattern we can own: MIT license, small surface, no runtime coupling beyond a dev/CI dependency. The evaluation criteria are output fidelity on our worst DTOs, deterministic diffs between releases, and how much of our custom metadata needs a hand-written extractor.

To security and platform: Dev-time/CI-scoped dependency, no network calls at runtime expected — verify before adoption. Pin the version, vendor the source, and record it in the dependency register with a named internal owner, given the single-maintainer risk profile and zero dependents.