Jsmn is a world fastest JSON parser/tokenizer. This is the official repo replacing the old one at Bitbucket



Build Status

jsmn (pronounced like 'jasmine') is a minimalistic JSON parser in C. It can be easily integrated into resource-limited or embedded projects.

You can find more information about JSON format at json.org

Library sources are available at https://github.com/zserge/jsmn

The web page with some information about jsmn can be found at http://zserge.com/jsmn.html


Most JSON parsers offer you a bunch of functions to load JSON data, parse it and extract any value by its name. jsmn proves that checking the correctness of every JSON packet or allocating temporary objects to store parsed JSON fields often is an overkill.

JSON format itself is extremely simple, so why should we complicate it?

jsmn is designed to be robust (it should work fine even with erroneous data), fast (it should parse data on the fly), portable (no superfluous dependencies or non-standard C extensions). And of course, simplicity is a key feature - simple code style, simple algorithm, simple integration into other projects.


  • compatible with C89
  • no dependencies (even libc!)
  • highly portable (tested on x86/amd64, ARM, AVR)
  • about 200 lines of code
  • extremely small code footprint
  • API contains only 2 functions
  • no dynamic memory allocation
  • incremental single-pass parsing
  • library code is covered with unit-tests


The rudimentary jsmn object is a token. Let's consider a JSON string:

'{ "name" : "Jack", "age" : 27 }'

It holds the following tokens:

  • Object: { "name" : "Jack", "age" : 27} (the whole object)
  • Strings: "name", "Jack", "age" (keys and some values)
  • Number: 27

In jsmn, tokens do not hold any data, but point to token boundaries in JSON string instead. In the example above jsmn will create tokens like: Object [0..31], String [3..7], String [12..16], String [20..23], Number [27..29].

Every jsmn token has a type, which indicates the type of corresponding JSON token. jsmn supports the following token types:

  • Object - a container of key-value pairs, e.g.: { "foo":"bar", "x":0.3 }
  • Array - a sequence of values, e.g.: [ 1, 2, 3 ]
  • String - a quoted sequence of chars, e.g.: "foo"
  • Primitive - a number, a boolean (true, false) or null

Besides start/end positions, jsmn tokens for complex types (like arrays or objects) also contain a number of child items, so you can easily follow object hierarchy.

This approach provides enough information for parsing any JSON data and makes it possible to use zero-copy techniques.


Download jsmn.h, include it, done.

#include "jsmn.h"

jsmn_parser p;
jsmntok_t t[128]; /* We expect no more than 128 JSON tokens */

r = jsmn_parse(&p, s, strlen(s), t, 128);

Since jsmn is a single-header, header-only library, for more complex use cases you might need to define additional macros. #define JSMN_STATIC hides all jsmn API symbols by making them static. Also, if you want to include jsmn.h from multiple C files, to avoid duplication of symbols you may define JSMN_HEADER macro.

/* In every .c file that uses jsmn include only declarations: */
#include "jsmn.h"

/* Additionally, create one jsmn.c file for jsmn implementation: */
#include "jsmn.h"


Token types are described by jsmntype_t:

typedef enum {
} jsmntype_t;

Note: Unlike JSON data types, primitive tokens are not divided into numbers, booleans and null, because one can easily tell the type using the first character:

  • 't', 'f' - boolean
  • 'n' - null
  • '-', '0'..'9' - number

Token is an object of jsmntok_t type:

typedef struct {
	jsmntype_t type; // Token type
	int start;       // Token start position
	int end;         // Token end position
	int size;        // Number of child (nested) tokens
} jsmntok_t;

Note: string tokens point to the first character after the opening quote and the previous symbol before final quote. This was made to simplify string extraction from JSON data.

All job is done by jsmn_parser object. You can initialize a new parser using:

jsmn_parser parser;
jsmntok_t tokens[10];


// js - pointer to JSON string
// tokens - an array of tokens available
// 10 - number of tokens available
jsmn_parse(&parser, js, strlen(js), tokens, 10);

This will create a parser, and then it tries to parse up to 10 JSON tokens from the js string.

