DEV Community: Yu Han

Structural Mapping with SJF4J

Yu Han — Sat, 15 Aug 2026 15:36:53 +0000

Compile-time mapping does not have to stop at Java properties.

Java object mapping is usually expressed in terms of properties:

@Mapping(target = "displayName", source = "name")
UserDto toDto(User user);

That model works well when both sides are ordinary Java objects.

But structured data is often broader than a pair of Java types. A value may live several levels deep. The source may be a Map or a JSON-like object. The target may itself be nested. A value may need to be assembled from several locations.

SJF4J approaches these cases as structural mapping.

Instead of limiting mapping endpoints to Java properties, @CompiledMapper can work with locations inside a structured object graph:

@Mapping(
    source = "$.customer.address.city",
    target = "$.shipping.destination.city"
)
OrderView map(Order source);

The mapper still generates direct Java code at compile time.

The difference is the abstraction it compiles.

The structural model behind it

SJF4J is built around a common structural model called the Object-Based Node Tree (OBNT).

OBNT represents structured data using native Java objects. A POJO, Map, or JsonObject can represent a JSON object; a List, array, or JsonArray can represent a JSON array; ordinary Java scalar values represent JSON values.

The objects remain ordinary Java objects. SJF4J does not require them to be converted into an intermediate JSON tree before structural operations can be applied.

The same OBNT model is shared across SJF4J's navigation, binding, patching, validation, and mapping APIs.

@CompiledMapper builds compile-time transformation on top of that model. A mapping therefore operates on structure first; the concrete Java representation is simply how that structure happens to be stored.

Start with ordinary object mapping

The simplest mapper remains familiar.

public class User {
    private String name;
    private int age;

    // getters and setters
}

public class UserDto {
    private String name;
    private int age;

    // getters and setters
}

Declare the mapper:

@CompiledMapper
public interface UserMapper {
    UserDto toDto(User user);
}

Then obtain the generated implementation:

UserMapper mapper = CompiledNodes.instanceOf(UserMapper.class);
UserDto dto = mapper.toDto(user);

Compatible members with matching names are mapped automatically.

When names differ, describe only the difference:

@CompiledMapper
public interface UserMapper {

    @Mapping(target = "displayName", source = "name")
    UserDto toDto(User user);
}

The annotation processor generates the implementation during compilation, so runtime mapping does not need reflective property discovery.

Map nested values directly

Consider a source with nested data:

{
  "name": "Alice",
  "profile": {
    "address": {
      "city": "Seattle",
      "country": "US"
    }
  }
}

The target may only need city.

With @CompiledMapper, the mapping can describe the actual structural location:

@CompiledMapper
public interface UserMapper {

    @Mapping(
        target = "city",
        source = "$.profile.address.city"
    )
    UserDto toDto(User source);
}

The source can also be expressed as JSON Pointer:

@CompiledMapper
public interface UserMapper {

    @Mapping(
        target = "country",
        source = "/profile/address/country"
    )
    UserDto toDto(User source);
}

There is no need to flatten the input model first or introduce another intermediate DTO just to expose the nested value.

Targets can be paths too

Structural mapping works in both directions.

A target can itself be nested:

@CompiledMapper
public interface UserMapper {

    @Mapping(
        target = "$.profile.displayName",
        source = "name"
    )
    UserView toView(User source);
}

Both sides can be structural locations:

@CompiledMapper
public interface OrderMapper {

    @Mapping(
        source = "$.customer.address.city",
        target = "$.shipping.destination.city"
    )
    OrderView map(Order source);
}

At this point, the mapping declaration is no longer just copying one property to another. It describes a transformation between locations in a structured object graph.

Maps and JSON-like objects use the same model

A mapper does not require every source to be a dedicated Java class.

For example:

@CompiledMapper
public interface UserMapper {
    UserDto toDto(Map<String, Object> source);
}

The reverse direction works as well:

@CompiledMapper
public interface UserMapper {
    Map<String, Object> toMap(User source);
}

SJF4J's JSON-like objects participate in the same OBNT model.

The point is not that every combination needs a special mapper. POJOs, maps, and JSON-like objects are simply different representations of structured data handled by the same mapping model.

Compute values from multiple sources

Some target values naturally depend on more than one source location.

@CompiledMapper
public interface UserMapper {

    @Mapping(
        target = "fullName",
        sources = {"firstName", "lastName"},
        compute = "(first, last) -> first + \" \" + last"
    )
    UserDto toDto(User source);
}

The computation is processed during annotation processing and emitted into the generated Java implementation.

There is no runtime expression interpreter in the mapping path.

Sources can also be nested paths:

