JSON API

JSON5/JSON6 Parser and Manipulation Library

High-performance JSON parser and manipulation library for embedded IoT applications. Supports both traditional JSON and relaxed JSON5/JSON6 syntax with extended features for ease of use.

This library provides a complete JSON processing solution including:

Fast parsing of JSON/JSON5/JSON6 text into navigable tree structures
Insitu parsing of JSON text resulting in extremely efficient memory usage
Query API with dot-notation path support (e.g., "config.network.timeout")
Modification APIs for setting values and blending JSON objects
Serialization back to JSON text with multiple formatting options
Template expansion with ${path.var} variable substitution

JSON5/JSON6 Extended Features:

Unquoted object keys when they contain no special characters
Unquoted string values when they contain no spaces
Trailing commas in objects and arrays
Single-line (//) and multi-line comments
Multi-line strings using backtick quotes
JavaScript-style primitives (undefined, null)
Keyword 'undefined' support
Compacted output mode with minimal whitespace

The library is designed for embedded developers who need efficient JSON processing with minimal memory overhead and high performance characteristics.

The parser is lax and will tolerate some non-standard JSON syntax such as:

Multiple or trailing commas in objects and arrays.
An empty string is allowed and returns an empty JSON instance.
Similarly a top level whitespace string is allowed and returns an empty JSON instance.

Use another tool if you need strict JSON validation of input data.

Function Index

Json *	jsonAlloc(void)
	Allocate a new JSON object.
int	jsonBlend(Json dest, int did, cchar dkey, const Json src, int sid, cchar skey, int flags)
	Blend nodes by copying from one Json to another.
int	jsonCheckIteration(Json *json, int count, int nid)
	Check if the iteration is valid.
Json *	jsonClone(const Json *src, int flags)
	Clone a json object.
char *	jsonConvert(cchar *fmt, ...)
	Parse a string as JSON or JSON5 and convert into strict JSON string.
cchar *	jsonConvertBuf(char buf, size_t size, cchar fmt, ...)
	Convert a string into strict json string in a buffer.
void	jsonFree(Json *json)
	Free a JSON object and all associated memory.
cchar *	jsonGet(Json json, int nid, cchar key, cchar *defaultValue)
	Get a json node value as a string.
bool	jsonGetBool(Json json, int nid, cchar key, bool defaultValue)
	Get a json node value as a boolean.
JsonNode *	jsonGetChildNode(Json *json, int nid, int nth)
	Get the Nth child node for a json node.
char *	jsonGetClone(Json json, int nid, cchar key, cchar *defaultValue)
	Get a json node value as an allocated string.
Time	jsonGetDate(Json json, int nid, cchar key, int64 defaultValue)
	Get a json node value as a date.
double	jsonGetDouble(Json json, int nid, cchar key, double defaultValue)
	Get a json node value as a double.
cchar *	jsonGetError(Json *json)
	Get the error message from the JSON object.
int	jsonGetId(const Json json, int nid, cchar key)
	Get a json node ID.
int	jsonGetInt(Json json, int nid, cchar key, int defaultValue)
	Get a json node value as an integer.
ssize	jsonGetLength(Json json, int nid, cchar key)
	Get the length of a property value.
JsonNode *	jsonGetNode(const Json json, int nid, cchar key)
	Get a json node object.
int	jsonGetNodeId(const Json json, JsonNode node)
	Get a json node object ID.
int64	jsonGetNum(Json json, int nid, cchar key, int64 defaultValue)
	Get a json node value as a 64-bit integer.
cchar *	jsonGetRef(Json json, int nid, cchar key, cchar *defaultValue)
	Get a json node value as a string.
int	jsonGetType(Json json, int nid, cchar key)
	Get the value type for a node.
int	jsonGetUserFlags(Json *json)
	Get user-defined flags from a JSON object.
uint64	jsonGetValue(Json json, int nid, cchar key, cchar *defaultValue)
	Get a json node value as a uint64.
void	jsonLock(Json *json)
	Lock a json object from further updates.
Json *	jsonParse(cchar *text, int flags)
	Parse a json string into a json object.
Json *	jsonParseFile(cchar path, char *errorMsg, int flags)
	Load a JSON object from a filename.
Json *	jsonParseFmt(cchar *fmt, ...)
	Parse a formatted string into a json object.
Json *	jsonParseKeep(char *text, int flags)
	Parse a json string into a json object and assume ownership of the supplied text memory.
Json *	jsonParseString(cchar text, char *errorMsg, int flags)
	Parse a JSON string into an object tree and return any errors.
int	jsonParseText(Json json, char text, int flags)
	Parse a json string into an existing json object.
void	jsonPrint(Json *json)
	Print a JSON object.
int	jsonPutToBuf(RBuf buf, const Json json, int nid, int flags)
	Convert a json object to a serialized JSON representation in the given buffer.
void	jsonPutValueToBuf(RBuf buf, cchar value, int flags)
	Convert a string value primitive to a JSON string and add to the given buffer.
int	jsonRemove(Json obj, int nid, cchar key)
	Remove a Property from a JSON object.
int	jsonSave(Json obj, int nid, cchar key, cchar *path, int mode, int flags)
	Save a JSON object to a filename.
int	jsonSet(Json obj, int nid, cchar key, cchar *value, int type)
	Update a key/value in the JSON object with a string value.
int	jsonSetBool(Json obj, int nid, cchar key, bool value)
	Update a property in the JSON object with a boolean value.
int	jsonSetDate(Json json, int nid, cchar key, Time value)
	Update a property in the JSON object with date value.
int	jsonSetDouble(Json json, int nid, cchar key, double value)
	Update a property with a floating point number value.
int	jsonSetFmt(Json obj, int nid, cchar key, cchar *fmt, ...)
	Update a key/value in the JSON object with a formatted string value.
void	jsonSetIndent(int indent)
	Set the indent level for compacted output.
int	jsonSetJsonFmt(Json json, int nid, cchar key, cchar *fmt, ...)
	Update a key in the JSON object with a JSON object value passed as a JSON5 string.
void	jsonSetMaxLength(int length)
	Set the maximum length of a line for compacted output.
void	jsonSetNodeType(JsonNode *node, int type)
	Update a node type.
void	jsonSetNodeValue(JsonNode node, cchar value, int type, int flags)
	Directly update a node value.
int	jsonSetNumber(Json json, int nid, cchar key, int64 value)
	Update a property in the JSON object with a numeric value.
int	jsonSetString(Json json, int nid, cchar key, cchar *value)
	Update a property in the JSON object with a string value.
void	jsonSetUserFlags(Json *json, int flags)
	Set user-defined flags on a JSON object.
cchar *	jsonString(const Json *json, int flags)
	Serialize a JSON object into a string.
char *	jsonTemplate(Json json, cchar str, bool keep)
	Expand a string template with ${prop.prop...} references.
char *	jsonToString(const Json json, int nid, cchar key, int flags)
	Serialize a JSON object into a string.
void	jsonUnlock(Json *json)
	Unlock a json object to allow updates.

Typedef Index

Json	JSON Object.
JsonNode	JSON Node.

Defines

#define	ITERATE_JSON int pid = (int) ((parent ? parent : json->nodes) - json->nodes), nid = pid + 1, _count = json->count; \ (json->count > 0) && json->nodes && nid >= 0 && (nid < json->nodes[pid].last) && \ (child = &json->nodes[nid]) != 0; \ nid = jsonCheckIteration(json, _count, json->nodes[nid].last)
	These macros iterates over the children under the "parent" id.
#define	ITERATE_JSON_ID int nid = pid + 1, _count = json->count; \ (json->count > 0) && json->nodes && nid >= 0 && (nid < json->nodes[pid].last) && \ (child = &json->nodes[nid]) != 0; \ nid = jsonCheckIteration(json, _count, json->nodes[nid].last)
	Iterate over the children under a node identified by its ID.
#define	ITERATE_JSON_KEY int parentId = jsonGetId(json, baseId, key), nid = parentId + 1, _count = json->count; \ (json->count > 0) && json->nodes && nid >= 0 && (nid < json->nodes[parentId].last) && \ (child = &json->nodes[nid]) != 0; \ nid = jsonCheckIteration(json, _count, json->nodes[nid].last)
	Iterate over the children under a given key node.
#define	JSON_APPEND 0x4
	Default behavior: append to existing properties (equivalent to '+').
#define	JSON_ARRAY 0x2
	Array node containing indexed elements.
#define	JSON_BARE 0x4000
	Internal: render without quotes or brackets.
#define	JSON_CCREATE 0x10
	Default behavior: conditional create only if not existing (equivalent to '?').
#define	JSON_COMBINE 0x1
	JSON blending operation flags.
#define	JSON_COMMENT 0x4
	Comment node (JSON5 feature).
#define	JSON_COMPACT 0x10
	JSON rendering flags.
#define	JSON_DEBUG 0x2000
	Internal: enable debug-specific formatting.
#define	JSON_DEFAULT_INDENT 4
	Default indent level for json text.
#define	JSON_DOUBLE_QUOTES 0x20
	Use double quotes for strings and keys.
#define	JSON_ENCODE 0x40
	Encode control characters in strings.
#define	JSON_EXPAND 0x80
	Expand ${path.var} template references during rendering.
#define	JSON_EXPANDING 0x8000
	Internal parsing flags.
#define	JSON_EXPECT_COMMA 0x20000
	Internal: parsing and expect a comma.
#define	JSON_EXPECT_KEY 0x10000
	Internal: parsing and expect a property key name.
#define	JSON_EXPECT_VALUE 0x40000
	Internal: parsing and expect a value.
#define	JSON_JS (JSON_SINGLE_QUOTES)
	Composite formatting flags.
#define	JSON_JSON5 (JSON_SINGLE_QUOTES)
	JSON5 format allowing relaxed syntax.
#define	JSON_KEY 0x1000
	Internal rendering flags.
#define	JSON_MAX_LINE_LENGTH 120
	Default Maximum length of a line for compacted output.
#define	JSON_MULTILINE 0x100
	Format output across multiple lines for readability.
#define	JSON_OBJECT 0x1
	JSON node type constants.
#define	JSON_ONE_LINE 0x200
	Force all output onto a single line.
#define	JSON_OVERWRITE 0x2
	Default behavior: overwrite existing properties (equivalent to '=').
#define	JSON_PARSE_FLAGS 0xFF000
	Internal: parsing flags.
#define	JSON_PASS_VALUE 0x2
	Transfer string ownership to JSON object during parsing.
#define	JSON_PRIMITIVE 0x10
	Primitive values: true, false, null, undefined, numbers.
#define	JSON_QUOTE_KEYS 0x400
	Always quote object property keys.
#define	JSON_REGEXP 0x20
	Regular expression literal (JSON6 feature).
#define	JSON_REMOVE_UNDEF 0x20
	Remove properties with undefined (NULL) values during blend.
#define	JSON_REPLACE 0x8
	Default behavior: replace existing properties (equivalent to '-').
#define	JSON_SINGLE_QUOTES 0x800
	Use single quotes instead of double quotes.
#define	JSON_STRICT_PARSE 0x1
	JSON parsing flags.
#define	JSON_STRING 0x8
	String value including ISO date strings.
#define	ME_JSON_MAX_NODES 100000
	Maximum number of elements in json text.

Typedefs

Json

JSON Object.

Description:: The primary JSON container structure that holds a parsed JSON tree in memory. This structure provides efficient access to JSON data through a node-based tree representation.

Fields:

uint	count	Number of nodes currently used in the tree.
char *	end	Pointer to one byte past the end of the text buffer.
char *	error	Detailed error message from parsing failures.
uint	flags	Internal parser flags (reserved for library use).
uint	lineNumber	Current line number during parsing (for error reporting).
uint	lock	Lock flag preventing modifications when set.
char *	next	Current parsing position in the text buffer.
struct JsonNode *	nodes	Array of JSON nodes forming the tree structure.
char *	path	File path if JSON was loaded from a file (for error reporting).
char *	property	Internal buffer for building property names during parsing.
ssize	propertyLength	Current allocated size of the property buffer.
uint	size	Total allocated capacity of the nodes array.
char *	text	Original JSON text being parsed (will be modified during parsing).
uint	userFlags	Application-specific flags available for user use.
char *	value	Cached serialized string result from jsonString() calls.

API Stability:: Evolving.

JsonNode

JSON Node.

Description:: Individual node in the JSON tree representing a single property or value. Each node contains a name/value pair and maintains structural information about its position in the tree hierarchy.

Fields:

uint	allocatedName	True if name string was allocated and must be freed by JSON library.
uint	allocatedValue	True if value string was allocated and must be freed by JSON library.
int	last	Index + 1 of the last descendant node (defines subtree boundary).
char *	name	Property name (null-terminated string, NULL for array elements).
uint	type	Node type: JSON_OBJECT, JSON_ARRAY, JSON_STRING, JSON_PRIMITIVE, etc.
char *	value	Property value (null-terminated string representation).

API Stability:: Evolving.

Functions

Json * jsonAlloc (void )

Allocate a new JSON object.

Description:: Creates a new, empty JSON object ready for parsing or manual construction. The object is allocated using the R runtime and must be freed with jsonFree() when no longer needed. The initial object contains no nodes and is ready to accept JSON text via jsonParseText() or manual node construction via jsonSet() calls.

Returns:: A newly allocated JSON object, or NULL if allocation fails.

API Stability:: Evolving.

int jsonBlend (Json *dest, int did, cchar *dkey, const Json *src, int sid, cchar *skey, int flags)

Blend nodes by copying from one Json to another.

Description:: This performs an N-level deep clone of the source JSON nodes to be blended into the destination object. By default, this add new object properies and overwrite arrays and string values. The Property combination prefixes: '+', '=', '-' and '?' to append, overwrite, replace and conditionally overwrite are supported if the JSON_COMBINE flag is present.

Parameters:

dest	Destination json.
did	Base node ID from which to store the copied nodes.
dkey	Destination property name to search for.
src	Source json.
sid	Base node ID from which to copy nodes.
skey	Source property name to search for.
flags	The JSON_COMBINE flag enables Property name prefixes: '+', '=', '-', '?' to append, overwrite, replace and conditionally overwrite key values if not already present. When adding string properies, values will be appended using a space separator. Extra spaces will not be removed on replacement. Without JSON_COMBINE or for properies without a prefix, the default is to blend objects by creating new properies if not already existing in the destination, and to treat overwrite arrays and strings. Use the JSON_OVERWRITE flag to override the default appending of objects and rather overwrite existing properies. Use the JSON_APPEND flag to override the default of overwriting arrays and strings and rather append to existing properies.

Returns:: Zero if successful.

API Stability:: Evolving.

int jsonCheckIteration (Json *json, int count, int nid)

Check if the iteration is valid.

Parameters:

json	Json object.
count	Prior json count of nodes.
nid	Node id.

Returns:: Node id if valid, otherwise a negative error code.

API Stability:: Evolving.

Json * jsonClone (const Json *src, int flags)

Clone a json object.

Parameters:

src	Input json object.
flags	Reserved, set to zero.

Returns:: The copied JSON tree. Caller must free with jsonFree.

API Stability:: Evolving.

char * jsonConvert (cchar *fmt, ...)

Parse a string as JSON or JSON5 and convert into strict JSON string.

Parameters:

fmt	Printf style format string.
...	Args for format.

Returns:: A string. Returns NULL if the text will not parse. Caller must free.

API Stability:: Evolving.

cchar * jsonConvertBuf (char *buf, size_t size, cchar *fmt, ...)

Convert a string into strict json string in a buffer.

Parameters:

fmt	Printf style format string.
...	Args for format.
buf	Destination buffer.
size	Size of the destination buffer.

Returns:: The reference to the buffer.

API Stability:: Evolving.

void jsonFree (Json *json)

Free a JSON object and all associated memory.

Description:: Releases all memory associated with a JSON object including the node tree, text buffers, and any allocated strings. After calling this function, the JSON object and all references into it become invalid and must not be used.

Parameters:

json	JSON object to free. Can be NULL (no operation performed).

API Stability:: Evolving.

cchar * jsonGet (Json *json, int nid, cchar *key, cchar *defaultValue)

Get a json node value as a string.

Description:: This call returns a reference into the JSON storage. Such references are short-term and may not remain valid if other modifications are made to the JSON tree. Only use the result of this API while no other changes are made to the JSON object. Use jsonGet if you need to retain the queried value. If a key value is NULL or undefined, then the defaultValue will be returned.

Parameters:

json	Source json.
nid	Base node ID from which to examine. Set to zero for the top level.
key	Property name to search for. This may include ".". For example: "settings.mode".
defaultValue	If the key is not defined, return the defaultValue.

Returns:: The key value as a string or defaultValue if not defined. This is a reference into the JSON store. Caller must NOT free.

API Stability:: Evolving.

bool jsonGetBool (Json *json, int nid, cchar *key, bool defaultValue)

Get a json node value as a boolean.

Parameters:

json	Source json.
nid	Base node ID from which to examine. Set to zero for the top level.
key	Property name to search for. This may include ".". For example: "settings.mode".
defaultValue	If the key is not defined, return the defaultValue.

Returns:: The key value as a boolean or defaultValue if not defined.

API Stability:: Evolving.

JsonNode * jsonGetChildNode (Json *json, int nid, int nth)

Get the Nth child node for a json node.

Description:: Retrieves a specific child node by its index position within a parent node. This is useful for iterating through array elements or object properties in order. The child index is zero-based.

Parameters:

json	Source json.
nid	Base node ID to examine.
nth	Zero-based index of which child to return.

Returns:: The Nth child node object for the specified node. Returns NULL if the index is out of range.

API Stability:: Evolving.

char * jsonGetClone (Json *json, int nid, cchar *key, cchar *defaultValue)

Get a json node value as an allocated string.

Description:: This call returns an allocated string as the result. Use jsonGet as a higher performance API if you do not need to retain the queried value.

Parameters:

json	Source json.
nid	Base node ID from which to examine. Set to zero for the top level.
key	Property name to search for. This may include ".". For example: "settings.mode".
defaultValue	If the key is not defined, return a copy of the defaultValue. The defaultValue can be NULL in which case the return value will be an allocated empty string.

Returns:: An allocated string copy of the key value or defaultValue if not defined. Caller must free.

API Stability:: Evolving.

Time jsonGetDate (Json *json, int nid, cchar *key, int64 defaultValue)

Get a json node value as a date.

Parameters:

json	Source json.
nid	Base node ID from which to examine. Set to zero for the top level.
key	Property name to search for. This may include ".". For example: "settings.mode".
defaultValue	If the key is not defined, return the defaultValue.

Returns:: The key value as a date or defaultValue if not defined.

API Stability:: Evolving.

double jsonGetDouble (Json *json, int nid, cchar *key, double defaultValue)

Get a json node value as a double.

Parameters:

json	Source json.
nid	Base node ID from which to examine. Set to zero for the top level.
key	Property name to search for. This may include ".". For example: "settings.mode".
defaultValue	If the key is not defined, return the defaultValue.

Returns:: The key value as a double or defaultValue if not defined.

API Stability:: Evolving.

cchar * jsonGetError (Json *json)

Get the error message from the JSON object.

Parameters:

json	Json object.

Returns:: The error message. Caller must NOT free.

API Stability:: Evolving.

int jsonGetId (const Json *json, int nid, cchar *key)

Get a json node ID.

Parameters:

json	Source json.
nid	Base node ID from which to start the search. Set to zero for the top level.
key	Property name to search for. This may include ".". For example: "settings.mode".

Returns:: The node ID for the specified key.

API Stability:: Evolving.

int jsonGetInt (Json *json, int nid, cchar *key, int defaultValue)

Get a json node value as an integer.

Parameters:

json	Source json.
nid	Base node ID from which to examine. Set to zero for the top level.
key	Property name to search for. This may include ".". For example: "settings.mode".
defaultValue	If the key is not defined, return the defaultValue.

Returns:: The key value as an integer or defaultValue if not defined.

API Stability:: Evolving.

ssize jsonGetLength (Json *json, int nid, cchar *key)

Get the length of a property value.

If an array, return the array length. If an object, return the number of object properties

Parameters:

json	Json object.
nid	Node id.
key	Property name.

Returns:: Length of the property value, otherwise a negative error code.

API Stability:: Evolving.

JsonNode * jsonGetNode (const Json *json, int nid, cchar *key)

Get a json node object.

Description:: This call returns a reference into the JSON storage. Such references are not persistent if other modifications are made to the JSON tree.

Parameters:

json	Source json.
nid	Base node ID from which to start the search. Set to zero for the top level.
key	Property name to search for. This may include ".". For example: "settings.mode".

Returns:: The node object for the specified key. Returns NULL if not found.

API Stability:: Evolving.

int jsonGetNodeId (const Json *json, JsonNode *node)

Get a json node object ID.

Description:: This call returns the node ID for a node. Such references are not persistent if other modifications are made to the JSON tree.

Parameters:

json	Source json.
node	Node reference.

Returns:: The node ID.

API Stability:: Evolving.

int64 jsonGetNum (Json *json, int nid, cchar *key, int64 defaultValue)

Get a json node value as a 64-bit integer.

Parameters:

json	Source json.
nid	Base node ID from which to examine. Set to zero for the top level.
key	Property name to search for. This may include ".". For example: "settings.mode".
defaultValue	If the key is not defined, return the defaultValue.

Returns:: The key value as a 64-bit integer or defaultValue if not defined.

API Stability:: Evolving.

cchar * jsonGetRef (Json *json, int nid, cchar *key, cchar *defaultValue)

Get a json node value as a string.

Description:: This call is DEPRECATED. Use jsonGet or jsonGetClone instead. This call returns a reference into the JSON storage. Such references are short-term and may not remain valid if other modifications are made to the JSON tree. Only use the result of this API while no other changes are made to the JSON object. Use jsonGet if you need to retain the queried value.

Parameters:

json	Source json.
nid	Base node ID from which to examine. Set to zero for the top level.
key	Property name to search for. This may include ".". For example: "settings.mode".
defaultValue	If the key is not defined, return the defaultValue.

Returns:: The key value as a string or defaultValue if not defined. This is a reference into the JSON store. Caller must NOT free.

API Stability:: Deprecated.

int jsonGetType (Json *json, int nid, cchar *key)

Get the value type for a node.

Description:: Determines the type of a JSON node, which indicates how the value should be interpreted. This is essential for type-safe access to JSON values.

Parameters:

json	Source json.
nid	Base node ID from which to start the search.
key	Property name to search for. This may include ".". For example: "settings.mode".

Returns:: The data type. Set to JSON_OBJECT, JSON_ARRAY, JSON_COMMENT, JSON_STRING, JSON_PRIMITIVE or JSON_REGEXP.

API Stability:: Evolving.

int jsonGetUserFlags (Json *json)

Get user-defined flags from a JSON object.

Description:: Retrieves the current value of application-specific flags from the JSON object. These flags are managed entirely by the user application.

Parameters:

json	JSON object to query.

Returns:: Current user flags value (8-bit value).

API Stability:: Evolving.

uint64 jsonGetValue (Json *json, int nid, cchar *key, cchar *defaultValue)

Get a json node value as a uint64.

Description:: Parse the stored value with unit suffixes and returns a number. The following suffixes are supported: sec, secs, second, seconds, min, mins, minute, minutes, hr, hrs, hour, hours, day, days, week, weeks, month, months, year, years, byte, bytes, k, kb, m, mb, g, gb. Also supports the strings: unlimited, infinite, never, forever.

Parameters:

json	Source json.
nid	Base node ID from which to examine. Set to zero for the top level.
key	Property name to search for. This may include ".". For example: "settings.mode".
defaultValue	If the key is not defined, return the defaultValue.

Returns:: The key value as a uint64 or defaultValue if not defined.

API Stability:: Evolving.

void jsonLock (Json *json)

Lock a json object from further updates.

Description:: This call is useful to block all further updates via jsonSet. The jsonGet API returns a references into the JSON tree. Subsequent updates can grow the internal JSON structures and thus move references returned earlier.

Parameters:

json	A json object.

API Stability:: Evolving.

Json * jsonParse (cchar *text, int flags)

Parse a json string into a json object.

Description:: Use this method if you are sure the supplied JSON text is valid or do not need to receive diagnostics of parse failures other than the return value.

Parameters:

text	Json string to parse.
flags	Set to JSON_JSON to parse json, otherwise a relaxed JSON5 syntax is supported. Call jsonLock() to lock the JSON tree to prevent further modification via jsonSet or jsonBlend. This will make returned references via jsonGet and jsonGetNode stable.

Returns:: Json object if successful. Caller must free via jsonFree. Returns null if the text will not parse.

API Stability:: Evolving.

Json * jsonParseFile (cchar *path, char **errorMsg, int flags)

Load a JSON object from a filename.

Description:: Reads and parses a JSON file from disk into a JSON object tree. This is a convenience function that combines file reading with JSON parsing. If parsing fails, detailed error information is provided.

Parameters:

path	Filename path containing a JSON string to load.
errorMsg	Error message string set if the parse fails. Caller must not free.
flags	Set to JSON_JSON to parse json, otherwise a relaxed JSON5 syntax is supported.

Returns:: JSON object tree. Caller must free via jsonFree(). Returns NULL on error.

API Stability:: Evolving.

Json * jsonParseFmt (cchar *fmt, ...)

Parse a formatted string into a json object.

Description:: Convenience function that formats a printf-style string and then parses it as JSON. This is useful for constructing JSON from dynamic values without manual string building.

Parameters:

fmt	Printf style format string.
...	Args for format.

Returns:: A json object. Caller must free via jsonFree().

API Stability:: Evolving.

Json * jsonParseKeep (char *text, int flags)

Parse a json string into a json object and assume ownership of the supplied text memory.

Description:: This is an optimized version of jsonParse that avoids copying the text to be parsed. The ownership of the supplied text is transferred to the Json object and will be freed when jsonFree is called. The caller must not free the text which will be freed by this function. Use this method if you are sure the supplied JSON text is valid or do not need to receive diagnostics of parse failures other than the return value.

Parameters:

text	Json string to parse. Caller must NOT free.
flags	Set to JSON_JSON to parse json, otherwise a relaxed JSON5 syntax is supported. Call jsonLock() to lock the JSON tree to prevent further modification via jsonSet or jsonBlend. This will make returned references via jsonGet and jsonGetNode stable.

Returns:: Json object if successful. Caller must free via jsonFree. Returns null if the text will not parse.

API Stability:: Evolving.

Json * jsonParseString (cchar *text, char **errorMsg, int flags)

Parse a JSON string into an object tree and return any errors.

Description:: Deserializes a JSON string created into an object. The top level of the JSON string must be an object, array, string, number or boolean value.

Parameters:

text	JSON string to deserialize.
errorMsg	Error message string set if the parse fails. Caller must not free.
flags	Set to JSON_JSON to parse json, otherwise a relaxed JSON5 syntax is supported.

Returns:: Returns a tree of Json objects. Each object represents a level in the JSON input stream. Caller must free errorMsg via rFree on errors.

API Stability:: Evolving.

int jsonParseText (Json *json, char *text, int flags)

Parse a json string into an existing json object.

Description:: Use this method if you need to have access to the error message if the parse fails.

Parameters:

json	Existing json object to parse into.
text	Json string to parse.
flags	Set to JSON_JSON to parse json, otherwise a relaxed JSON5 syntax is supported. Call jsonLock() to lock the JSON tree to prevent further modification via jsonSet or jsonBlend. This will make returned references via jsonGet and jsonGetNode stable.

Returns:: Json object if successful. Caller must free via jsonFree. Returns null if the text will not parse.

API Stability:: Evolving.

void jsonPrint (Json *json)

Print a JSON object.

Description:: Prints a JSON object in a compact human readable format.

Parameters:

json	Source json.

API Stability:: Evolving.

int jsonPutToBuf (RBuf *buf, const Json *json, int nid, int flags)

Convert a json object to a serialized JSON representation in the given buffer.

Parameters:

buf	Destination buffer.
json	Json object.
nid	Base node ID from which to convert. Set to zero for the top level.
flags	Json flags.

API Stability:: Evolving.

void jsonPutValueToBuf (RBuf *buf, cchar *value, int flags)

Convert a string value primitive to a JSON string and add to the given buffer.

Parameters:

buf	Destination buffer.
value	String value to convert.
flags	Json flags.

API Stability:: Evolving.

int jsonRemove (Json *obj, int nid, cchar *key)

Remove a Property from a JSON object.

Description:: Removes one or more properties from a JSON object based on the specified key path. The key path supports dot notation for nested property removal. This operation modifies the JSON tree in place.

Parameters:

obj	Parsed JSON object returned by jsonParse.
nid	Base node ID from which to start searching for key. Set to zero for the top level.
key	Property name to remove. This may include ".". For example: "settings.mode".

Returns:: Returns zero if successful, otherwise a negative error code.

API Stability:: Evolving.

int jsonSave (Json *obj, int nid, cchar *key, cchar *path, int mode, int flags)

Save a JSON object to a filename.

Description:: Serializes a JSON object (or a portion of it) to a file on disk. The output format is controlled by the flags parameter. The file is created with the specified permissions mode.

Parameters:

obj	Parsed JSON object returned by jsonParse.
nid	Base node ID from which to start searching for key. Set to zero for the top level.
key	Property name to save. Set to NULL to save the entire object. This may include ".". For example: "settings.mode".
path	Filename path to contain the saved JSON string.
mode	File permissions mode (e.g., 0644).
flags	Rendering flags - same as for jsonToString().

Returns:: Zero if successful, otherwise a negative error code.

API Stability:: Evolving.

int jsonSet (Json *obj, int nid, cchar *key, cchar *value, int type)

Update a key/value in the JSON object with a string value.

Description:: This call takes a multipart Property name and will operate at any level of depth in the JSON object.

Parameters:

obj	Parsed JSON object returned by jsonParse.
nid	Base node ID from which to start search for key. Set to zero for the top level.
key	Property name to add/update. This may include ".". For example: "settings.mode".
value	Character string value.
type	Set to JSON_ARRAY, JSON_OBJECT, JSON_PRIMITIVE or JSON_STRING.

Returns:: Positive node id if updated successfully. Otherwise a negative error code.

API Stability:: Evolving.

int jsonSetBool (Json *obj, int nid, cchar *key, bool value)

Update a property in the JSON object with a boolean value.

Description:: This call takes a multipart Property name and will operate at any level of depth in the JSON object.

Parameters:

obj	Parsed JSON object returned by jsonParse.
nid	Base node ID from which to start search for key. Set to zero for the top level.
key	Property name to add/update. This may include ".". For example: "settings.mode".
value	Boolean string value.

Returns:: Positive node id if updated successfully. Otherwise a negative error code.

API Stability:: Evolving.

int jsonSetDate (Json *json, int nid, cchar *key, Time value)

Update a property in the JSON object with date value.

Description:: This call takes a multipart Property name and will operate at any level of depth in the JSON object.

Parameters:

json	Parsed JSON object returned by jsonParse.
nid	Base node ID from which to start search for key. Set to zero for the top level.
key	Property name to add/update. This may include ".". For example: "settings.mode".
value	Date value expressed as a Time (Elapsed milliseconds since Jan 1, 1970).

Returns:: Positive node id if updated successfully. Otherwise a negative error code.

API Stability:: Evolving.

int jsonSetDouble (Json *json, int nid, cchar *key, double value)

Update a property with a floating point number value.

Description:: This call takes a multipart Property name and will operate at any level of depth in the JSON object.

Parameters:

json	Parsed JSON object returned by jsonParse.
nid	Base node ID from which to start search for key. Set to zero for the top level.
key	Property name to add/update. This may include ".". For example: "settings.mode".
value	Double floating point value.

Returns:: Positive node id if updated successfully. Otherwise a negative error code.

API Stability:: Evolving.

int jsonSetFmt (Json *obj, int nid, cchar *key, cchar *fmt, ...)

Update a key/value in the JSON object with a formatted string value.

Description:: The type of the inserted value is determined from the contents. This call takes a multipart property name and will operate at any level of depth in the JSON object.

Parameters:

obj	Parsed JSON object returned by jsonParse.
nid	Base node ID from which to start search for key. Set to zero for the top level.
key	Property name to add/update. This may include ".". For example: "settings.mode".
fmt	Printf style format string.
...	Args for format.

Returns:: Positive node id if updated successfully. Otherwise a negative error code.

API Stability:: Evolving.

void jsonSetIndent (int indent)

Set the indent level for compacted output.

Parameters:

indent

Indent level for compacted output.

API Stability:: Evolving.

int jsonSetJsonFmt (Json *json, int nid, cchar *key, cchar *fmt, ...)

Update a key in the JSON object with a JSON object value passed as a JSON5 string.

Parameters:

json	Parsed JSON object returned by jsonParse.
nid	Base node ID from which to start search for key. Set to zero for the top level.
key	Property name to add/update. This may include ".". For example: "settings.mode".
fmt	JSON string.
...	Args for format.

Returns:: Zero if updated successfully. Otherwise a negative error code.

API Stability:: Evolving.

void jsonSetMaxLength (int length)

Set the maximum length of a line for compacted output.

Parameters:

length

Maximum length of a line for compacted output.

API Stability:: Evolving.

void jsonSetNodeType (JsonNode *node, int type)

Update a node type.

Description:: This is an internal API and is subject to change without notice. It offers a higher performance path to update node types.

Parameters:

node	Json node.
type	Json node type.

API Stability:: Internal.

void jsonSetNodeValue (JsonNode *node, cchar *value, int type, int flags)

Directly update a node value.

Description:: This is an internal API and is subject to change without notice. It offers a higher performance path to update node values.

Parameters:

node	Json node.
value	String value to update with.
type	Json node type.
flags	Set to JSON_PASS_VALUE to transfer ownership of a string. JSON will then free.

API Stability:: Internal.

int jsonSetNumber (Json *json, int nid, cchar *key, int64 value)

Update a property in the JSON object with a numeric value.

Description:: This call takes a multipart Property name and will operate at any level of depth in the JSON object.

Parameters:

json	Parsed JSON object returned by jsonParse.
nid	Base node ID from which to start search for key. Set to zero for the top level.
key	Property name to add/update. This may include ".". For example: "settings.mode".
value	Number to update.

Returns:: Positive node id if updated successfully. Otherwise a negative error code.

API Stability:: Evolving.

int jsonSetString (Json *json, int nid, cchar *key, cchar *value)

Update a property in the JSON object with a string value.

Parameters:

json	Parsed JSON object returned by jsonParse.
nid	Base node ID from which to start search for key. Set to zero for the top level.
key	Property name to add/update. This may include ".". For example: "settings.mode".
value	String value.

Returns:: Positive node id if updated successfully. Otherwise a negative error code.

API Stability:: Evolving.

void jsonSetUserFlags (Json *json, int flags)

Set user-defined flags on a JSON object.

Description:: Sets application-specific flags in the userFlags field of the JSON object. These flags are reserved for user applications and are not used by the JSON library. Useful for tracking application state or marking JSON objects with custom attributes.

Parameters:

json	JSON object to modify.
flags	User-defined flags (8-bit value).

API Stability:: Evolving.

cchar * jsonString (const Json *json, int flags)

Serialize a JSON object into a string.

Description:: Serializes a top level JSON object created via jsonParse into a characters string in JSON format. This serialize the result into the json->value so the caller does not need to free the result.

Parameters:

json	Source json.
flags	Serialization flags. Supported flags include JSON_HUMAN for a human-readable multiline format. Use JSON_JSON for a strict JSON format. Use JSON_QUOTES to wrap property names in quotes. Defaults to JSON_HUMAN if set to zero.

Returns:: Returns a serialized JSON character string. Caller must NOT free. The string is owned by the json object and will be overwritten by subsequent calls to jsonString. It will be freed when jsonFree is called.

API Stability:: Evolving.

char * jsonTemplate (Json *json, cchar *str, bool keep)

Expand a string template with ${prop.prop...} references.

Description:: Unexpanded references left as is.

Parameters:

json	Json object.
str	String template to expand.
keep	If true, unexpanded references are retained as ${token}, otherwise removed.

Returns:: An allocated expanded string. Caller must free.

API Stability:: Evolving.

char * jsonToString (const Json *json, int nid, cchar *key, int flags)

Serialize a JSON object into a string.

Description:: Serializes a top level JSON object created via jsonParse into a characters string in JSON format.

Parameters:

json	Source json.
nid	Base node ID from which to convert. Set to zero for the top level.
key	Property name to serialize below. This may include ".". For example: "settings.mode".
flags	Serialization flags. Supported flags include JSON_JSON5 and JSON_HUMAN. Use JSON_JSON for a strict JSON format. Defaults to JSON_HUMAN if set to zero.

Returns:: Returns a serialized JSON character string. Caller must free.

API Stability:: Evolving.

void jsonUnlock (Json *json)

Unlock a json object to allow updates.

Parameters:

json	A json object.

API Stability:: Evolving.

Files

AI

Database

URL HTTP Client

Safe Runtime

Web Server

Configuration

Man Pages

JSON API

Function Index

Typedef Index

Defines

Typedefs

Functions

Configuration

JSON API ​

Function Index ​

Typedef Index ​

Defines ​

Typedefs ​

Functions ​

JSON API

Function Index

Typedef Index

Defines

Typedefs

Functions