Framework
SBJson/SBJson avatar
SBJson/SBJson

SBJson hands you parsed chunks before the document is known to be valid

This framework implements a strict JSON parser and generator in Objective-C.

3,713 stars672 forksObjective-CBSD-3-Clause

At a glance

What is it?
SBJson/SBJson is a BSD-3-Clause Objective-C JSON parser and generator built around chunk-based streaming, on branch trunk with its newest tag v5.0.4 dated 2026-05-15. The document states plainly that stream parsing gives up some correctness verification, that numbers too large for 64 bits become doubles, and that fuzzing runs 24 hours on a Nix-built AFL++.
Who is it for?
SBJson fits Objective-C code that has to consume a stream it does not control, such as a feed delivered one document per line or a large array arriving over a slow connection, because the parser's own feature is handing you chunks as they complete. Three things to weigh first.
Can I use it commercially?
Yes. BSD-3-Clause is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Activity is slowing. The repository last received commits 6 months ago.
What is it written in?
Mainly Objective-C, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • SBJson/SBJson3,713 ★ · -3
Star history
Repository2026-09-242026-11-15
SBJson/SBJson3.7k3.7k

-3 Stars in the last 52 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The block can fire on a document that later turns out to be broken

The document has a section called a word of warning, and it is the most useful paragraph in it.

Stream based parsing means losing some of the correctness verification a parser that considers the entire input before returning an answer would give you. It is technically possible for parts of a document to be returned as if they were correct, and for an error to turn up in a later part of the same document.

That is inherent to the design rather than a bug. The parser is created with a value block and an error handler:

objc
id parser = [SBJson5Parser parserWithBlock:block
                              errorHandler:eh];

and it returns a state value from `parse:`, `SBJson5ParserWaitingForData` while the input is incomplete and `SBJson5ParserComplete` when it is not, calling the block before it returns. So the caller sees results before it sees completeness, which is exactly what makes a slow connection tolerable and exactly what makes partial output possible.

Two other factories exist for different shapes of input. `multiRootParserWithBlock:` handles streams that contain one JSON document after another, the case of a feed giving you a document per line, and `unwrapRootArrayParserWithBlock:` handles a single very long top-level array when you cannot use the multi-document parser. All three share the same block and error handler shape.

Numbers that do not fit 64 bits become doubles and round

The type mapping is a table, and one row of it is where precision is decided.

null becomes `NSNull`, string becomes `NSString`, array becomes `NSMutableArray`, object becomes `NSMutableDictionary`, and true and false become `NSNumber` created with `numberWithBool:`, which is how booleans roundtrip even though Objective-C has no dedicated boolean class.

Numbers are the interesting case. Integers use `long long` or `unsigned long long` if they fit, specifically to avoid rounding errors. For all other numbers the parser uses `double`, and the document attaches its own warning to that choice: with all the potential rounding errors that entails.

So the boundary is exact and silent. An integer up to the signed or unsigned 64-bit boundary arrives exact, and anything beyond it, or any fractional value needing more precision than a double can carry, arrives as a double. Nothing in the mapping says which happened, so a consumer cannot tell from the value alone whether it has been rounded.

Two more mapping details are worth carrying into code. Arrays and objects arrive as the mutable variants, so a parsed document is directly editable, and there is no immutable option in the table.

The default nesting limit is 32 and it is configurable

Among the other features, one line is a safety property rather than a convenience: for safety there is a max nesting level for all input. It defaults to 32 and is configurable.

That default matters most for input you did not write. A parser that builds objects recursively will consume stack proportional to nesting depth, and a payload that nests a few thousand levels deep is a cheap way to make a process fall over. Capping depth at 32 turns that into an error the error handler sees.

The cap applies to all input, not only to untrusted documents, so a legitimate payload nested deeper than 32 levels fails until you raise the limit. The document does not say what the error looks like or what the maximum settable value is, so anyone relying on deep input has to discover both.

The remaining writer-side features are consistency and readability rather than validation: the writer can sort dictionary keys so output is consistent across writes, and it can produce human-readable output with newlines and indents.

Five years separate 5.0.3 from a patch called misc bug fixes

The recent tags are v5.0.4 on 2026-05-15, described in the release list as miscellaneous bug fixes, v5.0.3 on 2020-01-31, described as a patch release, and v5.0.3-rc1 on 2020-01-26, which carries a code of conduct and contributor guidelines.

So the sequence is a release candidate and a patch in January 2020, then nothing for more than six years, then a patch in May 2026 with no minor or major version in between. The default branch took its last commit on 2026-05-18, three days after that tag.

The installation instructions pin the patch rather than the line. The CocoaPods line is `pod 'SBJson', '~> 5.0.4'` and the Carthage line is `github "SBJson/SBJson" == 5.0.4`. A pessimistic constraint on a six-year-old patch release means an adopter gets exactly that build.

One badge is worth noticing too. Alongside the CircleCI and Carthage badges there is a repo status badge pointing at repostatus.org with the fragment for inactive. Whatever the project decides about its own status, that badge is what a reader sees next to the build status.

Version prefixes are how v3, v4 and v5 coexist

The document states that SBJson v3, v4 and v5 can be installed side by side in the same application, and gives the reason: all classes and public symbols contain the major version number.

You can see it in every example. The parser factory is `SBJson5Parser`, the block types are `SBJson5ValueBlock` and `SBJson5ErrorBlock`, and the file and directory names follow the same pattern with `SBJson5.podspec`, `SBJson5.xcodeproj/`, `SBJson5_iOS/` and `SBJson5_macOS/` alongside separate test targets for each platform.

