alibaba/fastjson2

Language: English | 中文

FASTJSON 2

FASTJSON 2 is a high-performance JSON library for Java, designed as the next-generation successor to FASTJSON with a goal of providing an optimized JSON solution for the next ten years.

Highlights

• Blazing Fast - Significantly outperforms Jackson, Gson, and org.json. Benchmarks
• Dual Format - Native support for both JSON (text) and JSONB (binary) protocols
• Full & Partial Parsing - Complete document parsing or selective extraction via JSONPath (SQL:2016 compatible)
• Modern Java - Optimized for JDK 8/11/17/21 with compact string, Record, and Vector API support
• Multi-Platform - Works on Java servers, Android 8+ clients, and big data pipelines
• Kotlin Native - First-class Kotlin extensions with idiomatic DSL-style API
• JSON Schema - Built-in validation support with high performance
• Secure by Default - AutoType disabled by default; no hardcoded whitelist; SafeMode support
• GraalVM Ready - Compatible with GraalVM Native Image

Table of Contents

• Quick Start
• Installation
  • Core Library
  • Fastjson v1 Compatibility
  • Kotlin Module
  • Spring Integration
• Basic Usage
  • Parse JSON to JSONObject
  • Parse JSON to JSONArray
  • Parse JSON to Java Object
  • Serialize to JSON
  • JSONObject & JSONArray
  • Serialize JavaBean
• Advanced Usage
  • JSONB Binary Format
  • JSONPath
  • Features Configuration
  • Annotations
  • Custom Serializer/Deserializer
  • Filters
• Upgrading from Fastjson 1.x
• Documentation
• Contributing

Quick Start

Add the dependency and start parsing JSON in seconds:

<dependency>
    <groupId>com.alibaba.fastjson2</groupId>
    <artifactId>fastjson2</artifactId>
    <version>2.0.63</version>
</dependency>

import com.alibaba.fastjson2.JSON;

// Parse
User user = JSON.parseObject("{\"name\":\"John\",\"age\":25}", User.class);

// Serialize
String json = JSON.toJSONString(user);

1. Installation

1.1 Core Library

The groupId for FASTJSON 2 is com.alibaba.fastjson2 (different from 1.x):

Maven:

<dependency>
    <groupId>com.alibaba.fastjson2</groupId>
    <artifactId>fastjson2</artifactId>
    <version>2.0.63</version>
</dependency>

Gradle:

dependencies {
    implementation 'com.alibaba.fastjson2:fastjson2:2.0.63'
}

Find the latest version on Maven Central.

1.2 Fastjson v1 Compatibility Module

If you are migrating from fastjson 1.2.x, you can use the compatibility package as a drop-in replacement. Note that 100% compatibility is not guaranteed - please test thoroughly and report issues.

Maven:

<dependency>
    <groupId>com.alibaba</groupId>
    <artifactId>fastjson</artifactId>
    <version>2.0.63</version>
</dependency>

Gradle:

dependencies {
    implementation 'com.alibaba:fastjson:2.0.63'
}

1.3 Kotlin Module

For projects using Kotlin, the fastjson2-kotlin module provides idiomatic Kotlin extensions:

Maven:

<dependency>
    <groupId>com.alibaba.fastjson2</groupId>
    <artifactId>fastjson2-kotlin</artifactId>
    <version>2.0.63</version>
</dependency>

Add the Kotlin standard library and reflection library as needed. The reflection library is required when using data classes or constructor-based parameter passing:

<dependency>
    <groupId>org.jetbrains.kotlin</groupId>
    <artifactId>kotlin-stdlib</artifactId>
    <version>${kotlin-version}</version>
</dependency>

<dependency>
    <groupId>org.jetbrains.kotlin</groupId>
    <artifactId>kotlin-reflect</artifactId>
    <version>${kotlin-version}</version>
</dependency>

Kotlin Gradle:

dependencies {
    implementation("com.alibaba.fastjson2:fastjson2-kotlin:2.0.63")
    implementation("org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version")
    implementation("org.jetbrains.kotlin:kotlin-reflect:$kotlin_version")
}

