Getting Started
SJF4J (Simple JSON Facade for Java) provides a unified structural processing layer built on JSON semantics, bringing data binding, navigation, validation, mapping, and patching together.
JSON Semantics, Native Java Objects
Apply JSONPath, JSON Pointer, JSON Patch, and JSON Schema directly to POJOs, Maps, Lists, and domain models — no intermediate JSON trees required.Multiple Backends, One API
Work seamlessly across JSON backends (Jackson 2.x/3.x, Gson, Fastjson2, JSON-P), YAML (SnakeYAML), and other formats — all through a unified API.Runtime Flexibility, Compiled Speed
Enjoy flexible runtime APIs and highly optimized compile-time code generation.
Installation
SJF4J requires Java 8+ and supports modular installation. The latest version:
Gradle:
// Core structural processing API
implementation("org.sjf4j:sjf4j-core:{version}")
// Optional: Compile-time APIs
annotationProcessor("org.sjf4j:sjf4j-processor:{version}")
// Optional: JSON Schema validation
implementation("org.sjf4j:sjf4j-schema:{version}")
// Optional: Backend and its dependency (Jackson 2.x example)
implementation("org.sjf4j:sjf4j-backend-jackson2:{version}")
implementation("com.fasterxml.jackson.core:jackson-databind:2.22.3")Learn more → Installation (Modular)
Using Spring Framework or Spring Boot? The optional integration modules register compiled APIs for @Autowired injection. See Spring Integration.
Quickstart
Start with an ordinary Java class:
public class User {
public String name;
public int age;
public Address address;
}
public class Address {
public String city;
}Work directly with these objects using JSON-oriented APIs:
String json = "{\"name\":\"Alice\",\"age\":18,\"address\":{\"city\":\"Beijing\"}}";
// JSON → POJO
Sjf4j sjf4j = new Sjf4j();
User user = sjf4j.fromJson(json, User.class);
// Modify the POJO directly using JSONPath
JsonPath.parse("$.address.city").put(user, "Chongqing");
// POJO → JSON
String output = sjf4j.toJsonString(user);No special base classes, annotations, or intermediate JSON trees are required.
Explore Features
The following table provides an overview of SJF4J's features and their corresponding Runtime and Compile-time APIs.
| Feature | Capability | Runtime | Compile-time |
|---|---|---|---|
| Binding | Data Binding | Sjf4j.from/toXxx() | @CompiledBinder |
| Navigating | JSONPath Navigation | JsonPath | @CompiledNavigator |
| Validating | JSON Schema Validation | JsonSchema | @CompiledValidator |
| Mapping | Object Mapping | Sjf4j.convert() | @CompiledMapper |
| — | JDBC Result Mapping | — | @CompiledJdbcMapper |
| Patching | JSON Patch & Merge Patch | JsonPatch | — |
| Modeling | Structural Operations | Nodes | — |
Binding
SJF4J provides unified data binding across JSON, YAML, and Java Properties, supporting POJOs, Maps, Lists, generic types, and custom value types.
Runtime
Sjf4j sjf4j = new Sjf4j();
User user = sjf4j.fromJson(json, User.class);
String yaml = sjf4j.toYamlString(user);Compiled
@CompiledBinder
interface UserJsonBinder {
@Read User read(String json);
}SJF4J's open streaming architecture supports custom data formats and backends.
Its rich binding capabilities include @OneOf polymorphism, multi-format ValueCodec support, and fully managed ExternalNode integration.
Learn more → Binding (Formats)
Navigating
Query and modify Java object graphs using JSONPath (RFC 9535) or JSON Pointer (RFC 6901).
Runtime
JsonPath path = JsonPath.parse("$.address.city");
String city = path.getString(user); // Read a property
path.put(user, "Chongqing"); // Update a propertyCompiled
@CompiledNavigator
interface UserNavigator {
@GetByPath("$.address.city")
String getCity(User user);
@PutByPath("$.address.city")
String putCity(User user, String city);
}SJF4J combines standards-compliant JSONPath querying with powerful structural navigation and mutation, operating directly on Java objects without intermediate JSON trees.
Learn more → Navigating (JSONPath)
Validating
Validate Java objects directly against JSON Schema, without intermediate JSON tree construction.
Runtime
JsonSchema schema = JsonSchema.fromJson("""
{
"type": "object",
"properties": {
"name": {"type": "string", "minLength": 1},
"age": {"type": "integer", "minimum": 0}
},
"required": ["name"]
}
""");
SchemaPlan plan = schema.createPlan();
ValidationResult result = plan.validate(user);Compiled
@CompiledValidator
interface UserValidator {
@ValidJsonSchema(ref = "classpath:/schemas/user.json")
boolean isValid(User user);
}Supports JSON Schema Draft 2020-12, 2019-09, and 7, including full validation and annotation collection.
Experimental: JSON Schema can also be used to generate Java models through the online Schema-to-Java Generator.
Learn more → Validating (JSON Schema)
Mapping
Convert between Maps, POJOs, values, and nested Java object structures.
Runtime
public class AnotherUser {
public String fullName;
public int age;
}
AnotherUser user = sjf4j.convert(user, AnotherUser.class);Compiled
@CompiledMapper supports property renaming, nested mapping, custom expressions and creation strategies.
@CompiledMapper
interface UserMapper {
@Mapping(target = "fullName", source = "name")
AnotherUser toAnother(User user);
}Learn more → Mapping (Object-to-object)
@CompiledJdbcMapper generates direct mappings from JDBC ResultSet to Java objects:
@CompiledJdbcMapper
interface UserJdbcMapper {
List<User> users(ResultSet resultSet);
}Learn more → JDBC ResultSet Mapping
Patching
Apply JSON Patch (RFC 6902) and JSON Merge Patch (RFC 7386) directly to Java object graphs.
JsonPatch patch = JsonPatch.fromJson("""
[{"op": "replace", "path": "/name", "value": "Alice Zhang"}]
""");
patch.apply(user); // Update in placeLearn more → Patching (JSON Patch)
Modeling
OBNT (Object-Based Node Tree) is the unified structural model behind SJF4J's APIs. It enables JSON-oriented operations directly on native Java objects without requiring intermediate JSON trees.
OBNT defines three kinds of nodes:
| Node kind | Java representations |
|---|---|
| Object node | Map, POJOs, JsonObject, JOJOs |
| Array node | List, Java arrays, JsonArray, JAJOs |
| Value node | Strings, numbers, booleans, and custom value types |
Use Nodes to work with these structures through a consistent API.
// Access and convert property values
Object raw = Nodes.getInObject(user, "name");
String name = Nodes.toString(raw);
// Iterate over object properties
Nodes.forEachObject(user, (key, value) ->
System.out.println(key + ": " + value));
// Compare objects by JSON semantics
if (!Nodes.equals(user, userMap)) {
// Inspect object structure
System.out.println("user: " + Nodes.inspect(user));
}OBNT also supports extensible object models:
- Extend
JsonObjectto create a JOJO (JSON Object Java Object), combining typed properties with dynamic members in a hybrid object model. - Extend
JsonArrayto create a JAJO (JSON Array Java Object), a typed, extensible array node. - Use
@NodeValueto model a Java type as a logical value node. - Use
@OneOfto model polymorphic node types. - Register an
ExternalNodeto integrate your own structural types into OBNT.
Learn more → Modeling (OBNT)
Enjoy Compiled APIs
SJF4J's Compiled APIs can deliver up to 50× faster execution than Runtime through compile-time code generation.
How It Works
Define an annotated interface:
@CompiledNavigator
interface UserNavigator {
@GetByPath("$.address.city")
String getCity(User user);
}The annotation processor generates an implementation such as UserNavigator_Impl:
// Simplified illustration of generated code
public final class UserNavigator_Impl implements UserNavigator {
@Override
public String getCity(User user) {
if (user == null) return null;
Address address = user.address;
return address == null ? null : address.city;
}
}This implementation is automatically generated at compile-time, producing readable, debuggable Java source code that the JVM can optimize just like hand-written code.
Where's the Code
Generated implementations use the _Impl suffix and are written to the standard annotation-processing output directory.
For Gradle:
build/
└── generated/
└── sources/
└── annotationProcessor/
└── java/
└── main/
└── com/example/
└── UserNavigator_Impl.javaFor Maven, typically: target/generated-sources/annotations/com/example/UserNavigator_Impl.java
How to Use
Add the annotation processor to your project:
annotationProcessor("org.sjf4j:sjf4j-processor:{version}")Use CompiledInstances.create() to instantiate generated implementations:
UserNavigator navigator = CompiledInstances.create(UserNavigator.class);More commonly, declare a static INSTANCE field directly in the interface:
@CompiledNavigator
interface UserNavigator {
UserNavigator INSTANCE = CompiledInstances.create(UserNavigator.class);
@GetByPath("$.address.city")
String getCity(User user);
}Then use it:
String city = UserNavigator.INSTANCE.getCity(user);Benchmarks
SJF4J's performance and standards compliance are evaluated through independent comparisons and JMH benchmarks.
JSON Binding
- 🔗 Java JSON Benchmark — Independent JSON library benchmarks.
- Binding Full Benchmarks — Native JSON backends vs. Runtime and Compiled.
- Binding Native Image Full Benchmarks — GraalVM AOT, direct library Binding vs. Runtime and Compiled.
JSONPath Navigation
- 🔗 JSONPath Comparison — Cross-implementation specification compatibility.
- JSONPath Full Benchmarks — Jayway JsonPath vs. Runtime and Compiled.
JSON Schema Validation
- 🔗 Creek Service — Independent JVM validation benchmarks.
- 🔗 Bowtie — Cross-language JSON Schema compliance.
- JSON Schema Full Benchmarks — NetworkNT vs. Runtime and Compiled, including roundtrip performance.
Object Mapping
- 🔗 Java Object Mapper Benchmark — Independent comparison with Java mapping frameworks.
- Object Mapping Full Benchmarks — MapStruct vs. CompiledMapper.
JDBC Result Mapping
- JDBC Mapping Full Benchmarks — Spring JDBC and MyBatis vs. CompiledJdbcMapper.
Learn more → Benchmarks
Contributing
SJF4J is an open-source project built for the Java community.
All contributions are welcome! Feel free to open an issue or submit a pull request~