JSONC is a C++23 JSON with Comments library. The C++ API is header-only, while the repository also provides optional compiled static or shared libraries for the C API. Both CMake and xmake build systems are kept in the repository.
- Header-only C++ API.
- JSON and JSONC document support.
- Ordered and unordered object models.
- Optional comment preservation for JSONC documents.
- Optional compiled C API for embedding in C or mixed-language projects.
- Configurable error model: exceptions, std::expected, or no-exception parsing.
- CMake and xmake build support.
- Optional static and shared library outputs for the C API.
The repository contains two layers:
- Header-only C++ library in
include/jsonc. - Optional compiled C API bridge in
src/jsonc.cppwith headers ininclude/jsonc-c.
If you only use the C++ API, you do not need to build the project. Build output is only required when you want the exported C API library.
The main C++ entry points are defined in include/jsonc/jsonc.hpp:
sculk::jsonc::json: unordered JSON without comment support.sculk::jsonc::ordered_json: ordered JSON without comment support.sculk::jsonc::jsonc: unordered JSONC with comment support.sculk::jsonc::ordered_jsonc: ordered JSONC with comment support.
Use the JSONC variants when you need to preserve or edit comments.
The library supports three error-handling styles:
- Default exception-based behavior.
JSONC_USE_EXPECTED: returnsstd::expected-based results.JSONC_NO_EXCEPTION: disables exceptions for parse paths that support non-throwing results.
If JSONC_USE_EXPECTED is enabled, JSONC_NO_EXCEPTION is enabled automatically.
- CMake 3.24 or newer.
- A compiler with C++23 support.
- Windows: MSVC or LLVM/Clang with a compatible generator.
- Linux/macOS: Clang is the intended toolchain in the original project settings.
This repository keeps both CMake and xmake build files.
For C++ usage, the library can be consumed directly from the headers:
#include <jsonc/jsonc.hpp>No compilation step is required unless you need the C API library.
cmake -S . -B build -DJSONC_BUILD_C_API=ON -DJSONC_LIBRARY_KIND=static -DJSONC_ENABLE_TEST=OFF
cmake --build build --config Releasecmake -S . -B build-shared -DJSONC_BUILD_C_API=ON -DJSONC_LIBRARY_KIND=shared -DJSONC_ENABLE_TEST=OFF
cmake --build build-shared --config Releasecmake -S . -B build-header -DJSONC_BUILD_C_API=OFF -DJSONC_ENABLE_TEST=OFFcmake -S . -B build-test -DJSONC_BUILD_C_API=OFF -DJSONC_ENABLE_TEST=ON
cmake --build build-test --config ReleaseJSONC_BUILD_C_API=ON|OFF: builds or skips the compiled C API library.JSONC_LIBRARY_KIND=static|shared: selects the library type.JSONC_ENABLE_TEST=ON|OFF: enables or disables thetesttarget.
The CMake targets are:
JSONC::jsonc: header-only C++ target.JSONC::capi: compiled C API target, available whenJSONC_BUILD_C_API=ON.
When building the shared C API library, the build copies the produced binary to bin/jsonc-<platform>-<arch> and creates a zip package in artifacts.
xmake f -m release --kind=static --enable_test=false
xmakexmake f -m release --kind=shared --enable_test=false
xmakexmake f -m release --kind=static --enable_test=true
xmakeFor header-only C++ usage:
add_subdirectory(path/to/JSONC)
target_link_libraries(your_target PRIVATE JSONC::jsonc)For the compiled C API library:
add_subdirectory(path/to/JSONC)
target_link_libraries(your_target PRIVATE JSONC::capi)#include <jsonc/jsonc.hpp>
#include <iostream>
int main() {
auto result = sculk::jsonc::ordered_jsonc::parse(R"({
// value comment
"value": 42,
"list": [1, 2, 3]
})", false, false);
#ifdef JSONC_USE_EXPECTED
if (!result) {
std::cerr << result.error().mErrorInfo << '\n';
return 1;
}
auto doc = *result;
#else
auto doc = result;
#endif
doc["value"] = 64;
doc["added"] = sculk::jsonc::ordered_jsonc::array({1, 2, 3, 4});
std::cout << doc.dump(4, false, false, true) << '\n';
}The C API is available in include/jsonc-c/jsonc.h.
It is implemented in the compiled library target and exposes parsing, querying, mutation, dumping, and memory management helpers for objects, arrays, and scalar values.
Typical C API flow:
- Parse content with
jsonc_parse_content. - Query or mutate values through the object/array helpers.
- Serialize with
jsonc_variant_dump,jsonc_object_dump, orjsonc_array_dump. - Release allocated handles with the matching
jsonc_free_*function.
include/jsonc: header-only public C++ library.include/jsonc-c: public C headers.src: compiled C API bridge sources.test: test and usage examples.artifacts: packaged shared-library outputs.bin: copied runtime outputs.
- Both CMake and xmake are intentionally retained.
- The C++ API is header-only; building is only required for the C API library and test executable.
- Building the C API library is optional and disabled by default.
Feedback is very welcome.
- Report bugs, ask questions, or suggest improvements via Issues: https://github.com/SculkCatalystMC/JSONC/issues
- Submit fixes and enhancements via Pull Requests: https://github.com/SculkCatalystMC/JSONC/pulls
For PRs, focused changes with a short explanation are preferred.
This project is licensed under the Mozilla Public License 2.0 (MPL-2.0). See the full text in LICENSE.
Core MPL-2.0 requirements (summary):
- If you modify MPL-covered files and distribute them, those modified files must remain under MPL-2.0.
- You must keep existing copyright and license notices in covered source files.
- If you distribute binaries/executables, you must make the corresponding covered source code available.
- You may combine this project with code under other licenses in a larger work, as long as MPL obligations for covered files are respected.
This summary is for convenience only. The LICENSE file is the authoritative legal text.