@CompiledMapper
public interface UserMapper {

    @Mapping(
        target = "fullName",
        sources = {
            "$.profile.firstName",
            "$.profile.lastName"
        },
        compute = "this::join"
    )
    UserDto toDto(User source);

    default String join(String first, String last) {
        return first + " " + last;
    }
}

This lets the mapper describe both where values come from and how they are combined, while non-trivial logic remains ordinary Java code.

Structural sources beyond object graphs

The same compile-time approach also applies to data that does not naturally look like a Java object graph.

For JDBC results, SJF4J provides @CompiledJdbcMapper:

@CompiledJdbcMapper
interface UserJdbcMapper {

    @Mapping(target = "name", source = "full_name")
    User user(ResultSet resultSet);
}

The annotation processor generates the ResultSet access and target assignments ahead of time.

JDBC uses a dedicated mapper because a ResultSet has its own access semantics, but the design remains consistent: describe the transformation and generate direct Java code at compile time.

Compile-time generation

Add SJF4J and its annotation processor:

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

For an interface such as:

@CompiledMapper
public interface UserMapper {

    @Mapping(target = "displayName", source = "name")
    UserDto toDto(User source);
}

SJF4J generates ordinary Java code corresponding to the mapping.

The generated implementation can directly read known members, navigate known structural paths, perform configured conversions, and assign target values.

The mapping decisions are made during compilation rather than repeatedly resolved at runtime.

Performance

@CompiledMapper is included in the independent
Java Object Mapper Benchmark,
which compares a range of Java object mapping frameworks on conventional object-to-object workloads.

The benchmark covers the familiar Java object mapping case, while SJF4J's mapping model also extends to structural paths and other representations.

See the independent
Java Object Mapper Benchmark
for the full comparison.

Structural mapping

SJF4J mapping is not primarily about adding more source and target types to a bean mapper.

It is built on OBNT, the same structural model used across the framework. Properties, nested paths, maps, JSON-like objects, and other structured sources can participate in the same compile-time transformation model.

That is what SJF4J means by structural mapping.

Tags: java json mapping performance

Documentation: https://sjf4j.org/docs/mapping
GitHub: https://github.com/sjf4j-projects/sjf4j

No parser. No interpreter. Just Java. That's how `@CompiledPath` gets so close to native performance.

Yu Han — Wed, 10 Jun 2026 14:52:07 +0000

Yu Han

Jun 10

143x Faster JSONPath by Removing JSONPath

#java #json #performance #opensource

4 min read

143x Faster JSONPath by Removing JSONPath

Yu Han — Wed, 10 Jun 2026 14:43:15 +0000

This benchmark result surprised even me:

Implementation	Time
Jayway JsonPath	143.477 ns/op
SJF4J Runtime `JsonPath`	26.284 ns/op
SJF4J APT-based `@CompiledPath`	0.988 ns/op
Native Java	0.877 ns/op

For this simple path:

$.store.bicycle.color

@CompiledPath is roughly 143× faster than Jayway JsonPath and nearly identical to hand-written Java code.

How?

The answer is surprisingly simple:

@CompiledPath does not make JSONPath interpretation faster.

It removes JSONPath interpretation from the runtime entirely.

The Hidden Cost of JSONPath

Consider a typical JSONPath lookup:

String color = JsonPath.read(
    document,
    "$.store.bicycle.color"
);

Even when the expression is precompiled, the runtime still needs to:

walk path segments;
inspect object types;
navigate containers;
resolve properties dynamically;
return and convert the result.

That flexibility is exactly what makes JSONPath useful.

But if the same path executes millions of times, the interpreter itself becomes part of the cost.

The JVM would much rather execute something like this:

String color = store.bicycle().color();

No parser.

No AST.

No reflection.

No path interpreter.

Just Java.

Turning JSONPath into Java Code

With SJF4J, you declare a path interface:

@CompiledPath
public interface StorePaths {

    @GetByPath("$.store.bicycle.color")
    String color(BookStore root);

}

And use it like any other Java API:

StorePaths paths = CompiledNodes.instanceOf(StorePaths.class);

String color = paths.color(store);

During compilation, the annotation processor generates an implementation.

Conceptually, the generated code looks like this:

@Override
public String color(BookStore root) {
    if (root == null) return null;

    Store store = root.store();
    if (store == null) return null;

    Bicycle bicycle = store.bicycle();
    if (bicycle == null) return null;

    return bicycle.color();
}

That's the entire trick.

There is no runtime JSONPath evaluation anymore.

The generated method is simply normal Java code.

Why It Gets So Close to Native Speed

The speedup comes from removing layers of work.

No Runtime Parser

