JBird

A blazing fast, type-safe library for working with JSON in Swift

Why JBird?

Working with JSON in Swift usually means choosing between two extremes. Foundation’s JSONSerialization hands you Any and forces you to cast and unwrap at every step. Codable is type-safe but rigid: it expects your Swift types to mirror the payload exactly, and reaching into a single field of an arbitrary document is awkward.

JBird closes that gap. It models JSON as a first-class Swift value you can read, traverse, and mutate directly — without ever losing type safety — and pairs that model with a fast, C-backed parsing core. And when you do want to work with concrete Swift types, JBird converts cleanly to and from them, including a drop-in Codable encoder and decoder.

// Foundation: cast and unwrap at every level
if let root = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
   let user = root["user"] as? [String: Any],
   let name = user["name"] as? String {
    // ...finally usable
}

// JBird: type-safe traversal in a single expression
let json = try JSON(data)
let name: String = try json["user"]["name"]

For more background, see the documentation.

Features

JBird is organized around five capabilities, all built on the same JSON value type — so they share a consistent, type-safe API and compose freely.

A type-safe model for creating and manipulating JSON

JSON is a Sendable, Equatable, Hashable enum with one case per JSON type (null, bool, number, string, array, object). It conforms to the standard ExpressibleBy*Literal protocols, so you build values using ordinary Swift literals:

var user: JSON = [
    "name": "Alice",
    "age": 30,
    "active": true,
    "roles": ["admin", "editor"],
]

Read values through throwing, typed accessors and subscripts. Subscripts chain across nested objects and arrays, and can convert to a concrete type inline:

let name = try user["name"].stringValue             // String
let firstRole: String = try user["roles"][0]        // String, via type inference
let age = try user["age", as: Int.self]             // Int

if user.containsValue(forKey: "email") { /* ... */ }

Mutate in place — set keys, append to arrays, merge, and remove — without rebuilding intermediate containers:

try user.setValue(31, forKey: "age")
try user["roles"].append("reviewer")
try user.removeValue(forKey: "active")
try user.merge(["verified": true], uniquingKeysWith: { _, new in new })

A blazing fast JSON serializer and deserializer

Parsing and serialization are backed by a hand-written C core with SIMD-accelerated scanning (SSE2 on x86-64, NEON on ARM64), an arena allocator, and string interning. It works directly with the JSON model, with no intermediate Any representation to slow things down.

// Deserialize from Data or String
let json = try JSON(data)
let fromString = try JSON(jsonString: #"{"ok":true}"#)

// Serialize to Data or String
let data = try json.serialize()
let string = try json.stringify()

Both directions accept option sets (DeserializationOptions, SerializationOptions) for control over things like pretty-printing, key sorting, and duplicate-key handling, and cancellable async variants are available for large payloads.

Conversion between typed JSON and Swift types

JBird defines a small protocol family for bridging typed JSON and other Swift types:

• JSONConvertible — a type can produce a JSON value (var jsonValue: JSON)
• JSONInitializable — a type can be built from a JSON value (init(json:) throws)
• JSONRepresentable — both of the above

Many standard library types already conform.

let json = JSON(["a": 1, "b": 2])        // from a Swift dictionary
let dict = try json.convert(into: [String: Int].self)

For your own types, the @JSONRepresentable macro generates both conformances. @JSONKey customizes the key for a property (a literal string or .snakeCase), and @OmitIfNil drops nil optionals from the output:

@JSONRepresentable
struct Article {
    @JSONKey("article_id") let id: String
    @JSONKey(.snakeCase)   let publishedAt: Date     // -> "published_at"
    @OmitIfNil             let summary: String?
}

let article = try Article(json: json)
let roundTrip = JSON(article)

A result builder for declarative JSON

The JSON { ... } result builder constructs values declaratively, with the => operator for object keys, nesting via trailing closures, and full support for if/else/for control flow:

let payload = JSON {
    "id" => 123
    "profile" => {
        "name" => "Alice"
        if isAdmin {
            "role" => "admin"
        }
    }
    "tags" => {
        for tag in tags {
            tag
        }
    }
}

A drop-in replacement for JSONEncoder / JSONDecoder

JSON.Encoder and JSON.Decoder mirror Foundation’s Codable API surface, so existing Codable types work unchanged — while encoding and decoding run through JBird’s fast core, no migration required.

struct Person: Codable {
    let name: String
    let age: Int
}

let encoder = JSON.Encoder()
encoder.outputFormatting = [.prettyPrinted, .sortedKeys]
encoder.keyEncodingStrategy = .convertToSnakeCase
let data = try encoder.encode(Person(name: "Bob", age: 25))

let decoder = JSON.Decoder()
decoder.keyDecodingStrategy = .convertFromSnakeCase
let person = try decoder.decode(Person.self, from: data)

The familiar configuration strategies are all present, along with support for EncodableWithConfiguration / DecodableWithConfiguration.

The declarative builder, conformance macros, and Codable support are exposed as package traits — DeclarativeAPI, ConformanceMacros, and CodableSupport — all enabled by default and individually opt-out.

JBird is rigorously validated against RFC 8259 by a comprehensive test suite and a fuzzer.

Installation

JBird is primarily distributed through the Swift Package Manager.

To add JBird as a dependency to an existing Swift package, add the following line of code to the dependencies parameter of your Package.swift file:

dependencies: [
    .package(url: "https://github.com/vsanthanam/JBird.git", from: "2.1.2")
]

Then, add the JBird dependency to your target or targets of choice:

.target(
    name: "YourTarget",
    dependencies: [
        .product(name: "JBird", package: "JBird")
    ]
)

Xcode

JBird supports the full range of Apple platforms when working with Xcode, whether you build from source or use an XCFramework:

Swift Package Manager

JBird has been tested to work with the following platforms and Swift toolchains:

All supported platforms undergo continuous integration testing to ensure compatibility across different environments. Other platforms such as FreeBSD may also work, but are not validated in the built-in GitHub Actions powered CI environment.

For additional installation instructions, see the documentation.

Performance

JBird is designed with performance and memory efficiency in mind, with benchmarks showing it to be one of the fastest JSON parsers available for Swift. The core parsing engine is written in C and is heavily optimized, making it significantly faster than pure Swift alternatives.

JBird demonstrates exceptional performance compared to other popular JSON parsing libraries:

• Speed: JBird parses JSON 2-5x faster than SwiftyJSON and about 25% faster than Foundation
• Memory Efficiency: JBird uses significantly less memory than other parsers (up to a 95% reduction)
• Resource Usage: JBird requires dramatically fewer CPU instructions and memory allocations for equivelent payloads
• Consistent Performance: JBird maintains its performance advantage across different JSON file sizes and formats

These benchmarks were run on a variety of JSON files ranging from 64KB to 5MB, in both minified and pretty-printed formats. You can explore the comparisons with common Swift JSON libraries (Foundation, SwiftyJSON, etc.) in the /Benchmarks directory.

Usage & Documentation

JBird’s documentation is built with DocC and included wich each release as a DocC archive. The latest version is hosted on GitHub Pages and is available here.

Additional information is available on the Swift Package Index

Explore the documentation for more details.

License

JBird is available under the MIT license. See the LICENSE file for more information.