Usually developers use different framework library to validate API requests data before executing any business logic. For example, Laravel framework uses validate method to validate HTTP requests. Similarly, Symfony uses validator component.
There is an alternative way to validate without using any framework validation rules, yet you can validate simple and very complex request data using JSON schema.
What is JSON schema?
JSON Schema is a vocabulary that allows you to annotate and validate JSON documents. Find more JSON Schema key words here.
Let’s take one sample API request data and it’s JSON schema.
Request body to create a sample user
{
"name": "John",
"email": "john@example.com",
"age": 25
}JSON schema for the above data
{
"type": "object",
"properties": {
"name": {
"type": "string"
},
"email": {
"type": "string",
"format": "email"
},
"age": {
"type": "integer",
"minimum": 18,
"maximum": 150
}
},
"required": ["email"]
}We can clearly see the validation rules:
- email – string, email format, and required
- name – string
- age – integer, min -18, max – 150
Validation Using JSON Schema In PHP
I will use Opis JSON Schema PHP library to validate the above JSON data using JSON schema.
Installation
Opis JSON Schema is available on Packagist and it can be installed from a command line interface by using Composer.
composer require opis/json-schemaValidation Code
I am using Laravel controller to demonstrate the validation
<?php
use App\Http\Controllers\Controller;
use Opis\JsonSchema\{
Validator,
JsonPointer,
ValidationResult,
};
use Opis\JsonSchema\Errors\{
ErrorFormatter,
ValidationError,
};
class UserController extends Controller
{
public function store(Request $request)
{
$validator = new Validator();
// Schema as a JSON string example
$schema = <<<'JSON'
{
"type": "object",
"properties": {
"name": {
"type": "string"
},
"email": {
"type": "string",
"format": "email"
},
"age": {
"type": "integer",
"minimum": 18,
"maximum": 150
}
},
"required": [
"email"
]
}
JSON;
$result = $validator->validate((object)$request->all(), $schema);
// If validation passed
if ($result->isValid()) {
// Create user ...
}
// Checking if there is an error format the error
if ($result->hasError()) {
// Get the error
$error = $result->error();
// Create an error formatter
$formatter = new ErrorFormatter();
// Print helper
$print = function ($value) {
echo json_encode(
$value,
JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES
), PHP_EOL;
};
// Custom formatter to show error message as per JSON schema rules
$custom = function (ValidationError $error, ?array $subErrors = null
) use ($formatter) {
$ret = [
'message' => $formatter->formatErrorMessage($error),
];
if ($subErrors) {
$ret['subErrors'] = $subErrors;
}
return $ret;
};
// custom
$print($formatter->formatNested($error, $custom));
}
}
}However complex JSON schema might be you can validate using the schema without being worried about all the minute validation rules.
Result
Input
{
"email": "john@example.com",
"age": 25.5
} Output
{
"message": "The properties must match schema: age",
"subErrors": [
{
"message": "The data (number) must match the type: integer"
}
]
}Possible validation output
Pros
- You can use the centralised JSON schema for Open API Specification and validation.
- Even, you can point out JSON schema URI to validate the JSON data. Check different validations.
Cons
- You may need to create several schemas and need to maintain it
Summary
JSON schema is very common and popular now a days for the wide usage of JSON data and Open API Specification. Using the same JSON schema for both the API design and API data validation need to be considered.