The path expression is processed during compilation.

Nothing needs to be parsed when the application runs.

No Path Interpreter

There is no AST traversal loop.

There is no segment-dispatch mechanism.

There is no dynamic path evaluation.

Direct Property Access

The generated implementation can directly navigate:

POJOs
Records
Maps
Lists
JsonObject
JsonArray

using the most direct access strategy available.

JVM-Friendly Code

Because the generated code looks like ordinary Java methods, the JIT compiler can inline and optimize it aggressively.

From the JVM's perspective, there is nothing special happening.

Compile-Time Validation Included

Performance is only part of the story.

Because paths are analyzed during compilation, invalid paths fail the build.

Suppose your model contains:

store.book

but you accidentally write:

@GetByPath("$.store.books.price")

Instead of discovering the problem in production, compilation fails immediately:

Unknown property 'books' on Store

The path becomes part of your application's contract.

If you've used MapStruct, QueryDSL, or jOOQ, the experience will feel familiar.

Reads and Writes

@CompiledPath supports both read and write operations.

@CompiledPath
public interface StorePaths {

    @GetByPath("$.store.book[{idx}].price")
    Double bookPrice(BookStore root, int idx);

    @PutByPath("$.store.book[{idx}].price")
    Double replaceBookPrice(
        BookStore root,
        int idx,
        Double value
    );

    @EnsurePutByPath("$.store.bicycle.price")
    Double ensureBicyclePrice(
        BookStore root,
        Double value
    );
}

Dynamic placeholders are mapped directly from method parameters:

@GetByPath("$.users[{idx}].profile[{key}]")
Object value(Model root, int idx, String key);

int parameters address array/list indexes
String parameters address object keys

The generated implementation performs direct navigation without evaluating a runtime expression tree.

Benchmark Snapshot

The following benchmark was executed against the same object graph:

Operation	Runtime `JsonPath`	`@CompiledPath`	Native Java	Speedup
`get_bookPrice`	92.485 ns/op	1.793 ns/op	1.627 ns/op	51.58×
`get_color`	91.491 ns/op	0.988 ns/op	0.877 ns/op	92.60×
`get_price`	80.996 ns/op	0.984 ns/op	0.949 ns/op	82.31×
`put_bookPrice`	99.874 ns/op	18.911 ns/op	18.697 ns/op	5.28×
`put_price`	86.607 ns/op	19.587 ns/op	19.157 ns/op	4.42×

The exact numbers depend on the model, JVM, hardware, and path shape.

The architectural takeaway is more important:

@CompiledPath moves path resolution from runtime to build time.

When Should You Use It?

@CompiledPath is a good fit when:

path expressions are known during development;
the same paths execute frequently;
performance matters;
compile-time safety is desirable.

Typical use cases include:

validation engines;
pricing systems;
routing rules;
DTO projections;
data transformation pipelines;
high-frequency service code.

For user-supplied or highly dynamic expressions, runtime JsonPath remains the right tool.

The two approaches are complementary.

Setup

Add the annotation processor:

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

The implementation classes are generated automatically during compilation.

The Real Idea

Most JSONPath libraries focus on evaluating path expressions as efficiently as possible.

@CompiledPath takes a different route.

Instead of optimizing the interpreter, it removes the interpreter.

The path expression becomes Java code.

And once that happens, the JVM can optimize it exactly like code you wrote yourself.

That is how a JSONPath expression ends up running at nearly the same speed as native Java.

Learn More

Home: https://sjf4j.org
GitHub: https://github.com/sjf4j-projects/sjf4j
Navigating (JSON Path): https://sjf4j.org/docs/navigating
Benchmarks: https://sjf4j.org/docs/benchmarks#json-path-benchmark

No JSON round trip! No ugly generated maps!

Yu Han — Fri, 29 May 2026 10:50:25 +0000

Yu Han

May 29

JSON Schema to Java: A Better Object Model

#java #jsonschema #codegen #performance

3 min read

JSON Schema to Java: A Better Object Model

Yu Han — Fri, 29 May 2026 10:47:06 +0000

Start with a simple schema:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Order",
  "type": "object",
  "required": ["id", "amount", "customer"],
  "properties": {
    "id": { "type": "string" },
    "amount": { "type": "number" },
    "customer": {
      "type": "object",
      "properties": {
        "email": { "type": "string" }
      }
    }
  }
}

Because additionalProperties defaults to true, many JSON Schema-to-Java generators produce a POJO like this:

public class Order {
    private String id;
    private BigDecimal amount;
    private Customer customer;
    private Map<String, Object> additionalProperties = new LinkedHashMap<>();

    // normal getters and setters...

