Json Schema Laravel Package

Getting Started

Install the package via Composer (composer require illuminate/json-schema) and start validating JSON data using the core JsonSchemaValidator class. For a Laravel-native feel, define your schema as an array or load it from a file, then call validate($data, $schema, true)—note the strict mode flag is required to get meaningful errors. If you prefer the facade pattern, register 'JsonSchema' => Illuminate\Support\Facades\JsonSchema::class in config/app.php. First use case: validating incoming API payloads against a well-defined contract before processing.

Implementation Patterns

• Schema-as-Code: Store schemas in storage/app/schemas/ (e.g., user.create.json) and load them via a dedicated SchemaLoader service to keep validation logic declarative and version-controlled.
• FormRequest Integration: In custom FormRequest classes, override validationAttributes() and inject the validator into rules()—return $validator->getErrors() as validation errors.
• Middleware-Based Validation: Build a reusable ValidateJsonSchema middleware to enforce schema compliance across entire API routes, especially useful for webhook endpoints or external integrations.
• Composability: Combine JSON Schema validation with Laravel’s built-in validator—use JSON Schema for deep object validation (e.g., nested payloads) and Laravel rules for simple field constraints (e.g., confirmed, different).
• Error Mapping: Create a helper like JsonSchemaValidator::normalizeErrors($errors) to transform verbose JSON Schema error objects into Laravel-friendly ['field' => 'message'] arrays for consistent API responses.

Gotchas and Tips

• Strict mode is non-negotiable: Validation fails silently unless you explicitly pass true as the third argument to validate()—a common source of confusion.
• No built-in format extensions: Formats like uuid, email, or date-time are validated only if the underlying justinrainbow/json-schema library supports them; custom formats require overriding JsonSchemaValidator::validateFormat() or preprocessing.
• Facade isn’t auto-registered: Laravel won’t expose JsonSchema by default—add it manually in config/app.php under aliases.
• Cache decoded schemas: Re-decoding large JSON schema files on each request kills performance; store parsed schemas in rememberForever() or a custom cache key.
• Error structure is rigid: getErrors() returns a deeply nested array (one entry per violation)—write a dedicated error transformer to avoid duplicating error-shape logic across controllers.
• Minimal community support: Since adoption is low and source unknown, assume full ownership of bug fixes, security patches, and Laravel upgrades—vet the underlying justinrainbow/json-schema dependency and test thoroughly in staging.