zod.h File Reference

Strict JSON schema validation (Zod-style) for CWIST. More...

#include <cwist/core/utils/json_heal.h>
#include <cjson/cJSON.h>
#include <stdbool.h>

Include dependency graph for zod.h:

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

Go to the source code of this file.

Classes
struct	cwist_zod_error
	A single validation failure. More...
struct	cwist_zod_result
	Result returned by cwist_zod_validate() / cwist_zod_parse(). More...

Macros
#define	CWIST_ZOD_MAX_ERRORS   32
#define	CWIST_ZOD_FIELD_MAX   64
#define	CWIST_ZOD_MSG_MAX   256

Typedefs
typedef struct cwist_zod_error	cwist_zod_error_t
	A single validation failure.
typedef struct cwist_zod_result	cwist_zod_result_t
	Result returned by cwist_zod_validate() / cwist_zod_parse().

Functions
cwist_zod_result_t	cwist_zod_validate (const cJSON *json, const cwist_schema_t *schema)
	Strictly validate an already-parsed cJSON object against a schema.
cwist_zod_result_t	cwist_zod_parse (const char *raw, const cwist_schema_t *schema, cJSON **out)
	Parse a raw JSON string and validate it in one step.
void	cwist_zod_print_errors (const cwist_zod_result_t *r)
	Print all validation errors to stderr.

Detailed Description

Strict JSON schema validation (Zod-style) for CWIST.

Unlike the self-healing layer, this module rejects data that does not conform to the schema. Use it at trust boundaries (HTTP API inputs, DB writes) where silent coercion is undesirable.

It shares the cwist_schema_t / cwist_schema_field_t types defined in json_heal.h so the same schema descriptor can drive both healing and strict validation.

Usage:

cwist_zod_result_t r = cwist_zod_parse(raw_body, &my_schema, &parsed);
if (!r.valid) {
    cwist_zod_print_errors(&r);
    // respond 400
}
// use parsed …
cJSON_Delete(parsed);

Definition in file zod.h.

Macro Definition Documentation

CWIST_ZOD_FIELD_MAX

#define CWIST_ZOD_FIELD_MAX   64

Definition at line 37 of file zod.h.

CWIST_ZOD_MAX_ERRORS

#define CWIST_ZOD_MAX_ERRORS   32

Definition at line 36 of file zod.h.

CWIST_ZOD_MSG_MAX

#define CWIST_ZOD_MSG_MAX   256

Definition at line 38 of file zod.h.

Typedef Documentation

cwist_zod_error_t

typedef struct cwist_zod_error cwist_zod_error_t

A single validation failure.

cwist_zod_result_t

typedef struct cwist_zod_result cwist_zod_result_t

Result returned by cwist_zod_validate() / cwist_zod_parse().

Function Documentation

cwist_zod_parse()

cwist_zod_result_t cwist_zod_parse	(	const char *	raw,
		const cwist_schema_t *	schema,
		cJSON **	out
	)

Parse a raw JSON string and validate it in one step.

On success *out is set to the parsed cJSON tree; the caller must call cJSON_Delete(*out) when done. On failure *out is set to NULL.

Parameters

raw	Null-terminated JSON string.
schema	Schema descriptor.
out	[out] Parsed cJSON tree on success, NULL otherwise.

Returns

Validation result. Check result.valid AND *out != NULL.

Parse a raw JSON string and validate it in one step.

Parameters

raw	Raw JSON text to parse.
schema	Expected field list and type requirements.
out	Optional output pointer that receives the parsed cJSON object on success.

Returns

Validation result containing success flag and collected errors.

Definition at line 112 of file zod.c.

References cap, cwist_zod_validate(), and cwist_zod_result::valid.

Referenced by cwist_db_insert_healed().

cwist_zod_print_errors()

void cwist_zod_print_errors

(

const cwist_zod_result_t *

r

)

Print all validation errors to stderr.

Print all validation errors to stderr.

Parameters

r	Validation result to print.

Definition at line 146 of file zod.c.

References cap, cwist_zod_result::error_count, cwist_zod_result::errors, cwist_zod_error::field, and cwist_zod_error::message.

Referenced by cwist_db_insert_healed().

cwist_zod_validate()

cwist_zod_result_t cwist_zod_validate	(	const cJSON *	json,
		const cwist_schema_t *	schema
	)

Strictly validate an already-parsed cJSON object against a schema.

Checks:

• All required fields are present.
• All fields that appear in the schema have the declared type.

No type coercion is performed; use cwist_json_heal() first if coercion is acceptable.

Parameters

json	cJSON object (not array / primitive).
schema	Schema descriptor.

Returns

Validation result. result.valid == true iff all checks pass.

Strictly validate an already-parsed cJSON object against a schema.

Parameters

json	Parsed JSON object to inspect.
schema	Expected field list and type requirements.

Returns

Validation result containing success flag and collected errors.

Definition at line 65 of file zod.c.

References cap, CWIST_ZOD_MSG_MAX, cwist_schema::field_count, cwist_schema::fields, cwist_schema_field::name, cwist_schema_field::required, cwist_schema_field::type, and cwist_zod_result::valid.

Referenced by cwist_db_query_strict(), and cwist_zod_parse().