    public Map<String, Object> getAdditionalProperties() {
        return additionalProperties;
    }
}

It works.

But it is ugly.

additionalProperties is a JSON Schema concept. Exposing it as part of every generated Java model leaks schema internals into your application API.

Generated code is still code. Developers read it, debug it, autocomplete it, and often build long-lived systems around it. So the generated model should look like Java, not like a schema engine dump.

A cleaner approach

SJF4J takes a different route.

Instead of forcing dynamic JSON properties into a public additionalProperties map, SJF4J can generate JOJO-style models: Java objects that extend JsonObject.

public class Order extends JsonObject {
    private String id;
    private BigDecimal amount;
    private Customer customer;

    // normal getters and setters...

    // no generated additionalProperties map
}

No getAdditionalProperties().

The model stays clean, while still supporting JSON-style dynamic properties when the schema allows them. The object model carries the dynamic behavior; the generated Java API does not have to expose a schema keyword as a public map.

If the schema says additionalProperties: false, SJF4J can also generate stricter POJO-style models or disable dynamic reads depending on the selected strategy.

Online generator

You can try it here:

👉 https://sjf4j.org/generator

The generator supports options like:

JOJO or POJO modeling
Lombok or explicit getters/setters
validation annotations
enum/date/time mapping
path-only models
generated JSON Path accessors

So a nested schema field can become a convenient Java method instead of boilerplate object walking.

Direct schema validation on Java objects

The other important part: SJF4J validates Java object graphs directly against JSON Schema.

Typical validation often looks like this:

Java object -> JSON string -> JSON tree -> schema validation

SJF4J avoids that extra round trip.

A schema can be compiled into a SchemaPlan and applied directly to a Java object, including a plain POJO:

SchemaPlan plan = JsonSchema.fromJson(schemaText).createPlan();
ValidationResult result = plan.validate(order);

If you want to bind the schema to the generated Java model, you can declare the schema reference on the class:

@ValidJsonSchema(ref = "Order.json")
public class Order extends JsonObject {
    // generated fields
}

The schema can live as a normal classpath resource, for example:

src/main/resources/json-schemas/Order.json

Then validation becomes even more direct:

SchemaValidator validator = new SchemaValidator();
ValidationResult result = validator.validate(order);

The schema lookup and compiled validation plan can be cached and reused, which makes this model suitable for hot paths as well.

No serialization.

No parsing back into a JSON tree.

Just JSON Schema semantics applied to the Java object graph.

That is simpler and faster.

SJF4J supports JSON Schema Draft 2020-12 / 2019-09 / draft-07 and performs well in public benchmarks such as Creek Service:

👉 https://www.creekservice.org/json-schema-validation-comparison/

The bigger picture

JSON Schema should be more than a document-bound validation format.

In Java applications, the data often already exists as objects. The interesting question is whether JSON semantics can operate on those objects directly.

SJF4J's answer is yes:

generate Java-friendly models from JSON Schema
keep dynamic object behavior available when the schema allows it
validate native Java object graphs without a JSON round trip
use the same object graph with JSON Path, JSON Pointer, JSON Patch, and mapping APIs

That is the larger model: schema, validation, navigation, and transformation working on the same in-memory Java structure.

Try it:

Generator: https://sjf4j.org/generator
Project: https://github.com/sjf4j-projects/sjf4j
Benchmarks: https://sjf4j.org/docs/benchmarks

Curious what others think:

Should JSON Schema in Java stay tied to serialized JSON documents, or should JSON semantics work directly on native Java object graphs?

SJF4J makes Java JSON Schema validation fast not just by validating quickly, but by avoiding the extra JSON-tree step entirely.

Yu Han — Wed, 13 May 2026 08:40:39 +0000

Yu Han

May 13

Is SJF4J the fastest JSON Schema validator for Java?

#java #jsonschema #opensource #performance

4 min read

Is SJF4J the fastest JSON Schema validator for Java?

Yu Han — Wed, 13 May 2026 08:38:55 +0000

If you benchmark JSON Schema validators in Java, one question matters more than it first appears:

does the validator work directly on your Java object graph, or does it first force you through a JSON tree?

SJF4J is built around the first path.

That is why the recent independent benchmark work from Creek Service is interesting.

Because SJF4J's story is not just "we are fast".

It is: we avoid work that many Java validation pipelines still force you to do.

An independent signal worth paying attention to

Creek Service maintains an independent comparison of JVM JSON Schema validators:

What makes this benchmark especially useful is that it looks at validation from two angles:

pure validation against the JSON Schema test suite
serde-style workflows, where data is serialized, validated, read back, validated again, and deserialized

