Lite³
A JSON-Compatible Zero-Copy Serialization Format
Loading...
Searching...
No Matches
JSON Conversion

Table of Contents

Introduction

The previous guide showed iterators. This guide will be about JSON conversion.

JSON is loved by many due to being human readable, simple to understand and able to represent complex data relationships.

Lite³, being a binary format, is not easily read directly. However to honor these beneficial properties, Lite³ implements JSON Conversion functions.

The goal of this example is to find the densest element in the periodic table, then export this element as a JSON document. For the periodic table, a JSON dataset will be used: examples/periodic_table.json

This example will go through a number of steps:

  1. Converting a JSON file to Lite³ format
  2. Iterating over the Lite³ data to find the densest element
  3. Converting from Lite³ to JSON in two different ways

Any guesses what the densest element is?

Example Code

This guide is based on an example inside the Lite³ repository found in examples/context_api/07-json-conversion.c with a dataset from examples/periodic_table.json:

1/*
2 Lite³: A JSON-Compatible Zero-Copy Serialization Format
3
4 Copyright © 2025 Elias de Jong <elias@fastserial.com>
5
6 Permission is hereby granted, free of charge, to any person obtaining a copy
7 of this software and associated documentation files (the "Software"), to deal
8 in the Software without restriction, including without limitation the rights
9 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
10 copies of the Software, and to permit persons to whom the Software is
11 furnished to do so, subject to the following conditions:
12
13 The above copyright notice and this permission notice shall be included in all
14 copies or substantial portions of the Software.
15
16 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
22 SOFTWARE.
23
24 __ __________________ ____
25 _ ___ ___/ /___(_)_/ /_______|_ /
26 _ _____/ / __/ /_ __/ _ \_/_ <
27 ___ __/ /___/ / / /_ / __/____/
28 /_____/_/ \__/ \___/
29*/
30#include <stdio.h>
31#include <string.h>
32#include <stdlib.h>
33
34#include "lite3_context_api.h"
35
36
37int main() {
38 lite3_ctx *ctx = lite3_ctx_create();
39 if (!ctx) {
40 perror("Failed to create lite3_ctx *ctx");
41 return 1;
42 }
43
44 // Convert JSON file to Lite³
45 if (lite3_ctx_json_dec_file(ctx, "examples/periodic_table.json") < 0) {
46 perror("Failed to decode JSON document");
47 return 1;
48 }
49
50 // Iterator to find densest element
51 size_t data_ofs;
52 if (lite3_ctx_get_arr(ctx, 0, "data", &data_ofs) < 0) {
53 perror("Failed to get data array");
54 return 1;
55 }
56 lite3_iter iter;
57 if (lite3_ctx_iter_create(ctx, data_ofs, &iter) < 0) {
58 perror("Failed to create iterator");
59 return 1;
60 }
61 size_t el_ofs;
62 size_t el_densest_ofs = 0;
63 double el_densest_kg_per_m3 = 0.0;
64 int ret;
65 while ((ret = lite3_ctx_iter_next(ctx, &iter, NULL, &el_ofs)) == LITE3_ITER_ITEM) {
66 if (lite3_ctx_is_null(ctx, el_ofs, "density_kg_per_m3")) {
67 continue;
68 }
69 double kg_per_m3;
70 if (lite3_ctx_get_f64(ctx, el_ofs, "density_kg_per_m3", &kg_per_m3) < 0) {
71 perror("Failed to get element density");
72 return 1;
73 }
74 if (kg_per_m3 > el_densest_kg_per_m3) {
75 el_densest_ofs = el_ofs;
76 el_densest_kg_per_m3 = kg_per_m3;
77 }
78 }
79 if (ret < 0) {
80 perror("Failed to get iter element");
81 return 1;
82 }
83 if (el_densest_ofs == 0) {
84 perror("Failed to find densest element");
85 return 1;
86 }
87
88 lite3_str name;
89 if (lite3_ctx_get_str(ctx, el_densest_ofs, "name", &name) < 0) {
90 perror("Failed to get densest element name");
91 return 1;
92 }
93 printf("densest element: %s\n\n", LITE3_STR(ctx->buf, name));
94
95 printf("Convert Lite³ to JSON by returned heap pointer (prettified):\n");
96 size_t json_len;
97 char *json = lite3_ctx_json_enc_pretty(ctx, el_densest_ofs, &json_len);
98 if (!json) {
99 perror("Failed encode JSON");
100 return 1;
101 }
102 printf("%s\n\n", json);
103 free(json);
104
105 printf("Convert Lite³ to JSON by writing to buffer (non-prettified):\n");
106 size_t json_buf_size = 1024;
107 char *json_buf = malloc(json_buf_size);
108 int64_t ret_i64;
109 if ((ret_i64 = lite3_ctx_json_enc_buf(ctx, el_densest_ofs, json_buf, json_buf_size)) < 0) {
110 perror("Failed encode JSON");
111 return 1;
112 }
113 size_t json_buf_len = (size_t)ret_i64;
114 printf("%s\n", json_buf);
115 printf("json bytes written: %zu\n", json_buf_len);
116 free(json_buf);
117
118 lite3_ctx_destroy(ctx);
119 return 0;
120}
lite3_ctx_get_str
#define lite3_ctx_get_str(ctx, ofs, key, out)
Get string value by key.
Definition lite3_context_api.h:1725
lite3_ctx_get_f64
#define lite3_ctx_get_f64(ctx, ofs, key, out)
Get floating point value by key.
Definition lite3_context_api.h:1652
lite3_ctx_get_arr
#define lite3_ctx_get_arr(ctx, ofs, key, out)
Get array by key.
Definition lite3_context_api.h:1799
lite3_ctx_iter_create
static int lite3_ctx_iter_create(lite3_ctx *ctx, size_t ofs, lite3_iter *out)
Create a lite3 iterator for the given object or array.
Definition lite3_context_api.h:2055
lite3_ctx_iter_next
static int lite3_ctx_iter_next(lite3_ctx *ctx, lite3_iter *iter, lite3_str *out_key, size_t *out_val_ofs)
Get the next item from a lite3 iterator.
Definition lite3_context_api.h:2082
lite3_ctx_json_enc_buf
static int64_t lite3_ctx_json_enc_buf(lite3_ctx *ctx, size_t ofs, char *__restrict json_buf, size_t json_bufsz)
Convert Lite³ to JSON and write to output buffer.
Definition lite3_context_api.h:2278
lite3_ctx_json_dec_file
static int lite3_ctx_json_dec_file(lite3_ctx *ctx, const char *__restrict path)
Convert JSON from file path to Lite³
Definition lite3_context_api.h:2163
lite3_ctx_json_enc_pretty
static char * lite3_ctx_json_enc_pretty(lite3_ctx *ctx, size_t ofs, size_t *__restrict out_len)
Convert Lite³ to JSON prettified string.
Definition lite3_context_api.h:2260
lite3_ctx_create
static lite3_ctx * lite3_ctx_create(void)
Create context with minimum size.
Definition lite3_context_api.h:214
lite3_ctx_destroy
void lite3_ctx_destroy(lite3_ctx *ctx)
Destroy context.
Definition ctx_api.c:229
lite3_ctx_is_null
#define lite3_ctx_is_null(ctx, ofs, key)
Find value by key and test for null type.
Definition lite3_context_api.h:1331
LITE3_ITER_ITEM
#define LITE3_ITER_ITEM
Return value of lite3_iter_next(); iterator produced an item, continue;.
Definition lite3.h:2616
LITE3_STR
#define LITE3_STR(buf, val)
Generational pointer / safe access wrapper.
Definition lite3.h:666
lite3_context_api.h
Lite³ Context API Header.
lite3_ctx
Lite³ context struct.
Definition lite3_context_api.h:140
lite3_iter
Struct containing iterator state.
Definition lite3.h:2626
lite3_str
Struct holding a reference to a string inside a Lite³ buffer.
Definition lite3.h:601

