json_heal.h File Reference

Self-Healing JSON Recovery Layer (CWIST) More...

#include <stdbool.h>
#include <stddef.h>
#include <cjson/cJSON.h>

Include dependency graph for json_heal.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	cwist_schema_field
	Single field descriptor used by both the healer and the Zod validator. More...
struct	cwist_schema
	A complete schema: array of field descriptors + count. More...
struct	cwist_heal_config
	Configuration passed to cwist_json_heal(). More...
struct	cwist_heal_result
	Result of a healing attempt. More...

Macros
#define	CWIST_SCHEMA_MAX_ALIASES   8
#define	CWIST_HEAL_LOG_MAX   512

Typedefs
typedef struct cwist_schema_field	cwist_schema_field_t
	Single field descriptor used by both the healer and the Zod validator.
typedef struct cwist_schema	cwist_schema_t
	A complete schema: array of field descriptors + count.
typedef char *(*	cwist_sllm_heal_fn) (const char *broken_json, const cwist_schema_t *schema, void *userdata)
	Optional deep-recovery callback (e.g. backed by an LLM).
typedef struct cwist_heal_config	cwist_heal_config_t
	Configuration passed to cwist_json_heal().
typedef struct cwist_heal_result	cwist_heal_result_t
	Result of a healing attempt.

Enumerations
enum	cwist_field_type_t {   CWIST_FIELD_STRING = 0 , CWIST_FIELD_INT , CWIST_FIELD_FLOAT , CWIST_FIELD_BOOL ,   CWIST_FIELD_OBJECT , CWIST_FIELD_ARRAY }
	Expected value type for a schema field. More...

Functions
cwist_heal_result_t	cwist_json_heal (const char *input, const cwist_heal_config_t *cfg)
	Attempt to heal a potentially broken JSON string.
int	cwist_json_schema_align (cJSON *obj, const cwist_schema_t *schema, char *log, size_t log_sz)
	Apply L2 schema alignment to an already-parsed cJSON object in place.
void	cwist_heal_result_free (cwist_heal_result_t *r)
	Free resources owned by a cwist_heal_result_t.

Detailed Description

Self-Healing JSON Recovery Layer (CWIST)

Three-tier recovery pipeline: L1 – Syntax : fast fixes (BOM, line-comments, trailing commas, bracket balancing) L2 – Schema : field-name alias resolution + type coercion against a known schema L3 – SLLM : user-supplied deep-recovery callback (AI / LLM inference)

Usage:

static const cwist_schema_field_t fields[] = {
    { "user_id", {"userId", "uid", NULL}, CWIST_FIELD_INT,    true  },
    { "name",    {NULL},                  CWIST_FIELD_STRING, true  },
    { "active",  {"is_active", NULL},     CWIST_FIELD_BOOL,   false },
};
static const cwist_schema_t schema = { fields, 3 };
 
cwist_heal_config_t cfg = { .threshold = 0.8, .schema = &schema };
cwist_heal_result_t r   = cwist_json_heal(broken_input, &cfg);
if (r.json) {
    printf("healed(%d): %s\n  log: %s\n", r.level, r.json, r.log);
}
cwist_heal_result_free(&r);

Definition in file json_heal.h.

Macro Definition Documentation

CWIST_HEAL_LOG_MAX

#define CWIST_HEAL_LOG_MAX   512

Definition at line 108 of file json_heal.h.

CWIST_SCHEMA_MAX_ALIASES

#define CWIST_SCHEMA_MAX_ALIASES   8

Definition at line 49 of file json_heal.h.

Typedef Documentation

cwist_heal_config_t

typedef struct cwist_heal_config cwist_heal_config_t

Configuration passed to cwist_json_heal().

cwist_heal_result_t

typedef struct cwist_heal_result cwist_heal_result_t

Result of a healing attempt.

cwist_schema_field_t

typedef struct cwist_schema_field cwist_schema_field_t

Single field descriptor used by both the healer and the Zod validator.

aliases is a NULL-terminated list of alternative names that will be renamed to name during L2 alignment. Fuzzy (case-insensitive, separator-stripped) matching is applied when exact aliases do not match.

cwist_schema_t

typedef struct cwist_schema cwist_schema_t

A complete schema: array of field descriptors + count.

cwist_sllm_heal_fn

typedef char *(* cwist_sllm_heal_fn) (const char *broken_json, const cwist_schema_t *schema, void *userdata)

Optional deep-recovery callback (e.g. backed by an LLM).