The first tells you whether a validator is strong at validation itself.
The second tells you how it behaves in something much closer to a real application pipeline.

Why this is good news for SJF4J

Creek Service's results reinforce two things SJF4J has been designed around from the start.

1) SJF4J is fast at pure validation

First: SJF4J is simply strong at pure validation.

That matters because the baseline job of a validator is still the same:

if you already have the schema and already have the data, validation should be fast and boring.

That alone already puts it in very serious company.

2) SJF4J gets more interesting as the workflow gets more real

This is the part that makes SJF4J more than just another validator with a benchmark chart.

Most validators are still easiest to understand as JSON validators.

SJF4J is better understood as a structural data processor for Java object graphs that also includes JSON Schema validation.

Instead, it can validate directly over:

Map / List
POJOs
JOJOs (JSON-Object Java Object)
other OBNT-compatible object graphs

So when your application is already working with Java objects, SJF4J does not need an extra parse/build pass just to begin validation.

In other words:

less conversion, less representation switching, less wasted work.

And that is exactly the kind of advantage that shows up in serde-style benchmarks.

Why this matters beyond benchmark screenshots

Because the real question is not just:

who wins a benchmark?

It is also:

who forces the least unnecessary work into my application?

In many Java systems, validation is not an isolated toy benchmark. It sits inside a larger flow:

HTTP request handling
event ingestion
Kafka or queue consumers
persistence pipelines
DTO ↔ domain transformations
configuration or document processing

If your validation layer keeps forcing this shape:

POJO -> JSON/tree -> validation -> POJO/domain

then the validator is only part of the cost story.

SJF4J reduces that friction by keeping validation inside the same structural processing model used for:

parsing
navigating
patching
mapping
validating

That gives you a simpler developer model and, very often, a faster runtime path.

A quick example

With SJF4J, schema validation can sit directly on top of a Java model:

@ValidJsonSchema("""
{
  "type": "object",
  "required": ["id", "email"],
  "properties": {
    "id": { "type": "integer" },
    "email": { "type": "string", "format": "email" }
  }
}
""")
public class UserDto {
    public int id;
    public String email;
}

SchemaValidator validator = new SchemaValidator();
ValidationResult result = validator.validate(userDto);

Or you can compile a reusable schema plan explicitly and validate native Java data directly:

JsonSchema schema = JsonSchema.fromJson("""
{
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "age": { "type": "integer", "minimum": 0 }
  },
  "required": ["name"]
}
""");

SchemaPlan plan = schema.createPlan();

Map<String, Object> data = Map.of(
    "name", "Ada",
    "age", 18
);

boolean ok = plan.isValid(data);

The key point is not just the API.

The key point is this:

validation happens over the object graph you already have.

SJF4J is not just a validator benchmark story

Another reason this matters: SJF4J is not a one-feature library.

It provides one structural model and one API family across:

JSON / YAML / Properties parsing
JSON Path navigation
JSON Patch / Merge Patch processing
JSON Schema validation
object graph mapping

So if your application needs more than "just validate a schema", SJF4J can simplify more of the pipeline instead of becoming one more isolated dependency with one narrow responsibility.

Where to look next

If you want to explore SJF4J further:

GitHub: sjf4j-projects/sjf4j
Docs: https://sjf4j.org
Validation guide: https://sjf4j.org/docs/validating
Benchmarks: https://sjf4j.org/docs/benchmarks

And if you want the benchmark context directly:

Creek Service comparison: https://www.creekservice.org/json-schema-validation-comparison/
Creek Service performance page: https://www.creekservice.org/json-schema-validation-comparison/performance

Final takeaway

Creek Service's independent benchmark is a good reminder that JSON Schema performance is not only about raw validation speed.

It is also about how much extra work your validation architecture forces you to do.

SJF4J performs well in pure validation.

But the more important point is this:

when your data is already in Java object graphs, validating those object graphs directly is often the better design.

That is the design SJF4J is built around.

And that may be exactly why it feels so fast in real Java workloads.

Stop switching between POJO and JsonNode in Java. What if your objects themselves were the JSON tree?

Yu Han — Sun, 26 Apr 2026 13:31:15 +0000

Yu Han

Apr 26

Beyond POJO and JsonNode: A More Cohesive Way to Handle JSON in Java

#java #json #opensource

5 min read

Beyond POJO and JsonNode: A More Cohesive Way to Handle JSON in Java

Yu Han — Sun, 26 Apr 2026 13:24:54 +0000

Jackson is excellent at binding JSON to POJOs, but in real projects, JSON handling rarely ends at deserialization. After binding, we often still need to:

query nested fields
preserve unknown properties
apply partial updates
validate data against JSON Schema

