DEV Community

Yu Han
Yu Han

Posted on

SJF4J in 5 Minutes: A Practical JSON Facade for Java

#java #programming

JSON handling in Java is rarely simple.

In real-world applications, data constantly moves between:

  • POJOs
  • Map / List
  • JSON strings
  • configuration files
  • APIs with evolving schemas

Java developers are often forced into a painful decision:

Either type safety, or flexibility — but not both.

SJF4J (Simple JSON Facade for Java) is built to remove that trade-off.

What Is SJF4J?

SJF4J is a lightweight facade over popular JSON libraries (Jackson, Gson, Fastjson2) and related formats (YAML, Properties).

It provides a unified semantic layer for structured data processing, fully grounded in JSON specifications.

It does not replace your JSON parser — it unifies how you work with structured data above them.

The Core Idea: Object-Based Node Tree

Instead of introducing a custom JSON AST, SJF4J treats existing Java objects as JSON nodes.

This is called the Object-Based Node Tree (OBNT).

In OBNT:

  • JSON objects → JsonObject, Map, POJOs
  • JSON arrays → JsonArray, List, arrays
  • JSON values → native Java types

Everything stays plain Java — with JSON semantics layered on top.

Quick Example 

JsonObject jo = JsonObject.fromJson("""
{
  "id": 1,
  "active": true
}
""");

int id = jo.getInt("id");              // type-safe
String active = jo.asString("active"); // Boolean → String
Enter fullscreen mode Exit fullscreen mode

SJF4J offers three access levels:

  • getNode → raw access

  • getXxx → type-safe access

  • asXxx → semantic, cross-type conversion

You choose strictness per call.

Path-Based Access (RFC-Compliant)

SJF4J fully supports:

  • JSON Path (RFC 9535)
  • JSON Pointer (RFC 6901) 
String name = jo.asByPath("$.user.name");
List<Integer> ids = jo.findByPath("$.items[*].id", Integer.class);
Enter fullscreen mode Exit fullscreen mode

The same path API works across:

  • JSON
  • Maps / Lists
  • POJOs
  • Hybrid object graphs

Dynamic + Typed: JOJO

SJF4J introduces JOJO (JSON Object Java Object) —
a domain object that extends JsonObject.

class User extends JsonObject {
    String name;
}
Enter fullscreen mode Exit fullscreen mode 
user.getName();               // typed
user.getString("age");        // dynamic
user.findByPath("$..name");   // JSON semantics
Enter fullscreen mode Exit fullscreen mode

You can start dynamic and gradually add structure — without breaking APIs.

Declarative Transformation with JsonPatch

SJF4J supports:

  • JSON Patch (RFC 6902)
  • JSON Merge Patch (RFC 7386) 
JsonPatch patch = JsonPatch.diff(source, target);
patch.apply(source);
Enter fullscreen mode Exit fullscreen mode

Patches work uniformly across POJOs, Maps, Lists, and JSON objects.

When Does SJF4J Shine?

SJF4J is ideal if you:

  • Work with evolving or semi-structured data
  • Need both flexibility and type safety
  • Want one API across multiple JSON libraries
  • Care about JSON specifications

Summary

SJF4J makes JSON-oriented Java development possible — without early lock-in or excessive boilerplate.

It is small, composable, and specification-driven.

👉 GitHub: https://github.com/sjf4j-projects/sjf4j

Top comments (0)