A non-negative return value of jsmn_parse is the number of tokens actually used by the parser. Passing NULL instead of the tokens array would not store parsing results, but instead the function will return the number of tokens needed to parse the given string. This can be useful if you don't know yet how many tokens to allocate.

If something goes wrong, you will get an error. Error will be one of these:

  • JSMN_ERROR_INVAL - bad token, JSON string is corrupted
  • JSMN_ERROR_NOMEM - not enough tokens, JSON string is too large
  • JSMN_ERROR_PART - JSON string is too short, expecting more JSON data

If you get JSMN_ERROR_NOMEM, you can re-allocate more tokens and call jsmn_parse once more. If you read json data from the stream, you can periodically call jsmn_parse and check if return value is JSMN_ERROR_PART. You will get this error until you reach the end of JSON data.

Other info

This software is distributed under MIT license, so feel free to integrate it in your commercial products.

  • Problem with multiple definitions on C++

    Problem with multiple definitions on C++

    Hi, I'm using JSMN in an Arduino project using C++, including it in a header file which gets called in multiple files on the project. The only way I could get it to work is if I modify the jsmn_init and jsmn_parse by adding the inline tag (doing so seems to work ok for now). My questions are:

    • Is there a problem with this approach?
    • If not, is there a reason for these functions not to include it by default?
    • If there is, what would be the best way to include this changes in some official capacity? As it seems like a very basic problem (although very easily solvable), at least for C++ development. Maybe a small notice in the library description?
    opened by the-mush 19
  • Modernize


    After years of inactivity, I decided to keep jsmn up-to-date with the modern expectations of how a tiny library should look like.

    So far API has not been changed, but jsmn is now a single-header, header-only library, with fixed formatting rules and a linter (that already complains a lot).

    opened by zserge 12
  • heap buffer overflow on some inputs

    heap buffer overflow on some inputs

    We found a heap buffer overflow bug on jsondump with our fuzzing tool FOT's semantic related functionality, with the following commands (memory leak of jsondump we think is not a big issue):

    export ASAN_OPTIONS=detect_leaks=0
    CFLAGS="-O3 -g -fsanitize=address" LDFLAGS="-fsanitize=address" make jsondump

    One simple test case is as follows, which is mutated based on library.json.

      "name": "jsmn",
      "keywords": "json",
      "description": "Minimalistic JSON parser/tokenizer in C. It : "jsmn",
    can be easily integrated into resource-limited or embedded projects",
        "type": "git",
        "url": "https://github.com/zserge/jsmn.git"
      "frameworks": "*",
      "platforms": "*",
      "examples": [
      "exclude": "test"

    The error output is:

    ==28237==ERROR: AddressSanitizer: heap-buffer-overflow on address 0x615000000280 at pc 0x00000050cad3 bp 0x7ffd1eb95810 sp 0x7ffd1eb95808
    READ of size 4 at 0x615000000280 thread T0
        #0 0x50cad2 in dump /home/hongxu/tests/jsmn/example/jsondump.c:33:9
        #1 0x50c9d5 in dump /home/hongxu/tests/jsmn/example/jsondump.c:44:9
        #2 0x50bed3 in main /home/hongxu/tests/jsmn/example/jsondump.c:120:4
        #3 0x7faee422e1c0 in __libc_start_main /build/glibc-itYbWN/glibc-2.26/csu/../csu/libc-start.c:308
        #4 0x41c5d9 in _start (/home/hongxu/tests/jsmn/jsondump+0x41c5d9)
    0x615000000280 is located 0 bytes to the right of 512-byte region [0x615000000080,0x615000000280)
    allocated by thread T0 here:
        #0 0x4d2045 in realloc (/home/hongxu/tests/jsmn/jsondump+0x4d2045)
        #1 0x50bdbc in realloc_it /home/hongxu/tests/jsmn/example/jsondump.c:15:12
        #2 0x50bdbc in main /home/hongxu/tests/jsmn/example/jsondump.c:113
        #3 0x7faee422e1c0 in __libc_start_main /build/glibc-itYbWN/glibc-2.26/csu/../csu/libc-start.c:308
    SUMMARY: AddressSanitizer: heap-buffer-overflow /home/hongxu/tests/jsmn/example/jsondump.c:33:9 in dump
    Shadow bytes around the buggy address:
      0x0c2a7fff8000: fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa
      0x0c2a7fff8010: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
      0x0c2a7fff8020: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
      0x0c2a7fff8030: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
      0x0c2a7fff8040: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
    =>0x0c2a7fff8050:[fa]fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa
      0x0c2a7fff8060: fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa
      0x0c2a7fff8070: fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa
      0x0c2a7fff8080: fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa
      0x0c2a7fff8090: fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa
      0x0c2a7fff80a0: fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa fa
    Shadow byte legend (one shadow byte represents 8 application bytes):
      Addressable:           00
      Partially addressable: 01 02 03 04 05 06 07 
      Heap left redzone:       fa
      Freed heap region:       fd
      Stack left redzone:      f1
      Stack mid redzone:       f2
      Stack right redzone:     f3
      Stack after return:      f5
      Stack use after scope:   f8
      Global redzone:          f9
      Global init order:       f6
      Poisoned by user:        f7
      Container overflow:      fc
      Array cookie:            ac
      Intra object redzone:    bb
      ASan internal:           fe
      Left alloca redzone:     ca
      Right alloca redzone:    cb

    There are other input tests that can trigger this bug with similar root cause (*.input.txt is the input file, and *.err.txt is the error output). w01_000011,sig:6,Splice:3:16,src:w02_000052.err.txt w01_000011,sig:6,Splice:3:16,src:w02_000052.input.txt w02_000003,sig:6,Havoc:21:35,src:w01_000052.err.txt w02_000003,sig:6,Havoc:21:35,src:w01_000052.input.txt

    opened by HongxuChen 12
  • Make jsmntype_t values bit flags

    Make jsmntype_t values bit flags

    This way one can easily check whether a token is either of multiple types, e.g.:

    if (token.type & (JSMN_ARRAY | JSMN_OBJECT))
    	// do stuff with array or object
    opened by olmokramer 11
  • jsmn: declare struct names to allow forward decls

    jsmn: declare struct names to allow forward decls

    Both jsmntok_t and jsmn_parser are declared as anonymous structures that are typedeffed to their actual name. This forces all downstream users of jsmn to always use the typedef name, instead of using e.g. struct jsmn_parser. While this might be considered a matter of taste, using typedefs only has the technical downside of disallowing forward declarations. E.g. if a dependent whishes to declare a pointer to jsmntok_t without actually pulling in the "jsmn.h" header, then he is not able to do so because there is no way in C to provide a forward declaration for typedefs to anonymous structs.

    Fix this by providing names for both jsmntok_t and jsmn_parser structures.

    opened by pks-t 8
  • Parser pass invalid JSON when PARENT_LINKS is enabled

    Parser pass invalid JSON when PARENT_LINKS is enabled

    jsmn parser pass the following wrong JSON message when JSMN_PARENT_LINKS is enabled:

    test case

    int main()
      int ret;
      char *json = "\"key 1\": 1234}";
      jsmntok_t *tokens;
      jsmn_parser parser;
      tokens = calloc(32, sizeof(jsmntok_t));
      ret = jsmn_parse(&parser, json, strlen(json), tokens, 32);
      printf("ret=%i\n", ret);
      return 0;

    With JSMN_PARENT_LINKS set, the parser returns 2, when disabled it returns -2 (expected).

    opened by edsiper 8
  • issues with there being no jsmn.c

    issues with there being no jsmn.c

    src/lib/jsmn/jsmn.h(456): Warning! W202: Symbol 'jsmn_init' has been defined, but not referenced src/lib/jsmn/jsmn.h(265): Warning! W202: Symbol 'jsmn_parse' has been defined, but not referenced

    this is with #define JSMN_STATIC in 16_map.h

    it is for https://github.com/sparky4/16/

    opened by sparky4 7
  • Running on Embedded Systems

    Running on Embedded Systems

    Hello, I am not able to parse files longer that 10 lines on my microcontroller. The microcontroller I am using is PIC32MZ. It has Program size meomry: 2048 & SRAM:512. When I have a large file program is not able to give any results. Can anyone please give suggestions on how I can proceed?

    Thank you.

    Regards, Mitun

    opened by mitunchidamparam 6
  • Does jsmn support parsing group with key, value pair. Example for parsing group with key, value pair

    Does jsmn support parsing group with key, value pair. Example for parsing group with key, value pair

    Can you let me know, if a group with key, value pair is supported.

    For example, if I have a json file, that is read by my program, and lets say the contents of the json file is below: { "plat_conf": { "ip_addr": "", "port_num": "4444" }

    The program simple.c, under example directory, has an example of a group that has an array of strings.

    I tried to modify simple.c, to parse a group with key, value pair, and ran into issues.

    Can you please let me know below:

    1. Does jsmn support parsing group with key, value pair.
    2. If yes, can you please update simple.c, by adding a group with key, value pair, in JSON_STRING in that program.
    opened by sudharkrish 6
  • JSON parsing error

    JSON parsing error

    I get a json parsing error in this case '{"value":"What is my "Presence"","condition":"equal"}' this is failing double quotes are not handled properly.

    opened by RanjithEy-Kore 6
  • [jsmnerr_t] Enum size on embedded devices.

    [jsmnerr_t] Enum size on embedded devices.

    With a STM32F1xx and the GCC compiler, the enum size is forced on 1 byte. With large JSONs, the number of tokens can't be greater than 127, otherwise the result is negative. One solution is to force the enum on 2 bytes like this:

    typedef enum {
        /* Not enough tokens were provided */
        /* Invalid character inside JSON string */
        /* The string is not a full JSON packet, more bytes expected */
    } jsmnerr_t;

    2 bytes means 32,767 tokens, enough on the most cases?

    opened by JeremieRapin 6
  • Missing commas does not fail in strict mode

    Missing commas does not fail in strict mode

    The following test fails in strict mode:

    check(parse("{\"a\": \"a\" \"b\":\"b\"}", JSMN_ERROR_INVAL, 5));

    Surely this should result in JSMN_ERROR_INVAL?

    opened by nrbrook 1
  • Building the project with cmake

    Building the project with cmake


    To ensure that the project is platform independent, I added three cmake files to it.

    Here are the standard steps to build the project:

    • create a specific directory where cmake will store its output, conventionally 'build'.
    • from this repository, enter this command to create the build structure: 'cmake '
    • and then 'to actually build the whole project and its six executables: 'make'

    The tests can be run with "make test'.

    I also ported the project to google test, which will come later on.

    Thanks for your time!


    opened by jpfeger 0
  • Combine json_alloc_token and json_fill_token

    Combine json_alloc_token and json_fill_token

    JSMN has been initializing tokens with default values, then initializing them again with the real values. The first step can be skipped to make JSMN smaller and faster.

    opened by alexhenrie 3
  • Not returning proper count when used with tokens=NULL and stream data

    Not returning proper count when used with tokens=NULL and stream data

    Hello, past few days I'm testing JSMN with stream data and NULL token parameter.

    Simple example

    static const char *JSON_STRING = "{\"user\": \"johndoe\", \"admin\": false}";
    uint8_t bigarray[500];
    int i=0;
    int j=0;
    int r;
    jsmn_parser p;
    jsmntok_t t[10]; /* We expect no more than 10 tokens */
    r = jsmn_parse(&p, JSON_STRING, strlen(JSON_STRING), NULL, 0);
    printf("parse full JSON: %d\n", r);
        bigarray[j] = JSON_STRING[i]; //get from fifo
        r = jsmn_parse(&p, bigarray, j+1, NULL, 0);
        printf("i=%d, ch=%c, ", j, bigarray[j]);           
        printf("r=%d ", r);           
        fwrite(bigarray, 1, j+1, stdout);
    printf("parse stream JSON: %d\n", r);

    So, the output is

    parse full JSON: 5 i=0, ch={, r=1 { i=1, ch=", r=-3 {" i=2, ch=u, r=-3 {"u i=3, ch=s, r=-3 {"us i=4, ch=e, r=-3 {"use i=5, ch=r, r=-3 {"user i=6, ch=", r=1 {"user" i=7, ch=:, r=0 {"user": i=8, ch= , r=0 {"user": i=9, ch=", r=-3 {"user": " i=10, ch=j, r=-3 {"user": "j i=11, ch=o, r=-3 {"user": "jo i=12, ch=h, r=-3 {"user": "joh i=13, ch=n, r=-3 {"user": "john i=14, ch=d, r=-3 {"user": "johnd i=15, ch=o, r=-3 {"user": "johndo i=16, ch=e, r=-3 {"user": "johndoe i=17, ch=", r=1 {"user": "johndoe" i=18, ch=,, r=0 {"user": "johndoe", i=19, ch= , r=0 {"user": "johndoe", i=20, ch=", r=-3 {"user": "johndoe", " i=21, ch=a, r=-3 {"user": "johndoe", "a i=22, ch=d, r=-3 {"user": "johndoe", "ad i=23, ch=m, r=-3 {"user": "johndoe", "adm i=24, ch=i, r=-3 {"user": "johndoe", "admi i=25, ch=n, r=-3 {"user": "johndoe", "admin i=26, ch=", r=1 {"user": "johndoe", "admin" i=27, ch=:, r=0 {"user": "johndoe", "admin": i=28, ch= , r=0 {"user": "johndoe", "admin": i=29, ch=f, r=1 {"user": "johndoe", "admin": f i=30, ch=a, r=1 {"user": "johndoe", "admin": fa i=31, ch=l, r=1 {"user": "johndoe", "admin": fal i=32, ch=s, r=1 {"user": "johndoe", "admin": fals i=33, ch=e, r=1 {"user": "johndoe", "admin": false i=34, ch=}, r=0 {"user": "johndoe", "admin": false} parse stream JSON: 0

    Mind that JSMN_STRICT should be defined, because in other case false is decoded like bunch of primitives! But that is not the point.

    From the output you can see that with tokens=NULL, the returned count is 1 when new token is found, not the found tokens so far. I've managed to locate that in jsmn.h in jsmn_parse function -> int count = parser->toknext;. So whit NULL, toknext is never updated and the returned count always starts from 0.

    Workaround is to use jsmn_init(&p) in every iteration. But it waste time in checking entire buffer .

    opened by givanov256 1
  • Allow JSMN_API to be defined by the user (e. g. for Windows DLLs).

    Allow JSMN_API to be defined by the user (e. g. for Windows DLLs).

    To make jsmn part of a shared Windows-DLL, jsmn's functions have to be marked __declspec(dllexport) / __declscpec(dllimport). Functions marked as extern are - contrary to unix - not automatically exported.

    Making JSMN_API user-definable (with a default fallback) makes writing wrapper such as these possible:


    #ifdef _WIN32
    #   define JSMN_API __declspec(dllexport)
    #define JSMN_STRICT
    #include "jsmn.h"


    #ifdef _WIN32
    #  ifdef EXPORTS
    #     define JSMN_API __declspec(dllexport)
    #  else
    #     define JSMN_API __declspec(dllimport)
    #  endif
    #define JSMN_HEADER
    #include "jsmn.h"
    #undef JSMN_HEADER
    opened by lx-s 0
Serge Zaitsev
Turning complex problems into a lightweight and simple software solutions.
Serge Zaitsev
A C++, header-only library for constructing JSON and JSON-like data formats, with JSON Pointer, JSON Patch, JSON Schema, JSONPath, JMESPath, CSV, MessagePack, CBOR, BSON, UBJSON

JSONCONS jsoncons is a C++, header-only library for constructing JSON and JSON-like data formats such as CBOR. For each supported data format, it enab

Daniel Parker 492 May 9, 2022
Ultralightweight JSON parser in ANSI C

cJSON Ultralightweight JSON parser in ANSI C. Table of contents License Usage Welcome to cJSON Building Copying the source CMake Makefile Vcpkg Includ

Dave Gamble 7.4k May 10, 2022
JSON parser and generator for C/C++ with scanf/printf like interface. Targeting embedded systems.

JSON parser and emitter for C/C++ Features ISO C and ISO C++ compliant portable code Very small footprint No dependencies json_scanf() scans a string

Cesanta Software 604 May 12, 2022
JSON & BSON parser/writer

jbson is a library for building & iterating BSON data, and JSON documents in C++14. \tableofcontents Features # {#features} Header only. Boost license

Chris Manning 38 Feb 18, 2022
A JSON parser in C++

JSON++ Introduction JSON++ is a light-weight JSON parser, writer and reader written in C++. JSON++ can also convert JSON documents into lossless XML d

Hong Jiang 481 Apr 29, 2022
🗄️ single header json parser for C and C++

??️ json.h A simple single header solution to parsing JSON in C and C++. JSON is parsed into a read-only, single allocation buffer. The current suppor

Neil Henning 495 May 18, 2022
Very low footprint JSON parser written in portable ANSI C

Very low footprint JSON parser written in portable ANSI C. BSD licensed with no dependencies (i.e. just drop the C file into your project) Never recur

James McLaughlin 1.1k May 8, 2022
Very simple C++ JSON Parser

Very simple JSON parser for c++ data.json: { "examples": [ { "tag_name": "a", "attr": [ { "key":

Amir Saboury 64 May 12, 2022
a JSON parser and printer library in C. easy to integrate with any model.

libjson - simple and efficient json parser and printer in C Introduction libjson is a simple library without any dependancies to parse and pretty prin

Vincent Hanquez 259 May 14, 2022
a header-file-only, JSON parser serializer in C++

PicoJSON - a C++ JSON parser / serializer Copyright © 2009-2010 Cybozu Labs, Inc. Copyright © 2011-2015 Kazuho Oku Licensed under 2-clause BSD license

Kazuho Oku 998 May 12, 2022
A fast JSON parser/generator for C++ with both SAX/DOM style API

A fast JSON parser/generator for C++ with both SAX/DOM style API Tencent is pleased to support the open source community by making RapidJSON available

Tencent 12k May 14, 2022
Lightweight, extremely high-performance JSON parser for C++11

sajson sajson is an extremely high-performance, in-place, DOM-style JSON parser written in C++. Originally, sajson meant Single Allocation JSON, but i

Chad Austin 532 Apr 30, 2022
🔋 In-place lightweight JSON parser

?? JSON parser for C This is very simple and very powerful JSON parser. It creates DOM-like data structure and allows to iterate and process JSON obje

Recep Aslantas 20 May 5, 2022
RapidJSON is a JSON parser and generator for C++.

A fast JSON parser/generator for C++ with both SAX/DOM style API

Tencent 12k May 14, 2022
single-header json parser for c99 and c++

ghh_json.h a single-header ISO-C99 (and C++ compatible) json loader. why? obviously this isn't the first json library written for C, so why would I wr

garrison hinson-hasty 14 May 10, 2022
Buggy JSON parser

Fuzzgoat: A minimal libFuzzer integration This repository contains a basic C project that includes an (intentionally insecure) JSON parser. It is an e

Fuzzbuzz 1 Apr 11, 2022
A generator of JSON parser & serializer C++ code from structure header files

JSON-CPP-gen This is a program that parses C++ structures from a header file and automatically generates C++ code capable of serializing said structur

Viktor Chlumský 8 May 2, 2022
Very low footprint JSON parser written in portable ANSI C

Very low footprint JSON parser written in portable C89 (sometimes referred to as ANSI C). BSD licensed with no dependencies (i.e. just drop the C file

null 1.2k May 12, 2022
json-cpp is a C++11 JSON serialization library.

JSON parser and generator for C++ Version 0.1 alpha json-cpp is a C++11 JSON serialization library. Example #include <json-cpp.hpp> struct Foo {

Anatoly Scheglov 4 Dec 31, 2019