That is when many codebases begin to bounce between two models—and the cost is not just conceptual, but structural.

POJO for typed business logic
JsonNode for structural operations

Every transition between POJO and JsonNode introduces friction: data copying, lost type information, or duplicated logic.

This article focuses on a question:

If Jackson already handles JSON-to-POJO mapping well, why do we still end up converting back to JsonNode for path access, patching, or validation?

And more importantly: what if we didn’t have to switch models at all?

Where the friction starts

A POJO is great for representing a stable Java model. But operations like JSON Path, JSON Patch, and JSON Schema are inherently structural.

That leads to a familiar pattern:

Order order = objectMapper.readValue(json, Order.class);

This is clean and natural. But later, requirements change:

we need to read $.customer.address.city
a PATCH request updates /items/0/price
the payload contains fields the POJO does not declare
validation rules are described as JSON Schema rather than Java annotations

So the code shifts to tree mode:

JsonNode root = objectMapper.readTree(json);
String city = root.path("customer").path("address").path("city").asText();

This works too. The problem is not either API on its own. The real friction comes from switching models inside the same workflow.

Over time, the codebase becomes fragmented:

business logic talks in fields and getters
structural logic talks in tree nodes
patching introduces another abstraction
validation may rely on yet another model

A more cohesive direction

In most JSON libraries, once the workflow becomes structural, we usually move into a dedicated tree model such as JsonNode.

SJF4J takes a different route: it removes the need for a separate tree model altogether.

Instead of introducing an AST like JsonNode, it treats ordinary Java objects themselves as nodes in a JSON-semantic tree.

In practice, that means:

a JSON object can be represented by Map, JsonObject, POJO, or JOJO
a JSON array can be represented by List, JsonArray, Java arrays, or Set
a JSON value can be represented by String, Number, Boolean, null, or adapted value types

That is the key design move.

Once these runtime objects participate in the same structural model, operations such as JsonPath, JsonPatch, and JsonSchema no longer need a separate tree representation in order to work. The object graph itself becomes the thing we navigate, patch, validate, and map.

So the real shift is not just “one more JSON library.” It is this:

instead of switching from Java objects to a JSON tree when the workflow becomes more structural,

SJF4J keeps the object graph itself structurally available from the beginning.

Why JOJO is a useful middle ground

One practical consequence of OBNT is JOJO (JSON-Object Java Object): a typed Java object that also behaves like a JSON object.

public class Order extends JsonObject {
    private String id;
    private Customer customer;
    private List<Item> items;
}

Then you can work with the same object in multiple ways:

Order order = new Sjf4j().fromJson(json, Order.class);

order.getId();                                     // typed access
order.getStringByPath("$.customer.address.city");  // path access
order.getString("sourceSystem");                   // dynamic property

This is useful because many real payloads are only mostly stable.

In practice, upstream systems evolve faster than your Java model.

Some fields belong to the core Java model. Others are optional, evolving, or owned by upstream systems. A plain POJO can feel too closed for that. A raw tree can feel too loose. JOJO sits comfortably in between.

A small example

Imagine an external order payload like this:

{
  "id": "A1001",
  "customer": {
    "name": "Alice",
    "address": { "city": "Shanghai" }
  },
  "items": [
    { "sku": "P1", "price": 100 }
  ],
  "sourceSystem": "partner-x"
}

With a closed POJO model, sourceSystem may be ignored unless it is modeled explicitly.

With JOJO:

String source = order.getString("sourceSystem");
String city = order.getStringByPath("$.customer.address.city");

It is a small difference in code, but a big difference in modeling style: typed fields and flexible JSON-style access can live together.

JsonPath becomes more than a convenience

Because the object graph itself is navigable, JsonPath is no longer an add-on—it becomes a natural way to interact with your data.

With direct field access:

String city = order.getCustomer()
                   .getAddress()
                   .getCity();

This is perfectly fine when the structure is fixed and shallow.

But once the data becomes deeper, more dynamic, or only partially known, path-based access can be much cleaner:

String city = order.getStringByPath("$.customer.address.city");

It also scales naturally to bulk queries:

List<Integer> prices = order.findByPath("$.items[*].price", Integer.class);

Or filtered queries:

List<String> skus = order.findByPath("$.items[?@.price >= 100].sku", String.class);

No, this is not the same as direct field access in absolute raw speed. But that trade-off is often worth it. Like many higher-level abstractions in Java, it introduces some overhead while saving code, reducing traversal boilerplate, and improving flexibility.

Learn more → Navigating (JSON Path)

Patch fits naturally too

Once the object graph is treated structurally, patching no longer feels bolted on.

