Skip to content

Getting Started ​

LicenseMaven CentraljavadocSupported Dialects
Draft 2020-12Draft 2019-09Draft 7
BuildcodecovStars

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: Maven Central

Gradle:

java
// 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:

java
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:

java
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.

FeatureCapabilityRuntimeCompile-time
BindingData BindingSjf4j.from/toXxx()@CompiledBinder
NavigatingJSONPath NavigationJsonPath@CompiledNavigator
ValidatingJSON Schema ValidationJsonSchema@CompiledValidator
MappingObject MappingSjf4j.convert()@CompiledMapper
—JDBC Result Mapping—@CompiledJdbcMapper
PatchingJSON Patch & Merge PatchJsonPatch—
ModelingStructural OperationsNodes—

Binding ​

SJF4J provides unified data binding across JSON, YAML, and Java Properties, supporting POJOs, Maps, Lists, generic types, and custom value types.

Runtime

java
Sjf4j sjf4j = new Sjf4j();

User user = sjf4j.fromJson(json, User.class);
String yaml = sjf4j.toYamlString(user);

Compiled

java
@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)

Query and modify Java object graphs using JSONPath (RFC 9535) or JSON Pointer (RFC 6901).

Runtime

java
JsonPath path = JsonPath.parse("$.address.city");

String city = path.getString(user);     // Read a property
path.put(user, "Chongqing");            // Update a property

Compiled

java
@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

java
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

java
@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

java
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.

java
@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:

java
@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.

java
JsonPatch patch = JsonPatch.fromJson("""
        [{"op": "replace", "path": "/name", "value": "Alice Zhang"}]
        """);

patch.apply(user);  // Update in place

Learn 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 kindJava representations
Object nodeMap, POJOs, JsonObject, JOJOs
Array nodeList, Java arrays, JsonArray, JAJOs
Value nodeStrings, numbers, booleans, and custom value types

Use Nodes to work with these structures through a consistent API.

java
// 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 JsonObject to create a JOJO (JSON Object Java Object), combining typed properties with dynamic members in a hybrid object model.
  • Extend JsonArray to create a JAJO (JSON Array Java Object), a typed, extensible array node.
  • Use @NodeValue to model a Java type as a logical value node.
  • Use @OneOf to model polymorphic node types.
  • Register an ExternalNode to 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:

java
@CompiledNavigator
interface UserNavigator {
    @GetByPath("$.address.city")
    String getCity(User user);
}

The annotation processor generates an implementation such as UserNavigator_Impl:

java
// 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:

text
build/
└── generated/
    └── sources/
        └── annotationProcessor/
            └── java/
                └── main/
                    └── com/example/
                        └── UserNavigator_Impl.java

For Maven, typically: target/generated-sources/annotations/com/example/UserNavigator_Impl.java

How to Use ​

Add the annotation processor to your project:

java
annotationProcessor("org.sjf4j:sjf4j-processor:{version}")

Use CompiledInstances.create() to instantiate generated implementations:

java
UserNavigator navigator = CompiledInstances.create(UserNavigator.class);

More commonly, declare a static INSTANCE field directly in the interface:

java
@CompiledNavigator
interface UserNavigator {
    UserNavigator INSTANCE = CompiledInstances.create(UserNavigator.class);

    @GetByPath("$.address.city")
    String getCity(User user);
}

Then use it:

java
String city = UserNavigator.INSTANCE.getCity(user);

Benchmarks ​

SJF4J's performance and standards compliance are evaluated through independent comparisons and JMH benchmarks.

JSON Binding

JSONPath Navigation

JSON Schema Validation

Object Mapping

JDBC Result Mapping

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~

Released under the MIT License.