Json Schema Laravel Package

Product Decisions This Supports

• Contract-first API design (build vs. buy): Instead of hand-writing request/response validators for every endpoint, adopt JSON Schema as the single source of truth. This package is the runtime enforcement layer, so the "build" decision collapses to wiring schemas into middleware/controllers rather than owning bespoke validation code.
• Roadmap scoping for new integrations: Public-facing APIs, partner webhooks, ingestion pipelines, and marketplace/plugin payloads all need schema validation. Confirming this package covers Drafts 3/4/6/7 and 2019-09 lets you commit to a Draft-7 schema catalog without a platform change.
• Feature enablement: Schema-driven validation unlocks self-serve partner onboarding (publish schemas, partners validate locally), machine-readable error responses (property + message pairs map cleanly to API error objects), and configuration/feature-flag validation at startup.
• Input normalization as a product capability: CHECK_MODE_COERCE_TYPES and CHECK_MODE_APPLY_DEFAULTS let you accept loosely typed form/HTTP input ("17" → 17, "true" → true) and fill optional fields without extra glue code — a small but real reduction in client-side friction and support tickets.
• Test and fixture strategy: The same schema used in production can gate payload fixtures in CI, so contract drift surfaces in test runs rather than in production incidents.
• Buy over build for spec compliance: Maintaining a correct implementation of draft semantics ($ref, oneOf/anyOf, format checks, strict mode) is genuinely expensive. Delegating to a 3.6k-star, MIT-licensed, actively released library is the cheaper and lower-risk path.

When to Consider This Package

Adopt when:

• The service is PHP/Laravel and validation must live in-process (request guards, job handlers, consumers), with no desire to add a schema service.
• You already have — or want — JSON Schema artifacts (OpenAPI components, partner contracts, published specs) and need a runtime that reads them directly.
• Schemas are shared across services or languages; standard JSON Schema is the interoperability contract.
• You want coercion and default application, not just yes/no validation.
• License posture matters: MIT, permissive, no copyleft review, no commercial negotiation.
• You want an actively maintained dependency — releases through the 6.x line with dated changelogs and bug fixes (encoding edge cases, URI/RFC handling, media-type parsing) rather than an abandoned one.

Look elsewhere or mitigate when:

• Draft 2020-12 is required. 2019-09 was added in 6.10.0; newer drafts and some newer-draft features are explicitly out of scope. If your architecture standardizes on 2020-12, this is a gap, not a detail.
• Remote $ref resolution is in the request path. URI retrieval can fetch external schemas; treat that as a trust boundary (allow-list, local-only refs, no user-supplied schema URLs) or you inherit an SSRF/supply-chain surface.
• Throughput is the constraint. Pure-PHP interpretation of large schemas at high RPS may not meet latency budgets; benchmark before committing, and consider validating at the edge or caching compiled plans.
• You need code generation (typed DTOs/models from schema) rather than runtime validation — different tool class.
• Schema-as-data modification is unacceptable. Coercion and defaults mutate the caller's original payload; if downstream code assumes immutability, wrap or disable those flags.
• The team is not PHP. This is the wrong layer; pick the equivalent for your runtime and keep the schemas portable.
• Strictness is a hard requirement across all drafts. CHECK_MODE_STRICT is limited to Draft-6/7/2019-09; older drafts get non-strict behavior only.

How to Pitch It (Stakeholders)

For executives — the one-paragraph version: We validate JSON payloads by writing schemas instead of bespoke validation code. justinrainbow/json-schema is the established PHP implementation of the JSON Schema standard: MIT-licensed, ~3.6k GitHub stars, actively released with a public changelog and CI, and it supports the schema drafts our partners and internal contracts already use. Adopting it converts validation from repeated engineering work into configuration, shortens delivery on every endpoint that accepts structured input, and gives us machine-readable, consistent error responses. The cost is one Composer dependency and no license review.

For engineering — the practical framing:

• Standard, boring, and maintained. No lock-in: schemas are portable JSON artifacts, and the library is swappable.
• Drop-in for Laravel: build a SchemaRule/form request that wraps Validator, map getErrors() straight to 422 responses.
• Use the flags deliberately: enable CHECK_MODE_COERCE_TYPES and CHECK_MODE_APPLY_DEFAULTS only where you accept untrusted/messy input, and know they mutate the payload.
• Guard the $ref resolver: prefer local/inline refs (SchemaStorage::addSchema with a base URI) over fetching remote schemas at request time.
• Pin the version, add contract tests against fixtures, and treat a schema change as an API change under review.

For the roadmap discussion: Low-risk, high-leverage infrastructure. It doesn't open a new product surface on its own, but it is a prerequisite that de-risks and accelerates every integration, webhook, and partner-onboarding story on the roadmap. The single decision to make now is which schema draft becomes our standard — recommend Draft-7 today, with a note that 2020-12 support requires a separate evaluation.