JsonPatch patch = JsonPatch.fromJson("""
[
  { "op": "replace", "path": "/customer/name", "value": "Alice Zhang" },
  { "op": "add", "path": "/items/0/discount", "value": 15 }
]
""");

patch.apply(order);

Or direct path mutation:

order.ensurePutByPath("$.shipping.trackingNo", "SF123456");

This is especially useful for:

HTTP PATCH endpoints
partial state updates
integration events
targeted nested mutations

Learn more → Patching (JSON Patch)

Validation stays in the same flow

Schema validation also becomes easier to place in the workflow when it operates on the same runtime structure:

@ValidJsonSchema("""
{ "type": "object", "required": ["id"] }
""")
public class Order extends JsonObject {
    // ...
}

boolean valid = new SchemaValidator().validate(order).isValid();

The benefit is not only fewer conversion steps. More importantly, query, mutation, and validation all operate with the same object graph.

Learn more → Validating (JSON Schema)

Final thought

JSON in Java is not just about converting strings into objects.

It is about how those objects participate in the rest of your system.

By treating ordinary objects as part of a JSON-semantic tree, SJF4J removes an entire layer of indirection—and with it, a surprising amount of complexity.

Project links:

GitHub: https://github.com/sjf4j-projects/sjf4j
Docs: https://sjf4j.org

A new jsonschema2jojo online tool!

Yu Han — Tue, 21 Apr 2026 00:08:37 +0000

Yu Han

Apr 20

Generating Java from JSON Schema

#java #jsonschema #opensource #productivity

5 min read

[Boost]

Yu Han — Tue, 21 Apr 2026 00:06:28 +0000

Yu Han

Apr 20

Generating Java from JSON Schema

#java #jsonschema #opensource #productivity

5 min read

Generating Java from JSON Schema

Yu Han — Mon, 20 Apr 2026 08:01:06 +0000

A new browser-based tool on sjf4j.org turns JSON Schema into Java scaffolding directly in the browser.

Paste a schema, tune the generation strategy, and get Java output immediately.

What makes it more interesting than a basic schema-to-POJO converter is that it exposes modeling decisions directly.

Schema-to-code is not only about mapping types. It is also about deciding what should become part of a stable Java API, and what should remain flexible.

Try it here

👉 Tool: https://sjf4j.org/generator

What the tool does

The generator is a browser-based playground for turning JSON Schema into Java scaffolding.

It currently supports:

package and class name configuration
primitive / number / date-time mapping choices
string enum → Java enum generation
nested object → inner class generation
required-field-aware generation
validation annotations such as @NotNull
JavaDoc generation from schema metadata
allOf flattening for object schemas
local $ref expansion
deterministic import and member ordering

One of the strongest parts of the tool is its customization model:

global configuration for overall generation behavior
property-by-property overrides in the Parsed Properties panel

So the tool does not force one all-or-nothing rule across the whole schema. A project can start with a global baseline, then adjust selected members one by one.

A simple example

Given a schema like this:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Order",
  "description": "Checkout order created by the storefront.",
  "type": "object",
  "required": ["id", "amount", "createdAt", "customer", "items"],
  "properties": {
    "id": {
      "type": "string",
      "description": "Business order identifier."
    },
    "amount": {
      "type": "number",
      "description": "Total amount in the settlement currency."
    },
    "createdAt": {
      "type": "string",
      "format": "date-time"
    },
    "paid": {
      "type": "boolean"
    },
    "customer": {
      "type": "object",
      "required": ["id", "email"],
      "properties": {
        "id": {
          "type": "string"
        },
        "email": {
          "type": "string"
        }
      }
    },
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["sku", "quantity"],
        "properties": {
          "sku": {
            "type": "string"
          },
          "quantity": {
            "type": "integer"
          }
        }
      }
    }
  }
}

With the default JOJO-oriented settings, the generated Java can look like this:

@Getter @Setter
public class Order extends JsonObject {
    /**
     * JSON shape:
     * <pre>
     * {
     *   "id": "string",
     *   "amount": "number",
     *   "createdAt": "string(date-time)",
     *   "paid": "boolean",
     *   "customer": {
     *     "id": "string",
     *     "email": "string"
     *   },
     *   "items": [
     *     {
     *       "sku": "string",
     *       "quantity": "integer"
     *     }
     *   ]
     * }
     * </pre>
     */
    @NotNull private String id;
    @NotNull private double amount;
    @NotNull private OffsetDateTime createdAt;
    private boolean paid;
    @NotNull private Customer customer;
    @NotNull private List<ItemsItem> items;

    private static final JsonPath PATH_CUSTOMER_EMAIL = JsonPath.compile("$.customer.email");

