Zephyr JSON

Zephyr JSON

Zephyr's JSON library provides compile-time descriptor-based serialization without dynamic memory allocation. It maps C struct fields to JSON keys using static descriptors.

Quick Start

#include <zephyr/data/json.h>

// 1. Define your data structure
struct sensor_data {
    const char *device_id;
    int32_t temperature;
    bool active;
};

// 2. Create descriptors mapping struct fields to JSON keys
static const struct json_obj_descr sensor_descr[] = {
    JSON_OBJ_DESCR_PRIM(struct sensor_data, device_id, JSON_TOK_STRING),
    JSON_OBJ_DESCR_PRIM(struct sensor_data, temperature, JSON_TOK_NUMBER),
    JSON_OBJ_DESCR_PRIM(struct sensor_data, active, JSON_TOK_TRUE),
};

// 3. Encode to JSON
struct sensor_data data = {.device_id = "sensor-01", .temperature = 25, .active = true};
char buffer[128];
int ret = json_obj_encode_buf(sensor_descr, ARRAY_SIZE(sensor_descr), &data, buffer, sizeof(buffer));
// buffer: {"device_id":"sensor-01","temperature":25,"active":true}

// 4. Decode from JSON
char json[] = "{\"device_id\":\"sensor-02\",\"temperature\":30,\"active\":false}";
struct sensor_data parsed;
int64_t result = json_obj_parse(json, strlen(json), sensor_descr, ARRAY_SIZE(sensor_descr), &parsed);

Kconfig

# Required
CONFIG_JSON_LIBRARY=y

# Optional: Enable float/double support (requires full libc)
CONFIG_JSON_LIBRARY_FP_SUPPORT=y

Token Types Quick Reference

Common Patterns

Nested Objects

struct inner {
    int value;
};

struct outer {
    const char *name;
    struct inner nested;
};

static const struct json_obj_descr inner_descr[] = {
    JSON_OBJ_DESCR_PRIM(struct inner, value, JSON_TOK_NUMBER),
};

static const struct json_obj_descr outer_descr[] = {
    JSON_OBJ_DESCR_PRIM(struct outer, name, JSON_TOK_STRING),
    JSON_OBJ_DESCR_OBJECT(struct outer, nested, inner_descr),
};
// {"name":"test","nested":{"value":42}}

Arrays of Primitives

struct data {
    int values[10];
    size_t values_len;  // Tracks actual count
};

static const struct json_obj_descr data_descr[] = {
    JSON_OBJ_DESCR_ARRAY(struct data, values, 10, values_len, JSON_TOK_NUMBER),
};
// {"values":[1,2,3,4,5]}

Arrays of Objects

struct item {
    const char *name;
    int qty;
};

struct order {
    struct item items[5];
    size_t items_len;
};

static const struct json_obj_descr item_descr[] = {
    JSON_OBJ_DESCR_PRIM(struct item, name, JSON_TOK_STRING),
    JSON_OBJ_DESCR_PRIM(struct item, qty, JSON_TOK_NUMBER),
};

static const struct json_obj_descr order_descr[] = {
    JSON_OBJ_DESCR_OBJ_ARRAY(struct order, items, 5, items_len,
                             item_descr, ARRAY_SIZE(item_descr)),
};
// {"items":[{"name":"apple","qty":3},{"name":"banana","qty":2}]}

Named Fields (JSON key differs from C field)

Use *_NAMED variants when JSON keys aren't valid C identifiers:

struct config {
    int api_version;     // JSON: "api-version"
    bool is_enabled;     // JSON: "is_enabled!"
};

static const struct json_obj_descr config_descr[] = {
    JSON_OBJ_DESCR_PRIM_NAMED(struct config, "api-version", api_version, JSON_TOK_NUMBER),
    JSON_OBJ_DESCR_PRIM_NAMED(struct config, "is_enabled!", is_enabled, JSON_TOK_TRUE),
};

String Buffers vs Pointers

struct example {
    const char *ptr_string;    // Points into original JSON buffer
    char buf_string[32];       // Copies data (survives buffer reuse)
};

static const struct json_obj_descr example_descr[] = {
    JSON_OBJ_DESCR_PRIM(struct example, ptr_string, JSON_TOK_STRING),
    JSON_OBJ_DESCR_PRIM(struct example, buf_string, JSON_TOK_STRING_BUF),
};

Use JSON_TOK_STRING_BUF when: JSON buffer will be reused or freed after parsing.

Important Notes

1. Input modification: json_obj_parse() modifies the input buffer (null-terminates strings in place)
2. No UTF-8 validation: The library does not validate UTF-8 encoding
3. Escape handling: Escape sequences are preserved as-is (e.g., \t stays as \t)
4. Descriptor limit: Maximum 63 fields per descriptor array
5. Return value: json_obj_parse() returns a bitmap of decoded fields (bit N = field N decoded)

References

• API Details: references/api.md - Complete function signatures and return values
• Kconfig Options: references/kconfig.md - Configuration options and dependencies
• Source Locations: references/locations.md - Header, implementation, and sample paths

Related Skills

• zephyr-net-socket: HTTP/CoAP communication (JSON payloads)
• zephyr-settings: Persistent storage (JSON config files)
• zephyr-cbor: Alternative binary serialization (smaller, faster than JSON)