Output:

densest element: Osmium
Convert Lite³ to JSON by returned heap pointer (prettified):
{
"atomic_radius": {
"calculated_pm": 185,
"van_der_waals_pm": null,
"covalent_pm": 128
},
"electron_config": "[Xe] 6s2 4f14 5d6",
"atomic_weight": 190.23,
"density_kg_per_m3": 22590.0,
"isotopes_count": 35,
"ionization_energy_kJ_per_mol": 840.0,
"series": "Transition",
"symbol": "Os",
"thermal_conductivity_W_per_mK": 88.0,
"oxidation_states": [
"-2",
"1",
"2",
"3",
"4c",
"5",
"6",
"7",
"8"
],
"discovery_year": 1803,
"valence": 8,
"electronegativity": 2.2,
"heat": {
"specific_J_per_kgK": 130.0,
"fusion_kJ_per_mol": 31.0,
"vaporization_kJ_per_mol": 630.0
},
"name": "Osmium",
"abundance_percent": {
"crust": 1.8e-7,
"ocean": null,
"universe": 3e-7,
"human_body": null
},
"electron_affinity_kJ_per_mol": 106.1,
"boiling_point_K": 5285.0,
"melting_point_K": 3306.0,
"atomic_number": 76
}
Convert Lite³ to JSON by writing to buffer (non-prettified):
{"atomic_radius":{"calculated_pm":185,"van_der_waals_pm":null,"covalent_pm":128},"electron_config":"[Xe] 6s2 4f14 5d6","atomic_weight":190.23,"density_kg_per_m3":22590.0,"isotopes_count":35,"ionization_energy_kJ_per_mol":840.0,"series":"Transition","symbol":"Os","thermal_conductivity_W_per_mK":88.0,"oxidation_states":["-2","1","2","3","4c","5","6","7","8"],"discovery_year":1803,"valence":8,"electronegativity":2.2,"heat":{"specific_J_per_kgK":130.0,"fusion_kJ_per_mol":31.0,"vaporization_kJ_per_mol":630.0},"name":"Osmium","abundance_percent":{"crust":1.8e-7,"ocean":null,"universe":3e-7,"human_body":null},"electron_affinity_kJ_per_mol":106.1,"boiling_point_K":5285.0,"melting_point_K":3306.0,"atomic_number":76}
json bytes written: 716