    public String getCustomerEmail() {
        return PATH_CUSTOMER_EMAIL.getString(this);
    }

    public String getItemsSku(int itemsIndex) {
        return getStringByPath("$.items[" + itemsIndex + "].sku");
    }

    @Getter @Setter
    public static class Customer extends JsonObject {
        @NotNull private String id;
        @NotNull private String email;
    }

    @Getter @Setter
    public static class ItemsItem extends JsonObject {
        @NotNull private String sku;
        @NotNull private int quantity;
    }
}

This is closer to a real API shape: nested objects, arrays, required members, generated inner classes, validation annotations, and root-level path accessors.

Why modeling choices matter

The generator is not designed as a “turn every JSON property into a field” machine.

In real systems, the harder question is usually:

Which parts of this schema should become a stable Java contract, and which parts should stay flexible?

That is why the tool exposes decisions such as:

JOJO vs POJO modeling
field vs property generation
path accessor generation on the root model
per-property type overrides
global defaults plus property-by-property adjustments

This matters when the input schema comes from:

a third-party API that changes often
an event payload with optional extension fields
an internal contract that is stable in some places and fluid in others

Why JOJO is interesting here

This generator is part of the broader SJF4J ecosystem, so it can generate models that fit naturally into SJF4J’s structural APIs.

If an object is modeled as a JOJO, it extends org.sjf4j.JsonObject.

That gives you an interesting hybrid:

typed Java members where you want a stable contract
dynamic JSON-style access where you still need flexibility

For example, the generator can produce root-level descendant accessors such as:

public String getCustomerEmail() {
    return PATH_CUSTOMER_EMAIL.getString(this);
}

public String getItemsSku(int itemsIndex) {
    return getStringByPath("$.items[" + itemsIndex + "].sku");
}

That is a different direction from classic schema-to-POJO generators. It is useful when the generated model is not just a DTO, but part of a larger JSON-processing workflow.

Global configuration and per-property tuning

Customization happens at two levels.

At the global level, the generator can define the overall baseline for a file:

package and class name
JOJO or POJO preference
field-generation strategy
accessor strategy
path-accessor strategy
integer / number / boolean / enum / date-time mapping
object-leaf mapping
validation namespace and annotations
JavaDoc generation

At the property level, the Parsed Properties panel can refine specific members:

switch between field and property generation
override the generated Java type
enable or disable by-path getter/setter generation for eligible paths

That makes the tool flexible enough for mixed schemas, where most properties follow one rule but a few important members need a different Java contract.

Where this fits in SJF4J

If you have not seen SJF4J before, it is a unified JSON-semantic processing layer for Java.

It provides one structural model across:

parsing
modeling
JSON Path navigation
JSON Patch / Merge Patch
JSON Schema validation
mapping / transformation

In practice, that means you can:

start from a JSON Schema
generate a Java model
parse payloads into that model
navigate it with JSON Path
validate it with JSON Schema
keep dynamic structure where needed

That end-to-end flow is why this generator fits naturally on the SJF4J site instead of being treated as an isolated utility.

A few implementation details worth keeping explicit

Some current baseline behaviors:

nested object schemas generate as public static inner classes
nested enums are generated inside the owning class
imports are deduplicated and sorted
object allOf is flattened before rendering
circular local $ref chains are rejected
unsupported non-local $ref is ignored for now
root path accessors are generated only when the root model is a JOJO

In other words, the tool tries to be predictable first, and flexible second — but without hiding the rules.

Another useful detail: the full generation rules are published on the page itself. So the tool is not a black box. The page also works as a spec-like baseline and regression target: the rules are explicit enough to be reused as an AI prompt, allowing an LLM to reproduce a similar generator — or help design a more optimized one on top of the same contract.

Why this is useful

The practical value is simple: the first draft of a Java model should be fast to get, but not locked into the wrong abstraction too early.

If you only need quick scaffolding, the generator already helps.

If you care about long-term maintainability, the more useful part is that it makes the trade-offs visible:

strict vs flexible object modeling
field-backed vs dynamic property-backed members
plain DTO generation vs JSON-semantic access patterns

Try it and tell me what is missing

If you want to try it:

Generator: https://sjf4j.org/generator
SJF4J docs: https://sjf4j.org/docs/getting_started
GitHub: https://github.com/sjf4j-projects/sjf4j

If you are already working with JSON Schema, Java DTO generation, or mixed typed/dynamic payloads, useful feedback would include:

nullable handling
multi-file output layout
more $ref composition cases
better defaults for boxed vs primitive types

Schema-to-code is easy to automate.

Designing good Java boundaries is still the hard part.