Json Schema Bundle Laravel Package

Getting Started

• Install: composer require soyuka/json-schema-bundle plus justinrainbow/json-schema if it isn't pulled transitively. This is a Symfony2-era bundle, so expect it to target Symfony 2.x constraints.
• Register the bundle in app/AppKernel.php inside registerBundles() (new Soyuka\JsonSchemaBundle\JsonSchemaBundle() — verify the exact FQCN in the repo's JsonSchemaBundle.php).
• Look here first: the bundle's DependencyInjection/ extension and Resources/config/services.yml/.xml. That's where the service id and any config keys (json_schema: ...) are defined. The bundle is thin, so the whole surface is a handful of files — read them before assuming a feature exists.
• First use case: validating a decoded JSON request/payload against a schema file. The common shape is:

$validator = $this->get('json_schema.validator'); // confirm the id in services.yml
$schema = (object) ['$ref' => 'file://'.__DIR__.'/../Resources/schemas/user.json'];
$data   = json_decode($request->getContent());

$validator->validate($data, $schema);
if ($validator->isValid()) {
    // proceed
}
foreach ($validator->getErrors() as $error) {
    // $error->getPropertyPath(), $error->getMessage(), $error->getConstraint()
}

If the bundle only registers the underlying JsonSchema\Validator, treat it as a DI convenience wrapper rather than a full validation framework.

Implementation Patterns

• Inject, don't fetch: bind the validator service id to a constructor argument in your own services, or alias it, so you can swap/decorate it later (e.g. add logging or normalize errors).
• Centralize schema resolution in a small SchemaRepository service that maps logical names (user.create) to absolute schema paths/URIs. Keeps $ref wiring out of controllers.
• Validate at the boundary: do schema validation in a request listener, a Symfony Validator constraint, or a form/API layer — not deep in domain services. Return 400 with a normalized error list on failure.
• Preload/cache schemas: $ref resolution is I/O-heavy. Load schemas once into a JsonSchema\Uri\UriRetriever / SchemaStorage (depending on the justinrainbow version) and reuse the validator instead of re-reading files per request.
• Console validation: wire a command that lints fixtures/config files against schemas in CI. This is often the highest-value use of a small bundle like this, since it gives you a fast feedback loop without touching runtime paths.
• Error normalization: map ValidationError objects to {property, message, constraint} arrays once, in a service, so API responses and logs stay consistent.
• Test fixtures: in functional tests, assert payloads against the same schemas to catch contract drift between client and server.

Gotchas and Tips

• Maintenance risk: 6 stars, 0 dependents, Symfony2-era. Verify composer constraints against your Symfony/PHP versions before committing. For new code, prefer justinrainbow/json-schema directly (note it is itself archived/unmaintained) or a maintained alternative like opis/json-schema.
• $ref resolution: relative refs are the classic footgun. Use absolute file:// or http:// URIs, or set a base URI on the retriever. $ref to a schema with its own relative $refs needs an explicit base.
• Version API drift: justinrainbow's API changed across majors (validate() vs check(), isValid() vs getErrors() semantics, ValidationError accessors). Pin the version and confirm method names against the installed release.
• Error objects, not strings: getErrors() returns objects; forgetting getPropertyPath() makes messages unactionable for clients.
• Service ids are explicit: no autowiring in this era. Grep services.yml for the real id rather than guessing; missing ids fail at container compile time with a clear message.
• Config quirks: if the bundle exposes schema directories or a cache path, check the extension's load() for defaults — silent no-ops are common when keys aren't declared under the bundle's root.
• Extension points: decorate the validator service (Symfony DecoratorServicePass) to add metrics/logging, and wrap the URI retriever if you need to resolve schemas from a DB, S3, or bundle resources. Read the underlying justinrainbow classes — the bundle adds little, so the real documentation is upstream.
• Debugging: dump $validator->getErrors() and the resolved schema URI first; 90% of failures are bad $refs or a schema loaded as an array instead of an object ((object) cast matters for properties).