Explanation

We will walk through the example code step-by-step, explaining the use of Lite³ library functions.

Lite³ messages are just bytes, stored contiguously inside a buffer. If you want to allocate these messages inside your own custom allocators, you can using the Buffer API. However in this guide, we will be using the Context API so that memory is managed automatically.

Note that Lite³ is a binary format, but the examples print message data as JSON to stdout for better readability.

Converting JSON file to Lite³

As explained in the first guide, we use contexts to store Lite³ buffers (see: Context API):

lite3_ctx *ctx = lite3_ctx_create();
if (!ctx) {
perror("Failed to create lite3_ctx *ctx");
return 1;
}

This context is now ready to store the dataset, but first we have to convert the JSON document to Lite³ using one of the JSON Conversion functions:

// Convert JSON file to Lite³
if (lite3_ctx_json_dec_file(ctx, "examples/periodic_table.json") < 0) {
perror("Failed to decode JSON document");
return 1;
}
Note
Here JSON is being converted from a file path, but you can also convert from a regular string using lite3_ctx_json_dec(). Converting from a file pointer is also possible through lite3_ctx_json_dec_fp().

Finding densest element

The next step is to find the densest element inside the periodic table. For this, we use an iterator to loop over all the elements, keeping track of the density for each.

The elements are contained in the "data" subfield, so after obtaining the offset for this field, we create the iterator:

// Iterator to find densest element
size_t data_ofs;
if (lite3_ctx_get_arr(ctx, 0, "data", &data_ofs) < 0) {
perror("Failed to get data array");
return 1;
}
lite3_iter iter;
if (lite3_ctx_iter_create(ctx, data_ofs, &iter) < 0) {
perror("Failed to create iterator");
return 1;
}

