📦 JsonX — Lightweight Embedded JSON Serializer

JsonX — is a declarative C layer over popular cJSON library with embedded-first memory model and structured mapping via JX_ELEMENT[].

🔧 Features

✅ ThreadX-compatible memory allocation via TX_BYTE_POOL
✅ FreeRTOS support via pvPortMalloc()/vPortFree()
✅ Baremetal support using either malloc or static buffer
✅ Custom allocator hooks support (malloc/free or user-defined)
✅ Clean jx_ namespace in the style of Azure RTOS (nx_, fx_, etc.)
✅ Structured conversion between C data and JSON using JX_ELEMENT
✅ Support for complex nested objects and arrays
✅ Strict and non-strict parsing modes
✅ Optional logging with centralized jx_log() support
✅ Lightweight footprint (suitable for STM32 / Cortex-M targets)

📦 File Structure

File	Description
`jx_api.h`	Public API headers (includes all public-facing declarations)
`jx_config.h`	Global configuration flags and compile-time feature toggles
`jx_debug.h`	Optional debug interface (logging abstraction)
`jx_internal.h`	Internal interfaces and sanity checks (`JX_RETURN_IF_NULL`, etc.)
`jx_static_allocator.h`	Interface of static buffer allocator for baremetal mode
`jx_types.h`	Core type definitions and macros (enums, constants, structures)
`jx_user.h`	Helper macros for declaring arrays, objects, and element sets
`jx_version.h`	Library version definition and constants
`example.c`	Demo usage with serialization of a `Person_t` structure
`jx_parser.c`	Core implementation: parsing, serialization, validation
`jx_static_allocator.c`	Implementation of the static allocator
`jx_version.c`	Version constant implementation
`README.md`	Project overview, usage examples, limitations, and build notes

🧠 Concepts

JsonX operates using a flat array of JX_ELEMENT structures. Each element represents a property or item in the JSON object, describing its type, memory location, and size.

Types supported:

JX_STRING, JX_NUMBER, JX_BOOLEAN
JX_OBJECT (nested), JX_ARRAY (list of elements)
JX_NULL

💡 Design Philosophy

JsonX uses declarative macros to map static C structures directly into JSON-compatible formats. This allows memory-efficient, low-footprint mapping of nested objects, arrays, and strings without dynamic type inspection or reflection.

Key benefits:

Avoids runtime heap usage in static mode
Enables fully static definitions for embedded firmware
Clear mapping between struct layout and resulting JSON

The JX_ELEMENT[] flat array acts as an intermediary representation for both parsing and serialization.

✨ Helper Macros

JsonX provides a set of declarative macros to simplify the definition of JSON ↔ C mappings.
They are split into two categories:

🔹 Element Macros (for use inside arrays)

These do not include a property name and are intended for use inside JX_PROPERTY_ARRAY(...), i.e., array elements:

Macro	Description
`JX_STRING_PTR(p)`	Maps a string pointer (`char *`). You manage the memory.
`JX_STRING_REF(v)`	Maps a string buffer (`char v[32]`). Expands to `&v`.
`JX_BOOLEAN_VAL(v)`	Maps a boolean value (`bool`, `uint8_t`, etc.).
`JX_NUMBER_VAL(v)`	Maps a numeric value (int, float, double...).
`JX_ARRAY_VAL(arr)`	Maps a nested array (`JX_ELEMENT[]`).
`JX_OBJECT_VAL(obj)`	Maps a nested object (`JX_ELEMENT[]`).
`JX_OBJECT_EMPTY`	Represents an empty object with no members.

🔸 Use _PTR when you already have a pointer (char *str), and _REF when you have a fixed-size buffer (e.g., char name[32]).

🔹 Property Macros (for objects)

These include the property name ("key" in JSON) and are used when building JSON objects:

Macro	Description
`JX_PROPERTY_STRING(key, val)`	`"key": string` mapping to `char[]`
`JX_PROPERTY_BOOLEAN(key, val)`	`"key": true/false` mapping
`JX_PROPERTY_NUMBER(key, val)`	`"key": number` mapping
`JX_PROPERTY_ARRAY(key, arr)`	`"key": [...]` array of nested elements
`JX_PROPERTY_OBJECT(key, obj)`	`"key": {}` nested object
`JX_PROPERTY_OBJECT_EMPTY(key)`	`"key": {}` with no members

🔹 Composite Array Macros

These macros help construct fixed-size arrays with multiple values or objects:

Macro	Description
`JX_PROPERTY_STRING_ARRAY_N(name, ref)`	Declare an array of N strings (buffers)
`JX_PROPERTY_NUMBER_ARRAY_N(name, ref)`	Declare an array of N numbers
`JX_PROPERTY_OBJECT_ARRAY_2(name, obj0, obj1)`	Declare a 2-element object array

🔸 All these macros expand into JX_ELEMENT[] declarations.
🔸 *_ARRAY_N(...) macros help initialize common use cases like [3][32] string buffers.
🔸 *_OBJECT_ARRAY_N(...) are ideal for grouping multiple sub-objects as array items.

All composite helpers are defined in jx_user.h, which is designed to hold such convenience macros.
This file is fully under user control — modifying or extending it does not affect the core functionality of the library.

Using these helpers keeps your object mappings clean, readable, and maintainable.

📘 JX_ELEMENT Field Reference

Each JSON node is represented by the JX_ELEMENT structure:

