{"record":{"id":"bd3d1bd29226ebf8","repo":"phalcon/cphalcon","slug":"json-form-schema-is-invalid-detail","errorCode":null,"errorMessage":"JSON form schema is invalid: {detail}","messagePattern":"JSON form schema is invalid: (.+?)","errorType":"exception","errorClass":"Phalcon\\Forms\\Exceptions\\InvalidJsonSchema","httpStatus":null,"severity":"error","filePath":"phalcon/Forms/Loader/JsonLoader.zep","lineNumber":61,"sourceCode":"\n    /**\n     * @phpstan-return array<int, array<string, mixed>>\n     * @throws Exception\n     */\n    public function load() -> array\n    {\n        var ex, definitions, json, loader;\n\n        let json = this->source;\n\n        if is_file(json) && is_readable(json) {\n            let json = (string) this->phpFileGetContents(json);\n        }\n\n        try {\n            let definitions = (new Decode())->__invoke(json, true, 512, JSON_THROW_ON_ERROR);\n        } catch InvalidArgumentException, ex {\n            throw new InvalidJsonSchema(ex->getMessage());\n        }\n\n        if typeof definitions !== \"array\" || !array_is_list(definitions) {\n            throw new JsonSchemaNotArray();\n        }\n\n        let loader = new ArrayLoader(definitions);\n\n        return loader->load();\n    }\n}\n","sourceCodeStart":43,"sourceCodeEnd":73,"githubUrl":"https://github.com/phalcon/cphalcon/blob/b7419de9cd0a8a3f48441ead84c9f8415d463e25/phalcon/Forms/Loader/JsonLoader.zep#L43-L73","documentation":"JsonLoader::load() decodes its source (a JSON string or a readable file path) with JSON_THROW_ON_ERROR; any decode failure is caught and rethrown as InvalidJsonSchema carrying the underlying json error message. This surfaces malformed JSON, truncated files, and bogus input early instead of silently producing an empty form.","triggerScenarios":"Passing a file path that does not exist or is not readable, so the loader tries to decode the path string itself as JSON; hand-edited schema files with trailing commas, single quotes, or unquoted keys; passing YAML or a PHP-exported string by mistake.","commonSituations":"Schema files edited manually and left with a syntax error; deployment missing the schema file so the literal path is decoded; permissions blocking is_readable(); empty string input.","solutions":["Pre-validate the document: json_decode($json, true, 512, JSON_THROW_ON_ERROR) before constructing JsonLoader","When passing a path, verify is_file($path) && is_readable($path) first","Read the exception message — it contains the exact json_last_error detail such as 'Syntax error' with byte offset"],"exampleFix":"// before\n$loader = new JsonLoader('/config/forms.json'); // path may not exist or contain invalid JSON\n$defs = $loader->load();\n\n// after\n$path = '/config/forms.json';\nif (!is_file($path) || !is_readable($path)) {\n    throw new RuntimeException(\"Schema file missing: {$path}\");\n}\njson_decode((string) file_get_contents($path), true, 512, JSON_THROW_ON_ERROR); // fail fast with a clear error\n$defs = (new JsonLoader($path))->load();","handlingStrategy":"validation","validationCode":"$json = is_file($source) && is_readable($source)\n    ? (string) file_get_contents($source)\n    : $source;\n\n// fail fast with the exact JSON error before the loader sees it\njson_decode($json, true, 512, JSON_THROW_ON_ERROR);\n\n$defs = (new \\Phalcon\\Forms\\Loader\\JsonLoader($source))->load();","typeGuard":null,"tryCatchPattern":"try {\n    $defs = (new \\Phalcon\\Forms\\Loader\\JsonLoader($source))->load();\n} catch (\\Phalcon\\Forms\\Exceptions\\InvalidJsonSchema $e) {\n    // e->getMessage() carries the underlying json_last_error detail\n    $logger->error('Invalid JSON form schema: ' . $e->getMessage());\n    throw new \\RuntimeException('Form schema is broken; contact the site admin', 0, $e);\n}","preventionTips":["Lint all JSON schema files (json_decode with JSON_THROW_ON_ERROR) in CI before deploy","Check is_file()/is_readable() when passing paths so a missing file is not decoded as JSON","Prefer JsonLoader for machine-written schemas and keep files out of manual editing where possible"],"tags":["phalcon","forms","json","schema","loader"],"backgroundTag":"invalid-json","analyzedSha":"b7419de9cd0a8a3f48441ead84c9f8415d463e25","analyzedAt":"2026-08-21T06:21:18.811Z","schemaVersion":2},"datasetVersion":"2026-08-21T11:28:35.574Z"}