Called only when L1 and L2 both fail to produce valid JSON. Must return a heap-allocated (plain malloc) JSON string, or NULL on failure. The caller will free the returned string with free(). The callback MUST use the standard C malloc allocator (not cwist_alloc) so that the framework can release it with free().

Parameters

broken_json	The damaged input string.
schema	Schema hint (may be NULL).
userdata	Opaque pointer from cwist_heal_config_t.

Returns

Heap-allocated recovered JSON string, or NULL.

Definition at line 89 of file json_heal.h.

Enumeration Type Documentation

cwist_field_type_t

enum cwist_field_type_t

Expected value type for a schema field.

Enumerator
CWIST_FIELD_STRING
CWIST_FIELD_INT
CWIST_FIELD_FLOAT
CWIST_FIELD_BOOL
CWIST_FIELD_OBJECT
CWIST_FIELD_ARRAY

Definition at line 40 of file json_heal.h.

Function Documentation

cwist_heal_result_free()

void cwist_heal_result_free

(

cwist_heal_result_t *

r

)

Free resources owned by a cwist_heal_result_t.

Free resources owned by a cwist_heal_result_t.

Parameters

r	Result object previously populated by cwist_json_heal().

Definition at line 584 of file json_heal.c.

References cap, and cwist_heal_result::json.

Referenced by cwist_db_insert_healed().

cwist_json_heal()

cwist_heal_result_t cwist_json_heal	(	const char *	input,
		const cwist_heal_config_t *	cfg
	)

Attempt to heal a potentially broken JSON string.

Tries L1 → L2 → L3 in order, stopping at the first successful parse whose confidence meets the threshold. If the input is already valid JSON it is returned verbatim (healed=false), though L2 alignment is still applied when a schema is provided.

Parameters

input	Raw (possibly broken) JSON string.
cfg	Healing configuration (may be NULL for defaults).

Returns

Heap-allocated result; caller must call cwist_heal_result_free().

Attempt to heal a potentially broken JSON string.

The function first attempts a direct parse, then falls back to the internal L1 syntax healer, and finally consults the user-provided SLLM callback when configured. Each successful step records the recovery level, confidence, and a short operator-facing log of the transformations that were applied.

Parameters

input	Raw JSON text that may contain structural defects.
cfg	Optional recovery configuration. NULL applies the built-in defaults.

Returns

Result structure describing the best recovery path that succeeded.

Definition at line 509 of file json_heal.c.

References cap, cwist_heal_result::confidence, cwist_free(), CWIST_HEAL_LOG_MAX, cwist_json_schema_align(), cwist_heal_result::healed, cwist_heal_result::json, cwist_heal_result::level, cwist_heal_result::log, cwist_heal_config::schema, cwist_heal_config::sllm_fn, cwist_heal_config::sllm_userdata, and cwist_heal_config::threshold.

Referenced by cwist_db_insert_healed().

cwist_json_schema_align()

int cwist_json_schema_align	(	cJSON *	obj,
		const cwist_schema_t *	schema,
		char *	log,
		size_t	log_sz
	)

Apply L2 schema alignment to an already-parsed cJSON object in place.

Renames aliased / fuzzy-matched field names to their canonical forms and coerces mismatched types (e.g. "123" → 123 for an INT field).

Parameters

obj	cJSON object to modify in place.
schema	Schema descriptor.
log	Optional output buffer for change description.
log_sz	Size of log buffer.

Returns

Number of fields modified, or -1 on error.

Apply L2 schema alignment to an already-parsed cJSON object in place.

For each schema field, locates the corresponding object member by canonical name, explicit alias, or fuzzy match; renames it to the canonical name when found under another key, and coerces its value to the schema's declared type (string/number/bool conversions). All edits and descriptions of each edit are applied directly to obj and log.

Parameters

obj	cJSON object to align; must be an object node.
schema	Field schema to enforce.
log	Optional recovery log (NULL-safe).
log_sz	Size of log in bytes.

Returns

Number of changes (renames + coercions) applied; negative on invalid arguments.

Definition at line 358 of file json_heal.c.

References cwist_schema_field::aliases, cap, CWIST_FIELD_ARRAY, CWIST_FIELD_BOOL, CWIST_FIELD_FLOAT, CWIST_FIELD_INT, CWIST_FIELD_OBJECT, CWIST_FIELD_STRING, CWIST_SCHEMA_MAX_ALIASES, cwist_schema::field_count, cwist_schema::fields, cwist_schema_field::name, and cwist_schema_field::type.

Referenced by cwist_json_heal().