typedef struct json_element_s
{
    char                    property[JX_PROPERTY_MAX_SIZE];  // JSON key (property name)
    JX_ELEMENT_TYPE         type;                            // Data type: STRING, NUMBER, ARRAY, etc.
    uint8_t                 value_len;                       // Size of array/object (if applicable)
    const void             *value_p;                         // Pointer to value (primitive or buffer)
    JX_ELEMENT_STATUS       status;                          // Internal state: parsed, serialized, etc.
    struct json_element_s  *element;                         // Pointer to sub-elements (for object/array)
    uint16_t                element_size;                    // Number of sub-elements
} JX_ELEMENT;

⚠️ Notes:

property: Stores the JSON key (i.e., field name like "name", "id", etc).

🔧 JX_PROPERTY_MAX_SIZE is defined in jx_config.h.
You can adjust it to save RAM or support longer property names.
Example: set to 32 for compact mode, 64 for compatibility with long field names.

type: Enumerated value from JX_ELEMENT_TYPE (e.g., JX_STRING, JX_NUMBER, etc).

value_p: Pointer to primitive value (e.g., string/number/boolean).

element: For objects and arrays, points to the sub-elements.

value_len: Runtime length of the array or number of valid sub-elements (during parsing).

element_size: Static capacity (allocated size) of element[]. Required for parsing bounds checks.

status: Used internally by the parser/serializer to track element state.

🔸 All JX_NUMBER fields must be mapped to variables of type double.
This is a limitation inherited from the underlying cJSON,
which stores all numeric values internally as double.

🔸 See JX_ELEMENT_TYPE and JX_ELEMENT_STATUS in jx_types.h for available constants.

This structure is the backbone of JsonX, enabling both serialization and deserialization of complex JSON structures.

🧪 Example: Full Nested Person Object

See example.c for a full demonstration of how to define nested JSON layouts using JX_PROPERTY_OBJECT_ARRAY_2() and other helpers.

⚙️ Initialization

Depending on system configuration, initialization differs. One of the following must be used depending on mode:

ThreadX:

TX_BYTE_POOL byte_pool;
CHAR byte_pool_buffer[1024];

tx_byte_pool_create(&byte_pool, "JsonX byte pool", byte_pool_buffer, sizeof(byte_pool_buffer));
jx_init(&byte_pool);

FreeRTOS:

jx_init();

Baremetal with heap:

jx_init();

Baremetal with static buffer:

CHAR static_buffer[1024];
jx_init(static_buffer, sizeof(static_buffer));

Custom Allocator (platform-independent):

JX_HOOKS hooks = {
    .alloc = malloc,
    .free = free
};
jx_init(&hooks);

🧩 Usage Example

struct {
    char name[32];
    double coords[2];
} test_struct;

// JSON element array
JX_ELEMENT user[] = {
    { .type = JX_STRING, .property = "name", .value_p = test_struct.name },
    { .type = JX_ARRAY,  .property = "position", .element = (JX_ELEMENT[]) {
        JX_NUMBER_VAL(test_struct.coords[0]),
        JX_NUMBER_VAL(test_struct.coords[1])
    }, .value_len = 2 }
};

For a more advanced example of nested object arrays, see example.c

Convert to JSON (with user-allocated buffer):

char *json_buf = jx_alloc_memory(256);
jx_struct_to_json(user, 2, json_buf, 256, JX_FORMATTED);

Parse from JSON:

const char *input = "{\"name\":\"Eve\",\"position\":[12, 34]}";
jx_json_to_struct(input, user, 2, JX_MODE_STRICT);

Output Result:

test_printf("Name: %s, X: %d, Y: %d", test_struct.name, (int)test_struct.coords[0], (int)test_struct.coords[1]);

Deinitialize:

jx_free_memory(json_buf);
jx_parser_deinit();

🧼 Logging

If JX_DEBUG is set in jx_config.h, debug logging will be activated via the jx_log(...) macro:

#define jx_log(...)  logger_printf(__VA_ARGS__)

Additionally, a debug-only utility function is available:

void jx_dump_structure(JX_ELEMENT *desc, size_t count);

This function prints a human-readable tree of the current JSON structure — useful for verifying layout, element types, and parsing results.

⚠️ Notes: jx_dump_structure() is defined as static inline in jx_debug.h and compiled only when JX_DEBUG defined. No external linking or implementation is needed. This makes it lightweight and easy to enable/disable for debug builds.

Known limitations

In baremetal static mode (JX_USE_BAREMETAL without JX_USE_HEAP_BAREMETAL), jx_alloc_memory() must not be used by the user during JSON parsing or serialization.
Doing so may lead to undefined behavior due to cJSON_Delete() being internally called by JsonX, which uses the same static buffer allocator. This breaks allocator consistency when user code simultaneously allocates memory using jx_alloc_memory(). Workaround: allocate required user buffers before calling JsonX APIs, or disable static mode using JX_USE_HEAP_BAREMETAL.

📌 Versioning

#define JX_VERSION_MAJOR 1
#define JX_VERSION_MINOR 0
#define JX_VERSION_PATCH 0

const CHAR* jx_version(); // Returns static string: "JsonX v1.0.0 - (C) Mihail Zamurca, MIT Licensed"

👉 See also: cJSON documentation

📋 License

JsonX uses cJSON under MIT license and wraps it for embedded systems.

embedmind/JsonX