cJSON
A tiny JSON parser in a single C file you can drop into any project.
What it is
cJSON is a lightweight C library for parsing, printing, and manipulating JSON data. It is designed to be simple, fast, and portable, making it ideal for embedded systems and performance-critical applications.
cJSON allows you to parse JSON strings into C structures, traverse and modify JSON objects and arrays, and serialize them back into strings or files. It is suitable for both simple and complex JSON handling.
- Licence
- MIT
- Watch for
- Manual memory management — every cJSON_Parse needs a cJSON_Delete
When to use it
The question documentation cannot answer for you — because it cannot recommend something else.
Reach for it when
- Embedded or constrained targets where dependency size matters
- You want to vendor one .c and one .h file and be done
Look elsewhere when
- You are writing C++ — nlohmann/json is far more pleasant and type-safe
Installation
sudo apt install libcjson-devGetting started
The smallest useful thing you can do with it, and what each part means.
#include <stdio.h>
#include <cjson/cJSON.h>
int main() {
const char *text = "{\"name\":\"Alice\",\"age\":30}";
cJSON *root = cJSON_Parse(text);
if (!root) {
printf("Error parsing JSON\n");
return 1;
}
cJSON *name = cJSON_GetObjectItem(root, "name");
printf("Name: %s\n", name->valuestring);
cJSON_Delete(root);
return 0;
}#include <cjson/cJSON.h>
cJSON *root = cJSON_CreateObject();
cJSON_AddStringToObject(root, "name", "Bob");
cJSON_AddNumberToObject(root, "age", 25);
char *text = cJSON_Print(root);
printf("%s\n", text);
cJSON_free(text);
cJSON_Delete(root);Advanced usage
Where the library earns its place over a simpler alternative.
cJSON *arr = cJSON_CreateArray();
cJSON_AddItemToArray(arr, cJSON_CreateString("apple"));
cJSON_AddItemToArray(arr, cJSON_CreateString("banana"));
for(int i = 0; i < cJSON_GetArraySize(arr); i++) {
cJSON *item = cJSON_GetArrayItem(arr, i);
printf("%s\n", item->valuestring);
}
cJSON_Delete(arr);cJSON_ReplaceItemInObject(root, "age", cJSON_CreateNumber(26));FILE *fp = fopen("data.json", "w");
fputs(cJSON_Print(root), fp);
fclose(fp);FILE *fp = fopen("data.json", "r");
fseek(fp, 0, SEEK_END);
long length = ftell(fp);
fseek(fp, 0, SEEK_SET);
char *data = malloc(length + 1);
fread(data, 1, length, fp);
data[length] = '\0';
cJSON *root = cJSON_Parse(data);
free(data);
fclose(fp);Errors and fixes
The failures you are most likely to hit, and what actually resolves them.
- cJSON_Parse returns NULL
- Check JSON syntax and ensure the input string is valid.
- Invalid type access
- Use type checking functions like `cJSON_IsString`, `cJSON_IsNumber` before accessing values.
- Memory leaks
- Always call `cJSON_Delete` on allocated JSON objects and free printed strings.
Best practices
- Always check return values from `cJSON_Parse` to handle parsing errors.
- Use `cJSON_Delete` to free memory after creating or parsing objects.
- Use `cJSON_AddItemToObject` and `cJSON_AddItemToArray` to manage memory automatically.
- Use `cJSON_Print` or `cJSON_PrintBuffered` for serializing JSON to strings.
- Avoid memory leaks by freeing both JSON objects and allocated strings properly.
Alternatives
Comparable options, and the reason you would pick one over the other.
Background
Why it exists, and what it was reacting to.
cJSON was created by Dave Gamble to provide a minimalistic, easy-to-use C library for handling JSON data. It is widely used in projects that need a small footprint and fast JSON parsing without external dependencies.