Now comes the looping part:

size_t el_ofs;
size_t el_densest_ofs = 0;
double el_densest_kg_per_m3 = 0.0;
int ret;
while ((ret = lite3_ctx_iter_next(ctx, &iter, NULL, &el_ofs)) == LITE3_ITER_ITEM) {
if (lite3_ctx_is_null(ctx, el_ofs, "density_kg_per_m3")) {
continue;
}
double kg_per_m3;
if (lite3_ctx_get_f64(ctx, el_ofs, "density_kg_per_m3", &kg_per_m3) < 0) {
perror("Failed to get element density");
return 1;
}
if (kg_per_m3 > el_densest_kg_per_m3) {
el_densest_ofs = el_ofs;
el_densest_kg_per_m3 = kg_per_m3;
}
}
if (ret < 0) {
perror("Failed to get iter element");
return 1;
}
if (el_densest_ofs == 0) {
perror("Failed to find densest element");
return 1;
}

Iterators were explained in the previous guide. This loop will read the density of each element. Everytime a greater density is found, it is stored alongside the element offset in these variables:

size_t el_densest_ofs = 0;
double el_densest_kg_per_m3 = 0.0;

To some, this while condition may seem strange:

int ret;
while ((ret = lite3_ctx_iter_next(ctx, &iter, NULL, &el_ofs)) == LITE3_ITER_ITEM)

But if you pay attention to the parentheses, this is just a way of comparing the return value while still storing it for error handling:

if (ret < 0) {
perror("Failed to get iter element");
return 1;
}

If a message is corrupted, invalid or other wise damaged, it is important to know as early as possible. Otherwise, your iterator could unexpectedly stop halfway and it might 'appear to work' for long enough until your problems enter production.

Another remark is that not all elements in the dataset actually contain a density field ("density_kg_per_m3"). This is because some elements are highly unstable and have only ever existed for milliseconds or less. Therefore, their density has never been measured. Reading an null value would cause the program to exit, since lite3_ctx_get_f64() is expecting a double type. So we filter out these elements by checking for null, to skip the current loop iteration:

if (lite3_ctx_is_null(ctx, el_ofs, "density_kg_per_m3")) {
continue;
}

Printing the densest element

After all that work, the object of the densest element has been found, with the offset being stored inside el_densest_ofs.

Every element also contains a "name" field that is readable:

lite3_str name;
if (lite3_ctx_get_str(ctx, el_densest_ofs, "name", &name) < 0) {
perror("Failed to get densest element name");
return 1;
}
printf("densest element: %s\n\n", LITE3_STR(ctx->buf, name));

Output:

densest element: Osmium

Did you know this?

Convert to JSON by returned heap pointer

Now that the densest element has been found, we want to create a separate JSON document containing only the information about this element.

Remember that the entire periodic table dataset currently is stored inside the context (ctx) as Lite³. If you want to convert Lite³ to JSON, you do not need to convert the entire message. Instead, it is possible to selectively convert only a sub-object or array. In this case, we only want to target the Osmium element. To do this, we target the el_densest_ofs offset at which it is stored:

printf("Convert Lite³ to JSON by returned heap pointer (prettified):\n");
size_t json_len;
char *json = lite3_ctx_json_enc_pretty(ctx, el_densest_ofs, &json_len);
if (!json) {
perror("Failed encode JSON");
return 1;
}
printf("%s\n\n", json);
free(json);
Warning
Do not forget to free() heap pointers returned by lite3_ctx_json_enc() and lite3_ctx_json_enc_pretty().

Output:

