{"id":34888344,"url":"https://github.com/sjf4j-projects/sjf4j","last_synced_at":"2026-05-22T07:14:11.576Z","repository":{"id":327517300,"uuid":"1081834640","full_name":"sjf4j-projects/sjf4j","owner":"sjf4j-projects","description":"Simple JSON Facade for Java","archived":false,"fork":false,"pushed_at":"2026-03-04T04:57:45.000Z","size":1312,"stargazers_count":2,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-04T08:27:45.723Z","etag":null,"topics":["data-mapping","java","json","json-path","json-schema","yaml"],"latest_commit_sha":null,"homepage":"https://sjf4j.org","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sjf4j-projects.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-23T11:03:09.000Z","updated_at":"2026-03-04T05:06:52.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/sjf4j-projects/sjf4j","commit_stats":null,"previous_names":["sjf4j-projects/sjf4j"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/sjf4j-projects/sjf4j","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sjf4j-projects%2Fsjf4j","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sjf4j-projects%2Fsjf4j/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sjf4j-projects%2Fsjf4j/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sjf4j-projects%2Fsjf4j/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sjf4j-projects","download_url":"https://codeload.github.com/sjf4j-projects/sjf4j/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sjf4j-projects%2Fsjf4j/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30372533,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-10T21:41:54.280Z","status":"online","status_checked_at":"2026-03-11T02:00:07.027Z","response_time":84,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["data-mapping","java","json","json-path","json-schema","yaml"],"created_at":"2025-12-26T04:21:00.691Z","updated_at":"2026-05-22T07:14:11.569Z","avatar_url":"https://github.com/sjf4j-projects.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SJF4J — Simple JSON Facade for Java\n\n![License](https://img.shields.io/github/license/sjf4j-projects/sjf4j)\n[![Maven Central](https://img.shields.io/maven-central/v/org.sjf4j/sjf4j)](https://central.sonatype.com/search?q=sjf4j)\n[![javadoc](https://javadoc.io/badge2/org.sjf4j/sjf4j/javadoc.svg)](https://javadoc.io/doc/org.sjf4j/sjf4j)\n![Supported Dialects](https://img.shields.io/endpoint?url=https%3A%2F%2Fbowtie.report%2Fbadges%2Fjava-org.sjf4j-sjf4j%2Fsupported_versions.json)  \n![Build](https://img.shields.io/github/actions/workflow/status/sjf4j-projects/sjf4j/gradle.yml?branch=main)\n[![codecov](https://codecov.io/gh/sjf4j-projects/sjf4j/graph/badge.svg?branch=main)](https://codecov.io/gh/sjf4j-projects/sjf4j)\n![Stars](https://img.shields.io/github/stars/sjf4j-projects/sjf4j?style=social)\n\nSJF4J is a lightweight JSON facade and structural processing layer for Java.  \nIt sits above multiple JSON libraries — including [Jackson](https://github.com/FasterXML/jackson-databind),\n[Gson](https://github.com/google/gson), [Fastjson2](https://github.com/alibaba/fastjson2),\nand [JSON-P](https://github.com/jakartaee/jsonp-api) — while also supporting YAML\n(via [SnakeYAML](https://github.com/snakeyaml/snakeyaml)) and Java Properties.\n\nSJF4J provides **consistent structural processing across backends, data formats, and native Java object graphs**, \nbuilt on established JSON standards and semantics.  \nIt unifies [modeling](https://sjf4j.org/docs/modeling) (OBNT),\n[parsing](https://sjf4j.org/docs/parsing) (Codec), [navigating](https://sjf4j.org/docs/navigating) (JSON Path), \n[patching](https://sjf4j.org/docs/patching) (JSON Patch), [validating](https://sjf4j.org/docs/validating) (JSON Schema), \nand [mapping](https://sjf4j.org/docs/mapping) (Transformation) under one API model.\n\n\n## Install\nSJF4J requires **JDK 8+** and has no external dependencies beyond the data parsers you choose to add.\n\nGradle:\n```groovy\nimplementation(\"org.sjf4j:sjf4j:{version}\")\n```\n\nMaven:\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003eorg.sjf4j\u003c/groupId\u003e\n    \u003cartifactId\u003esjf4j\u003c/artifactId\u003e\n    \u003cversion\u003e{version}\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n**Optional Runtime Dependencies**  \nParsers are enabled automatically when their corresponding libraries are present,\nand can also be configured explicitly when needed.\n\n- **JSON**\n  - Include one of: `Jackson 3.x`, `Jackson 2.x`, `Gson`, `Fastjson2`, or `JSON-P` (with `Parsson` or others).  \n  - By default, SJF4J automatically detects and uses the first available implementation in that order.\n  - If none are detected, it falls back to a built-in simple JSON parser (functional but slower).\n  - Or configure the backend explicitly, for example:\n    ```java\n    Sjf4j.builder().jsonFacadeProvider(Jackson2JsonFacade.provider()).build();\n    ```\n\n- **YAML**\n  - Include `SnakeYAML` (the YAML 1.1 backend).\n  - YAML support requires SnakeYAML at runtime; unlike JSON, there is no built-in YAML parser fallback.\n\n- **Java Properties**\n  - Built-in support.\n  - Conversion is inherently limited by its flat key-value structure.\n\n- **In-Memory** \n  - Built-in support.\n  - Provides the same JSON-semantic APIs on in-memory object graphs via OBNT. \n  - Useful even without external data sources (e.g., DB result mapping, complex nested data processing).\n\nCommon runtime dependencies (pick as needed):\n\n```groovy\n// Jackson 3\nimplementation(\"tools.jackson.core:jackson-databind:{jackson3-version}\")\n\n// Jackson 2\nimplementation(\"com.fasterxml.jackson.core:jackson-databind:{jackson2-version}\")\n\n// Gson\nimplementation(\"com.google.code.gson:gson:{gson-version}\")\n\n// Fastjson2\nimplementation(\"com.alibaba.fastjson2:fastjson2:{fastjson2-version}\")\n\n// JSON-P API + Parsson implementation\nimplementation(\"jakarta.json:jakarta.json-api:{jsonp-version}\")\nimplementation(\"org.eclipse.parsson:parsson:{parsson-version}\")\n\n// YAML\nimplementation(\"org.yaml:snakeyaml:{snakeyaml-version}\")\n```\n\n\n## Quickstart\n\n### 1-minute example\n\nStart with `JsonObject` when you want to parse JSON, access values directly,\nand use JSON-semantic navigation and mutation APIs immediately.\n\n```java\nJsonObject jo = JsonObject.fromJson(\n        \"{\" +\n        \"\\\"name\\\":\\\"Alice\\\",\" +\n        \"\\\"age\\\":18,\" +\n        \"\\\"scores\\\":{\\\"math\\\":59}\" +\n        \"}\");\n\nString name = jo.getString(\"name\");\nint age = jo.getInt(\"age\");\nint math = jo.getIntByPath(\"$.scores.math\");\n\njo.putByPath(\"$.scores.art\", 95);\n\nString out = jo.toJson();\n```\n\n`JsonObject` is one of SJF4J’s dynamic JSON object representations. Others include `Map`, `POJO`, and `JOJO`.\n\n### 5-minutes walkthrough\n\nSJF4J is built around a single structural model: the **Object-Based Node Tree (OBNT)**.\n- All structured data in SJF4J are mapped into OBNT.\n- All nodes in OBNT are represented as native Java objects -- no dedicated AST.\n- All APIs operate directly on native Java objects.\n- All APIs follow -- or extend -- standard JSON semantics.\n\nThe following example demonstrates a complete lifecycle for processing structured data:\n```text\nModeling  →  Parsing  →  Navigating  →  Patching  →  Validating  →  Mapping\n```\n\n#### Modeling\n\nFor demonstration purposes, this examples use JOJO (`JsonObject`-based objects) since it handles typed fields and dynamic properties, \nmaking it suitable for objects with extra or unknown data.\n\n\u003e **Note**: Standard POJOs are fully supported as well, with equivalent navigation, mutation, and validation capabilities.\n\nDefine a JOJO `Student`:\n```java\npublic class Student extends JsonObject {\n    private String name;\n    private Map\u003cString, Integer\u003e scores;\n    private List\u003cStudent\u003e friends;\n    // Getters and setters\n}\n```\n\nLearn more → [Modeling (OBNT)](https://sjf4j.org/docs/modeling)\n\n\n\n#### Parsing\n\nUse `Sjf4j` to encode and decode structured data across multiple formats.\n```java\nString json = \"\"\"\n{\n    \"name\": \"Alice\",\n    \"scores\": {\"math\": 59, \"art\": 95},\n    \"friends\": [\n        {\"name\": \"Bill\", \"active\": true, \"scores\": {\"math\": 83}},\n        {\"name\": \"Cindy\", \"friends\": [{\"name\": \"David\", \"scores\": {\"math\": 95}}]}\n    ],\n    \"age\": 18\n}\n\"\"\";\n\nStudent student = new Sjf4j().fromJson(json, Student.class);\n```\n\nNow `student` exposes two complementary access models:\n- Strongly-typed Java getters/setters\n- JSON-semantic dynamic APIs\n\n```java\nstudent.getName();                  // Alice\nstudent.getInt(\"age\");              // 18\n```\n\nLearn more → [Parsing (Codec)](https://sjf4j.org/docs/parsing)\n\n#### Navigating\n\nEvery OBNT node supports declarative structural navigating, expressive querying,\nand precise mutation via `JSON Path` (RFC 9535) or `JSON Pointer` (RFC 6901).\n```java\nstudent.getIntByPath(\"$.scores.math\");\n// 59\n\nstudent.findByPath(\"$..friends[?@.scores.math \u003e= 90].name\", String.class);  \n// [\"David\"]\n\nstudent.ensurePutByPath(\"/friends/0/scores/music\", 100);\n// Bill's scores becomes: {\"math\": 83, \"music\": 100}\n```\n\nLearn more → [Navigating (JSON Path)](https://sjf4j.org/docs/navigating)\n\n#### Patching\n\nEvery OBNT node supports standard-compliant structural updates \nvia `JSON Patch` (RFC 6902) or `JSON Merge Patch` (RFC 7386).\n```java\nJsonPatch patch = JsonPatch.fromJson(\"\"\"\n[\n    { \"op\": \"replace\", \"path\": \"/name\", \"value\": \"Alice Zhang\" },\n    { \"op\": \"add\",     \"path\": \"/scores/physics\", \"value\": 91 }\n]\n\"\"\");\n\npatch.apply(student);\n```\n\nThe changes are applied in-place:\n```java\nstudent.getName();                              // \"Alice Zhang\"\nstudent.getIntByPath(\"$.scores.physics\");       // 91\n```\n\nLearn more → [Patching (JSON Patch)](https://sjf4j.org/docs/patching)\n\n#### Validating\n\nDeclare `JSON Schema` (Draft 2020-12) constraints with `@ValidJsonSchema` (Jakarta/Bean Validation style).\n```java\n@ValidJsonSchema(\"\"\"\n{\n  \"$ref\": \"#/$defs/Student\",\n  \"$defs\": {\n    \"Student\": {\n      \"type\": \"object\",\n      \"properties\": {\n        \"name\": {\n          \"type\": \"string\",\n          \"minLength\": 1\n        },\n        \"scores\": {\n          \"type\": \"object\",\n          \"additionalProperties\": {\"type\": \"integer\", \"minimum\": 0}\n        },\n        \"friends\": {\n          \"type\": \"array\",\n          \"items\": {\"$ref\": \"#/$defs/Student\"}\n        }\n      },\n      \"required\": [\"name\"]\n    }\n  }\n}\n\"\"\")\npublic class Student extends JsonObject {\n    private String name;\n    private Map\u003cString, Integer\u003e scores;\n    private List\u003cStudent\u003e friends;\n}\n```\n\nValidate at runtime:\n```java\nSchemaValidator validator = new SchemaValidator();\nvalidator.validate(student).isValid();                  // true\n```\n\nLearn more → [Validating (JSON Schema)](https://sjf4j.org/docs/validating)\n\n#### Mapping\n\nWhile `JsonPatch` focuses on in-place partial modification,\n`NodeMapper` produces a new structure from the source object graph.\n```java\nNodeMapper\u003cStudent, StudentDto\u003e mapper = NodeMapper\n    .builder(Student.class, StudentDto.class)\n    .copy(\"studentName\", \"name\")\n    .ensureValue(\"$.info.school\", \"PKU\")\n    .compute(\"/avgScore\", root -\u003e \n            root.getScores().values().stream().mapToInt(i -\u003e i).average().orElse(0))\n    .build();\n\nStudentDto studentDto = mapper.map(student);\n```\n\nLearn more → [Mapping (Transformation)](https://sjf4j.org/docs/mapping)\n\n\n## Benchmarks\nSJF4J delivers high performance with minimal overhead while providing a unified JSON-semantic processing model.\n\n**Reflection Access Benchmark**  \nLambda-based accessor generation minimizes reflection overhead,\ndelivering performance close to direct field or method invocation.\n\n**JSON Parsing Benchmark**  \nSJF4J operates on top of underlying JSON parsers while adding structural\ncapabilities and flexible binding annotations.  \nIn most cases, the additional overhead remains modest compared to native\nJSON libraries.\n\n**JSON Path Navigating Benchmark**  \nSJF4J shows strong performance in `compile` and `query` workloads, while also providing `mutation` operations.  \nWithin SJF4J, `Map/List` achieves the highest speed, with `JOJO` generally closer to `Map/List` than plain `POJO`.\n\n**JSON Schema Validating Benchmark**  \nSJF4J fully supports JSON Schema Draft 2020-12 and consistently ranks\namong the top-performing Java implementations in\n[Creek Service](https://www.creekservice.org/json-schema-validation-comparison/)\nand\n[Bowtie](https://bowtie.report/) benchmarks.\n\nLearn more → [Benchmarks](https://sjf4j.org/docs/benchmarks)\n\n## Contributing\n\nContributions are welcome in all forms, including code, documentation, bug reports, examples, benchmarks, \nand thoughtful feedback.  \nA good place to start is by [opening an issue](https://github.com/sjf4j-projects/sjf4j/issues/new).\n\nJSON is a simple and perhaps the most widely used structured data format today,\nand is backed by an entire ecosystem of standards, including RFCs.\n\n\u003e *So, what might JSON-oriented development look like in Java?*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsjf4j-projects%2Fsjf4j","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsjf4j-projects%2Fsjf4j","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsjf4j-projects%2Fsjf4j/lists"}