That is a real benefit when a dependency you do not control still pulls in v4, since the linker has nothing to collide over. The cost is that your source names the version, so upgrading major versions is a rename across every call site rather than a version bump in a Podfile.

The layout also shows two platforms built from one library. `SBJson5_iOS/` and `SBJson5_macOS/` each have a matching test directory, `SBJson5_iOSTests/` and `SBJson5_macOSTests/`, alongside a shared `Classes/` and `Tests/` tree plus a `TestData/` directory.

Reproducing the fuzz run means Nix and a different branch

The fuzzing section is unusually concrete about how to repeat it.

The claim is a run of AFL++ over the sbjson binary for over 24 hours with no crashes found, and a note that the hangs reported when parsing manually could not be reproduced. The output shown is a run of 1 day, 0 hours, 26 minutes and 51 seconds, 57 cycles done, a corpus count of 1089, zero saved crashes and zero saved hangs.

Reproducing it takes two commands, and the first one changes branch:

bash
git checkout fuzz
nix-shell --command ./fuzz.sh

The `shell.nix` builds AFL++ 4.34c from source, configured to use POSIX shared memory through `shm_open` and `mmap` so that it runs on macOS without the System V IPC problems the packaged version has. The `fuzz.sh` script builds an instrumented sbjson binary and starts afl-fuzz seeded with the jsonchecker test data.

So the harness is Nix-based by design, the fuzzer is built from source rather than installed, and the input corpus comes from a published JSON conformance checker. The fuzz branch is separate from the default branch, which is `trunk`.

Two podspecs, two NEWS files and an example still on v4

The root of the repository is where the accumulated history shows.

There are two podspecs, `SBJson.podspec` and `SBJson5.podspec`, and two changelog files, `NEWS.md` and `NEWS4.md`, so both the packaging and the release history exist in more than one place. `CREDITS.md` sits next to a `RegenerateCredits` entry, which is a tool for rebuilding the credits list rather than a document a person maintains.

`RELEASING.md` is the release process, and the tree also carries `CODE_OF_CONDUCT.md`, `CONTRIBUTING.md`, `.editorconfig`, `.gitattributes` and a `.circleci/` directory for the build status the badge points at.

Two of the examples are separate repositories, and one of them is on the old major version: ChunkedDelivery is a toy example using `NSURLSessionDataDelegate` for chunked delivery, while DisplayPretty is described as a very brief example using SBJson 4 to reflow JSON on OS X. So the reference for reflowing JSON still sits on v4 while the library is v5.

The last installation option is the one the author discourages: copying the contents of the `Classes` folder into your own Xcode project, described as an alternative no longer recommended, next to CocoaPods as the preferred way and Carthage as supported.

Editorial conclusion

SBJson fits Objective-C code that has to consume a stream it does not control, such as a feed delivered one document per line or a large array arriving over a slow connection, because the parser's own feature is handing you chunks as they complete. Three things to weigh first. Streaming trades verification for latency, and the document says so itself: a prefix of the document can reach your block and a later part can still fail, so error handling has to assume partial output. Number fidelity is bounded by the type mapping, since anything that does not fit a signed or unsigned 64-bit integer becomes a double and rounds. And the release line is thin, with 5.0.3 published in January 2020 and 5.0.4, described as miscellaneous bug fixes, in May 2026, while the installation snippets pin that exact patch. BSD-3-Clause, a default nesting limit of 32, side-by-side installation of v3, v4 and v5, and reproducible fuzzing through Nix.

Frequently asked questions

What is SBJson used for?

Chunk-based JSON parsing and generation in Objective-C. You feed the parser one or more chunks of UTF-8 data and it calls a block for each root-level document, or for each top-level entry in a root array, which lets you return parsed pieces before a slow download completes and parse very large documents without holding them all in memory.

How does SBJson map JSON types to Objective-C types?

null to NSNull, string to NSString, array to NSMutableArray, object to NSMutableDictionary, true and false to NSNumber made with numberWithBool, and number to NSNumber. Integers use long long or unsigned long long when they fit to avoid rounding, and all other numbers use double, with the rounding errors that entails.

Is SBJson's streaming parser safe for input you do not control?

There is a max nesting level for all input, defaulting to 32 and configurable. The document also warns that stream parsing loses correctness verification, so parts of a document can be handed to your block as if they were correct before an error appears later in the same document.

How do I install SBJson?

Through CocoaPods, described as the preferred way, with pod 'SBJson', '~> 5.0.4' in a Podfile. Carthage is also supported with github "SBJson/SBJson" == 5.0.4. Copying the contents of the Classes folder into your own Xcode project is listed as an alternative the author no longer recommends.

Can SBJson 4 and SBJson 5 be installed in the same app?

Yes, and v3 can be there too. The document gives the reason: all classes and public symbols contain the major version number, which is why the v5 API is named SBJson5Parser with SBJson5ValueBlock and SBJson5ErrorBlock. The cost is that your call sites name the version.

Official sources

  1. Issues
  2. License: BSD-3-Clause
  3. README
  4. Releases
  5. SBJson/SBJson on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/sbjson-sbjson.svg)](https://hysenlabs.com/projects/sbjson-sbjson)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/sbjson-sbjson.svg)](https://hysenlabs.com/projects/sbjson-sbjson)

Was this useful?