1.4 Spring Framework Integration

For Spring Framework projects, use the appropriate extension module. See the full Spring Integration Guide for details.

Maven (Spring 5.x):

<dependency>
    <groupId>com.alibaba.fastjson2</groupId>
    <artifactId>fastjson2-extension-spring5</artifactId>
    <version>2.0.63</version>
</dependency>

Maven (Spring 6.x):

<dependency>
    <groupId>com.alibaba.fastjson2</groupId>
    <artifactId>fastjson2-extension-spring6</artifactId>
    <version>2.0.63</version>
</dependency>

Gradle:

dependencies {
    // Choose one based on your Spring version:
    implementation 'com.alibaba.fastjson2:fastjson2-extension-spring5:2.0.63'
    // or
    implementation 'com.alibaba.fastjson2:fastjson2-extension-spring6:2.0.63'
}

2. Basic Usage

The package name for FASTJSON 2 is com.alibaba.fastjson2. If upgrading from v1, simply update the package imports.

2.1 Parse JSON to JSONObject

Java:

String text = "{\"id\":1,\"name\":\"fastjson2\"}";
JSONObject data = JSON.parseObject(text);

byte[] bytes = text.getBytes(StandardCharsets.UTF_8);
JSONObject data = JSON.parseObject(bytes);

Kotlin:

import com.alibaba.fastjson2.*

val text = """{"id":1,"name":"fastjson2"}"""
val data = text.parseObject()

val bytes: ByteArray = text.toByteArray()
val data = bytes.parseObject() // JSONObject

2.2 Parse JSON to JSONArray

Java:

String text = "[{\"id\":1},{\"id\":2}]";
JSONArray data = JSON.parseArray(text);

Kotlin:

import com.alibaba.fastjson2.*

val text = """[{"id":1},{"id":2}]"""
val data = text.parseArray() // JSONArray

2.3 Parse JSON to Java Object

Java:

String text = "{\"id\":1,\"name\":\"John\"}";
User user = JSON.parseObject(text, User.class);

Kotlin:

import com.alibaba.fastjson2.*

val text = """{"id":1,"name":"John"}"""
val user = text.to<User>()          // User
val user = text.parseObject<User>() // User (alternative)

2.4 Serialize Java Object to JSON

Java:

User user = new User(1, "John");
String text = JSON.toJSONString(user);   // String output
byte[] bytes = JSON.toJSONBytes(user);   // byte[] output

Kotlin:

import com.alibaba.fastjson2.*

val user = User(1, "John")
val text = user.toJSONString()      // String
val bytes = user.toJSONByteArray()  // ByteArray

2.5 Working with JSONObject and JSONArray

2.5.1 Get Simple Properties

String text = "{\"id\": 2, \"name\": \"fastjson2\"}";
JSONObject obj = JSON.parseObject(text);

int id = obj.getIntValue("id");
String name = obj.getString("name");

String text = "[2, \"fastjson2\"]";
JSONArray array = JSON.parseArray(text);

int id = array.getIntValue(0);
String name = array.getString(1);

2.5.2 Get JavaBean from JSON Containers

Java:

JSONArray array = ...;
JSONObject obj = ...;

User user = array.getObject(0, User.class);
User user = obj.getObject("key", User.class);

Kotlin:

val array: JSONArray = ...
val obj: JSONObject = ...

val user = array.to<User>(0)
val user = obj.to<User>("key")

2.5.3 Convert JSONObject/JSONArray to JavaBean

Java:

JSONObject obj = ...;
JSONArray array = ...;

User user = obj.toJavaObject(User.class);
List<User> users = array.toJavaList(User.class);

Kotlin:

val obj: JSONObject = ...
val array: JSONArray = ...

val user = obj.to<User>()           // User
val users = array.toList<User>()    // List<User>

2.6 Serialize JavaBean to JSON

Java:

class User {
    public int id;
    public String name;
}

User user = new User();
user.id = 2;
user.name = "FastJson2";

String text = JSON.toJSONString(user);
byte[] bytes = JSON.toJSONBytes(user);

Kotlin:

