Schema Laravel Package

Technical Evaluation

Architecture fit. psx/schema is a framework-agnostic parser/generator for schema dialects (TypeSchema, JSON Schema, OpenAPI, RAML, XSD, JSON-LD) that normalizes everything through an internal TypeSchema model. It has no illuminate/* coupling, so it composes cleanly as a domain service behind an interface inside a Laravel app. That is the right shape — but it means the package gives you schema objects, not Laravel artifacts. Any DTOs, FormRequests, validation rules, or API Resources remain our code (or generated code we own).

Integration feasibility. Low friction on paper: composer require psx/schema, PSR-4 autoload, no service provider needed. The real effort is mapping the TypeSchema object model onto our conventions — a nontrivial adapter layer if we want generated code that looks like the rest of the codebase rather than PSX-flavored DTOs.

Technical risk.

• Adoption signal is weak. 55 stars, 0 dependents, effectively single-maintainer (Apioo). No third-party ecosystem to lean on for bug reports, patterns, or hiring.
• Runtime vs. build-time. Parsing is CPU/memory-bound and best treated as a build/CI step, not a per-request operation. If a story emerges that requires runtime parsing, that changes the risk profile significantly.
• Semantic fidelity. Cross-format conversion always loses or reinterprets edge semantics (additionalProperties, nullability, oneOf/anyOf, discriminator handling, OpenAPI 3.0 vs 3.1). Silent mis-generation is the dangerous failure mode — it produces code that compiles and fails at the boundary.
• Vendor drift. TypeSchema is the same author's format, which is a soft lock-in point. If the project stalls, our migration cost is proportional to how deeply TypeSchema shapes our internal contracts.
• License is clean (Apache-2.0), which removes the usual legal blocker but not the stewardship question.

Key questions to resolve before committing.

1. Which concrete formats do we need — and are they all supported at the fidelity we require (OpenAPI 3.1? JSON Schema draft 2020-12?)
2. Supported PHP matrix vs. our Laravel version — does it run on PHP 8.2/8.3?
3. Release cadence and issue-response latency over the last 12 months?
4. Is the public API stable across minor versions, or has it broken semver?
5. What is parse time and peak memory on our largest realistic schema (target: our biggest OpenAPI spec)?
6. Who is the internal owner, and is fork-and-patch an acceptable fallback?

Integration Approach

Stack fit. Position it as a developer-experience and contract-governance tool, not a runtime dependency. Two viable placements:

• CLI/CI (recommended): an artisan command or CI job that ingests upstream schemas, validates them, and emits DTOs/validation into a generated namespace.
• Runtime (avoid initially): only if we need dynamic schema introspection for a gateway or plugin system.

Migration path. Do not retrofit existing contracts. Sequence:

1. Spike (1–2 weeks): one real OpenAPI spec → parse → generate DTOs into app/Generated/ → diff against hand-written equivalents. This answers the fidelity questions empirically.
2. Keep the package behind a thin SchemaRegistry/ContractCompiler interface in our domain layer so the underlying library is swappable.
3. Treat generated output as reviewed source, committed to the repo — never generated silently at deploy time.

Compatibility. Verify Composer constraints against our PHP/Laravel matrix and confirm zero transitive Laravel/Eloquent collisions. Pin a version, and vendor-fork if we need a patch we can't upstream.

Sequencing.

• Phase 1: CI-only contract validation (parse + lint, fail the build on invalid schemas). Low blast radius, immediate value.
• Phase 2: codegen for internal, non-customer-facing services only.
• Phase 3: extend to public API contracts once fidelity is proven and an owner is assigned.

Operational Impact

Maintenance. Single-maintainer dependency is the dominant operational risk. Mitigate with: pinned version, a documented fork path, an adapter boundary, and a quarterly dependency-health review with explicit exit criteria (e.g., no release in 12 months → evaluate alternatives).

Support. Community-only. No vendor SLA. We need one named internal SME who can debug a parse failure — this is not a "nobody owns it" dependency.

Scaling. Build-time usage scales fine — it's a CI cost linear in schema size. Runtime usage is the concern: parsing per request will show up in p95 latency and memory, and there is no obvious caching story inside the library. If we ever need runtime parsing, add an opaque cache keyed on schema hash.

Failure modes to instrument.

• Parse exceptions on schema format versions we didn't anticipate (build failure — acceptable, loud).
• Silent semantic loss during conversion (build succeeds, runtime 400s — the dangerous one). Mitigate with generated contract tests that assert round-trip equivalence.
• Drift between generated code and handwritten business logic after a regeneration.
• Transitive dependency breakage from an upstream PHP version bump.

Ramp-up. Small, well-scoped API surface — a senior PHP developer reaches productivity in roughly 1–2 days. The real learning curve is the TypeSchema intermediate model and its semantics, not the PHP. Budget half a sprint for the first engineer plus a written internal guide covering the adapter and the generation workflow, so the knowledge doesn't stay with one person.