Convert Lite³ to JSON by returned heap pointer (prettified):
{
"atomic_radius": {
"calculated_pm": 185,
"van_der_waals_pm": null,
"covalent_pm": 128
},
"electron_config": "[Xe] 6s2 4f14 5d6",
"atomic_weight": 190.23,
"density_kg_per_m3": 22590.0,
"isotopes_count": 35,
"ionization_energy_kJ_per_mol": 840.0,
"series": "Transition",
"symbol": "Os",
"thermal_conductivity_W_per_mK": 88.0,
"oxidation_states": [
"-2",
"1",
"2",
"3",
"4c",
"5",
"6",
"7",
"8"
],
"discovery_year": 1803,
"valence": 8,
"electronegativity": 2.2,
"heat": {
"specific_J_per_kgK": 130.0,
"fusion_kJ_per_mol": 31.0,
"vaporization_kJ_per_mol": 630.0
},
"name": "Osmium",
"abundance_percent": {
"crust": 1.8e-7,
"ocean": null,
"universe": 3e-7,
"human_body": null
},
"electron_affinity_kJ_per_mol": 106.1,
"boiling_point_K": 5285.0,
"melting_point_K": 3306.0,
"atomic_number": 76
}

The conversion was successful! Note that the 'prettified' JSON was obtained to make it easily readble. If you want minified JSON, you can use the lite3_ctx_json_enc() function.

Convert to JSON by writing to buffer

Instead of obtaining a heap pointer, sometimes you may want to write the converted JSON data directly to some buffer.

This is where functions lite3_ctx_json_enc_buf() and lite3_ctx_json_enc_pretty_buf() come in. The caller passes their target buffer as parameter, and the output JSON will be written directly up to the maximum specified size.

It is possible for the caller to pass a buffer that is too small. In that case, the operation will fail. There are two possible return values:

  • >= 0 on success (number of bytes written)
  • < 0 on error

Here we temporarily allocate a heap buffer, but you can pass any buffer you want:

printf("Convert Lite³ to JSON by writing to buffer (non-prettified):\n");
size_t json_buf_size = 1024;
char *json_buf = malloc(json_buf_size);
int64_t ret_i64;
if ((ret_i64 = lite3_ctx_json_enc_buf(ctx, el_densest_ofs, json_buf, json_buf_size)) < 0) {
perror("Failed encode JSON");
return 1;
}
size_t json_buf_len = (size_t)ret_i64;
printf("%s\n", json_buf);
printf("json bytes written: %zu\n", json_buf_len);
free(json_buf);

Output:

Convert Lite³ to JSON by writing to buffer (non-prettified):
{"atomic_radius":{"calculated_pm":185,"van_der_waals_pm":null,"covalent_pm":128},"electron_config":"[Xe] 6s2 4f14 5d6","atomic_weight":190.23,"density_kg_per_m3":22590.0,"isotopes_count":35,"ionization_energy_kJ_per_mol":840.0,"series":"Transition","symbol":"Os","thermal_conductivity_W_per_mK":88.0,"oxidation_states":["-2","1","2","3","4c","5","6","7","8"],"discovery_year":1803,"valence":8,"electronegativity":2.2,"heat":{"specific_J_per_kgK":130.0,"fusion_kJ_per_mol":31.0,"vaporization_kJ_per_mol":630.0},"name":"Osmium","abundance_percent":{"crust":1.8e-7,"ocean":null,"universe":3e-7,"human_body":null},"electron_affinity_kJ_per_mol":106.1,"boiling_point_K":5285.0,"melting_point_K":3306.0,"atomic_number":76}
json bytes written: 716

Now the non-prettified version was used, so the JSON is not very readable and takes up a large horizontal line.

Note that lite3_ctx_json_enc_buf() returns an int64_t value. This value must checked for error handling, then cast to (size_t) before storing json_buf_len.

Cleaning up

We are good citizens, so we clean up after ourselves:

lite3_ctx_destroy(ctx);

This destroys the context, freeing all the internal buffers so that the memory is released. When you create contexts, don't forget to destroy them, or else you will be leaking memory.

Conclusion

This was the seventh guide showing JSON conversion.

This is the end of the How-to Guide series, showing all the essential functions for getting started with Lite³.

If you still have questions, consider the mailing list as explained in the README.