class User(
    var id: Int,
    var name: String
)

val user = User(2, "FastJson2")
val text = user.toJSONString()      // String
val bytes = user.toJSONByteArray()  // ByteArray

Output:

{"id":2,"name":"FastJson2"}

3. Advanced Usage

3.1 JSONB Binary Format

JSONB is a high-performance binary JSON format that provides significantly faster serialization/deserialization and smaller payload sizes. See the JSONB Format Specification.

Serialize to JSONB

User user = ...;
byte[] bytes = JSONB.toBytes(user);
byte[] bytes = JSONB.toBytes(user, JSONWriter.Feature.BeanToArray); // Even more compact

Parse JSONB

byte[] bytes = ...;
User user = JSONB.parseObject(bytes, User.class);
User user = JSONB.parseObject(bytes, User.class, JSONReader.Feature.SupportArrayToBean);

3.2 JSONPath

JSONPath enables partial parsing of JSON documents without full deserialization, which is ideal for extracting specific fields from large payloads. FASTJSON 2 implements SQL:2016 JSONPath syntax.

Extract from String

String text = ...;
JSONPath path = JSONPath.of("$.id"); // Cache and reuse for better performance

JSONReader parser = JSONReader.of(text);
Object result = path.extract(parser);

Extract from byte[]

byte[] bytes = ...;
JSONPath path = JSONPath.of("$.id"); // Cache and reuse for better performance

JSONReader parser = JSONReader.of(bytes);
Object result = path.extract(parser);

Extract from JSONB byte[]

byte[] bytes = ...;
JSONPath path = JSONPath.of("$.id"); // Cache and reuse for better performance

JSONReader parser = JSONReader.ofJSONB(bytes); // Note: use ofJSONB method
Object result = path.extract(parser);

See the full JSONPath Documentation for filter expressions, aggregate functions, array slicing, and more.

3.3 Features Configuration

FASTJSON 2 provides fine-grained control over serialization and deserialization behavior through JSONWriter.Feature and JSONReader.Feature. All features are OFF by default.

// Serialization with features
String json = JSON.toJSONString(user,
    JSONWriter.Feature.WriteNulls,
    JSONWriter.Feature.PrettyFormat);

// Deserialization with features
User user = JSON.parseObject(json, User.class,
    JSONReader.Feature.SupportSmartMatch);

See the full Features Reference for all available options and migration mapping from fastjson 1.x.

3.4 Annotations

Use @JSONField and @JSONType to customize serialization/deserialization behavior:

public class User {
    @JSONField(name = "user_name", ordinal = 1)
    public String name;

    @JSONField(format = "yyyy-MM-dd", ordinal = 2)
    public Date birthday;

    @JSONField(serialize = false)
    public String password;
}

See the full Annotations Guide.

3.5 Custom Serializer/Deserializer

Implement ObjectWriter<T> or ObjectReader<T> for custom serialization logic:

// Custom writer
class MoneyWriter implements ObjectWriter<Money> {
    public void write(JSONWriter jsonWriter, Object object, Object fieldName, Type fieldType, long features) {
        Money money = (Money) object;
        jsonWriter.writeString(money.getCurrency() + " " + money.getAmount());
    }
}

// Register
JSON.register(Money.class, new MoneyWriter());

See the full Custom Reader/Writer Guide.

3.6 Filters

FASTJSON 2 provides a comprehensive filter system for serialization:

See the full Filter Documentation.

4. Upgrading from Fastjson 1.x

FASTJSON 2 provides both a compatibility mode (drop-in replacement) and a new API mode for upgrading. Key changes:

See the full Migration Guide for step-by-step instructions, API mapping table, and common issues.

5. Documentation

Core References

Format & Protocol

JSONPath

Integrations

Customization

Migration & Performance

6. Contributing

We welcome contributions of all kinds - bug reports, feature requests, documentation improvements, and code contributions.

• See CONTRIBUTING.md for development setup, coding standards, and the pull request process
• See CODE_OF_CONDUCT.md for community guidelines
• See SECURITY.md for reporting security vulnerabilities

Star History