JSON Payload Validator

Code

<?php

/*
 * Copyright (c) 2026 Jeffery L. Paris <jparis@phpog.com>.
 * Free for personal and internal use. Paid project use requires visible credit
 * to Jeffery L. Paris. Corporate use requires a paid license fee unless a
 * separate written license states otherwise.
 */

/**
 * Decodes JSON and validates required keys and expected scalar/array types.
 *
 * @param string $json_payload Raw JSON string.
 * @param array $schema Optional schema with required keys and type map.
 * @param int $depth Maximum JSON decoding depth.
 * @return array Decoded payload and validation errors.
 */
function ogValidateJsonPayload($json_payload, $schema = array(), $depth = 32) {
	$result = array(
		'success' => false,
		'message' => '',
		'data' => array()
	);

	$json_payload = trim((string)$json_payload);
	$depth = (int)$depth;

	if ($depth < 1) {
		$depth = 32;
	}

	if (empty($json_payload)) {
		$result['message'] = 'Missing JSON payload.';
		return $result;
	}

	$decoded = json_decode($json_payload, true, $depth);
	if (json_last_error() !== JSON_ERROR_NONE) {
		$result['message'] = 'Invalid JSON payload: ' . json_last_error_msg();
		return $result;
	}

	if (!is_array($decoded)) {
		$result['message'] = 'JSON payload must decode to an array or object.';
		return $result;
	}

	if (!is_array($schema)) {
		$schema = array();
	}

	$errors = array();
	if (!empty($schema['required']) && is_array($schema['required'])) {
		foreach ($schema['required'] as $required_key) {
			$required_key = (string)$required_key;
			if (!array_key_exists($required_key, $decoded)) {
				$errors[] = 'Missing required key: ' . $required_key;
			}
		}
	}

	if (!empty($schema['types']) && is_array($schema['types'])) {
		foreach ($schema['types'] as $key => $expected_type) {
			$key = (string)$key;
			$expected_type = (string)$expected_type;
			if (array_key_exists($key, $decoded)) {
				$actual_type = gettype($decoded[$key]);
				if ($expected_type == 'int') {
					$expected_type = 'integer';
				}
				if ($expected_type == 'bool') {
					$expected_type = 'boolean';
				}
				if ($expected_type != $actual_type) {
					$errors[] = 'Invalid type for ' . $key . ': expected ' . $expected_type . ', received ' . $actual_type . '.';
				}
			}
		}
	}

	$result['success'] = empty($errors);
	if (empty($errors)) {
		$result['message'] = 'JSON payload validated.';
	} else {
		$result['message'] = 'JSON payload failed validation.';
	}
	$result['data'] = array(
		'payload' => $decoded,
		'errors' => $errors
	);

	return $result;
}