Json Schema Validator Laravel Package

Getting Started

Start by installing the package via Composer:

composer require ergebnis/json-schema-validator

The core use case is validating a JSON document (e.g., a config file or API request payload) against a JSON Schema. Begin with the Validator class:

use Ergebnis\Json\Schema\Validator;

$validator = new Validator();
$schema = json_decode(file_get_contents('schema.json'), true);
$data = json_decode(file_get_contents('config.json'), true);

$result = $validator->validate($data, $schema);

The validate() method returns a Result object. Check validity with:

if (!$result->isValid()) {
    foreach ($result->getErrors() as $error) {
        echo "- {$error->getMessage()}\n";
    }
}

👉 First stop: check the Result interface and Error objects—they’re the heart of the actionable feedback.

Implementation Patterns

• Configuration Validation: Run early in app bootstrapping (e.g., in config/app.php or a middleware) to fail fast on malformed configs:

  $config = Json::decode(file_get_contents('config.json'));
  $validator->validate($config, Json::decode(file_get_contents('config.schema.json')))->requireValid();
  

• API Payload Validation (Laravel): Create a custom FormRequest rule or middleware:

  // In a middleware or trait
  $validator->validate($request->all(), $schema)->requireValid();
  

• Unit & Integration Tests: Use requireValid() for strict validation assertions—e.g., in test suites to ensure fixtures comply with expected contracts:

  $result = $validator->validate($fixture, $schema);
  $this->assertTrue($result->isValid(), $result->describe());
  

• CI Gatekeeping: Integrate as a pre-deployment check (e.g., in a GitHub Action):

  php bin/validate-configs.php
  

  where the script calls requireValid() and exits non-zero on failure.

💡 Tip: Cache schema parsing (json_decode + JsonSchema\Validator) in production—schemas rarely change.

Gotchas and Tips

• ❗ No schema auto-fetching: This library validates against already-resolved schemas. Relative $refs (e.g., "$ref": "defs.json") won’t resolve unless you explicitly load and attach them to the Schema object. Use SchemaFactory to build composable schemas.

• ❗ Type coercion pitfalls: json_decode(..., true) returns associative arrays, but JSON Schema treats 0 and "0" differently. Ensure your PHP data types match schema expectations (e.g., avoid 1 where integer is required if strict comparison matters).

• ✅ Error context matters: Error::getPath() and Error::getPointer() help pinpoint exactly where validation failed—great for UI error highlighting or logging.

• 🔧 Extensibility: While focused, it exposes SchemaFactory and ValidatorInterface. For advanced use (e.g., custom formats), subclass or decorate.

• 🧪 Testing strategy: Write schema tests first (TDD-style). Use Provider::validateDataAgainstSchema() in PHPUnit to batch-test all fixtures in a folder.

• ⚠️ Performance: Avoid re-parsing schemas on every request. Store parsed schemas (as arrays) and reuse Schema instances where possible.