Laravel Json Schema Laravel Package

Product Decisions This Supports

• Scaling to large payloads: The new normalizeWithJsonSerializable flag (defaulting to true, so drop-in compatible) gives teams a deliberate trade-off between fidelity and memory/speed. This matters for APIs handling large JSON payloads, bulk exports, reporting endpoints, and high-throughput message serialization where memory ceilings and latency budgets are real constraints.
• Build vs. buy for serialization/normalization: Rather than hand-rolling JSON encoding logic (and re-inventing edge-case handling for JsonSerializable, Eloquent Models, and JsonModel contracts), teams can adopt this package and gain a supported escape hatch — flip the flag to use the faster, lower-memory Opis\Helper::toJson path for the 90% of payloads that aren't exotic.
• Feature/roadmap signal: The default-true design is a strong compatibility signal, meaning this is a low-risk upgrade. It also opens the door to a follow-up roadmap item: allow per-request or per-serializer configuration so a single application can be fast by default and high-fidelity only where needed.
• Use-case triage: This package is a fit when product requirements include either (a) faithful serialization of models/JsonSerializable objects, or (b) throughput-optimized encoding of very large payloads. It is less central when payloads are always small and structured.
• Operational risk reduction: Teams can set the flag false in memory-constrained workers (queue consumers, Lambda/containers with tight memory limits) without forking the library, reducing the risk of OOM crashes in production.

When to Consider This Package

Adopt it when:

• You need JSON normalization/serialization on Laravel models and JsonSerializable objects, and want a maintained library rather than bespoke json_encode plumbing.
• Your application occasionally or routinely processes very large JSON payloads where memory footprint or latency is a production concern — the new flag gives you a tunable fast path.
• You value drop-in compatibility across upgrades; the default-true behavior means existing code paths are unaffected.
• You want a single API to handle both standard and large-payload encoding, avoiding a split between two serialization approaches.

Look elsewhere (or scope tightly) when:

• Your serialization needs are simple and small — a direct json_encode or Laravel's built-in resource/serialization features may suffice without an extra dependency.
• You rely on exotic JsonSerializable contracts (custom Eloquent casts, JsonModel implementations) that the Opis\Helper::toJson fast path does not fully honor — you must keep the flag true and lose the memory benefit.
• Serialization correctness is compliance-critical and you cannot accept the documented semantic gap between the two paths.
• You require fine-grained, per-request configuration today; the flag alone may be too coarse until per-context configuration is available.

How to Pitch It (Stakeholders)

For executives: This release is a low-risk, high-value enhancement. Default behavior is unchanged, so upgrades carry no migration cost, while teams gain an opt-in performance lever for large payloads — directly relevant to infrastructure cost and reliability (fewer memory-related failures). It reinforces the case for buying a maintained serialization library rather than building one.

For engineering: The new normalizeWithJsonSerializable flag (default true) preserves the existing high-fidelity normalization path, including Eloquent Models and JsonModel contracts. Setting it to false switches to Opis\Helper::toJson, which is faster and less memory-intensive but bypasses unusual JsonSerializable contracts. Recommended usage: keep true by default for correctness, and set false deliberately in memory-constrained or high-throughput contexts where the payload shape is known-simple. Action items: benchmark against representative production payloads before flipping the default, and document which code paths depend on the high-fidelity path.