JSON Schema Validator (Opis)

This module integrates Opis JSON Schema with Drupal to enable JSON and YAML validation against recent JSON Schema drafts (draft-06, draft-07, 2019-09, and 2020-12).

This is very useful for validating the content of JSON fields.

The module is intended for developers. You will need to create a custom module to add your schemas.

Alternative modules

If you are using older versions of JSON Schema, you do not need this module; Drupal core and composer already include justinrainbow/json-schema. You only need this module if you want Opis for support for recent versions of JSON Schema (draft-06 and newer).

Although development of the json-schema library was paused for awhile, people are now working on it again and support for more recent versions of JSON Schema is being added.

See the discussion at #3350943: Dependency evaluation for json schema validation.

Getting started

Install the module with Composer.

Create some JSON schema. All JSON schema must use the same domain for "$id".

Each schema file must be named .schema.json, where </code> is the schema's <code>"$id" with the domain removed.

Put all the JSON schema in the same directory.

Enable the module: drush pm:install json_schema_validator

Go to the module settings page at /admin/config/system/json_schema_validator.

For Schema Domain, set the domain of the JSON schema (the domain used for "$id").

For Schema Directory Path, set the path of the directory to your JSON schemas.

Validation Enabled (on by default) is a kill switch. When you turn it off, validateJsonSchema() returns TRUE for any input without checking it, and validateAndUseDefaultsWhenInvalid() still applies the schema's defaults but skips the final validation pass. validateAndApplyDefaults() instead fails closed and throws, because its strict guarantee cannot hold without the validator.

Debug logging

When validation fails, the failure is logged with the schema name, the user ID, and the failing paths and schema-derived reasons. The data being validated is not included, and the thrown exception reports only the paths and reasons.

The same applies when invalid values are reset to defaults (with validateAndUseDefaultsWhenInvalid()): each reset is logged with its path and the applied default, but the rejected value itself is omitted.

Enable Debug: log full payload on validation failure to additionally include the data being validated — the complete payload on a hard failure, and the rejected value on each reset-to-default. Leave this off in production: that data can contain sensitive values (for example fields stored encrypted), and logging it in plaintext defeats that protection.

Using the validator

Call the service with your data encoded as a JSON string and the name of your schema. The schema name is the schema's "$id" with the domain and the .schema.json suffix removed.

For a schema file named my-defined-json-schema.schema.json with an "$id" of https://www.example.com/my-defined-json-schema.schema.json, the schema name is my-defined-json-schema.

$encoded_json = json_encode($data_to_validate);
\Drupal::service('json_schema_validator.validator')->validateJsonSchema($encoded_json, 'my-defined-json-schema');

Validation methods

The json_schema_validator.validator service implements JsonSchemaValidatorInterface, which provides three validation methods:

• validateJsonSchema() — validates the data and throws on an invalid value. Use this when invalid input should be rejected.
• validateAndUseDefaultsWhenInvalid() — replaces every missing or invalid value with the schema's "default", returning data that is guaranteed to validate. Use this to sanitize input rather than reject it.
• validateAndApplyDefaults() — fills missing values from the schema's "default" but leaves a present-but-invalid value in place so validation rejects it (strict). Use this where silently overwriting a wrong value would be unsafe (for example, dates).

See the interface for the full contract: parameters, return values, and the exceptions each method throws.

Note: The two defaults methods walk the schema themselves and support only a subset of JSON Schema: object; array (with items constrained by enum, minItems, maxItems, uniqueItems); scalar type/enum; and $ref. validateAndUseDefaultsWhenInvalid() throws on any other keyword (for example pattern, format, or oneOf) and requires every value it can reach to declare a "default". validateJsonSchema() has no such limitation; it validates against the full schema with Opis.

Validating YAML files

Some schema-bearing files in the Drupal ecosystem (for example SDC *.component.yml) store their data as YAML rather than JSON. The json_schema_validator.yaml_validator service reads a YAML file from disk, decodes it with Drupal core's YAML serializer, and validates it against your JSON schema. The schema itself is still authored in JSON.

\Drupal::service('json_schema_validator.yaml_validator')->validateYamlFile($path_to_yaml_file, 'my-defined-json-schema');

The json_schema_validator.yaml_validator service implements YamlJsonSchemaValidatorInterface, which mirrors the three JSON methods. Each reads and decodes the YAML file and then delegates to its JSON counterpart:

• validateYamlFile()
• validateYamlFileAndUseDefaultsWhenInvalid()
• validateYamlFileAndApplyDefaults()

Supporting this module

All contributions are welcome. Please submit MRs, not patches, so that the CI tests are run. Please add tests if possible.

Maintainers

• Patrick Kenny - ptmkenny