json-io

json-io is a powerful and lightweight Java library that simplifies JSON serialization and deserialization while handling complex object graphs with ease. Unlike basic JSON parsers, json-io preserves object references, handles polymorphic types, and maintains cyclic relationships in your data structures. Whether you're working with sophisticated domain models, dealing with legacy Java objects, or need high-performance JSON processing, json-io provides a robust solution with minimal configuration.

Key Features:

• Preserves object references and handles cyclic relationships
• Supports polymorphic types and complex object graphs
• Zero external dependencies (other than java-util)
• Fully compatible with both JPMS and OSGi environments
• Lightweight (json-io.jar is ~300K, java-util is ~600K)
• Compatible with JDK 1.8 through JDK 24
• The library is built with the -parameters compiler flag. Parameter names are now retained for tasks such as constructor discovery.
• Optional unsafe mode for deserializing package-private classes, inner classes, and classes without accessible constructors (opt-in for security)
• Extensive configuration options via ReadOptionsBuilder and WriteOptionsBuilder
• Optionally parse JSON with unknown class references into a Map-of-Maps representation
• Featured on json.org

Cloud Native & Microservices

Optimized for modern cloud deployments and container environments:

• Zero Transitive Dependencies: Only depends on java-util, eliminating dependency conflicts in microservices architectures
• Object Graph Preservation: Essential for complex domain models in distributed systems - handles cycles and references that break other libraries
• Container-Ready: JPMS and OSGi support enables efficient packaging with jlink for minimal container images

Compatibility

JPMS (Java Platform Module System)

This library is fully compatible with JPMS, commonly known as Java Modules. It includes a module-info.class file that specifies module dependencies and exports.

JPMS Benefits:

• Explicit module boundaries for better isolation
• Works with jlink for custom JRE builds (<50MB runtime)
• Multi-release JAR with JDK 8 bytecode (class file format 52)

OSGi

This library also supports OSGi environments. It comes with pre-configured OSGi metadata in the MANIFEST.MF file, ensuring easy integration into any OSGi-based application.

OSGi Compatibility:

• Compatible with OSGi frameworks (Apache Karaf, Apache Felix, Eclipse Equinox)
• Standard OSGi bundle with proper Import-Package and Export-Package declarations
• Dynamic service loading support

Both of these features ensure that our library can be seamlessly integrated into modular Java applications, providing robust dependency management and encapsulation.

---

To include in your project:

Gradle

implementation 'com.cedarsoftware:json-io:4.63.0'

Maven

 <dependency>
   <groupId>com.cedarsoftware</groupId>
   <artifactId>json-io</artifactId>
   <version>4.63.0</version>
 </dependency>

---

User Guide

Usage

WriteOptions reference

ReadOptions reference

Revision History

Releases

4.63.0 (current)

• Version: 4.63.0
• Bundling: Both JPMS (Java Platform Module System) and OSGi (Open Service Gateway initiative)
• Maintained: Fully
• Java Package: com.cedarsoftware.io
• Java: JDK1.8+ (Class file 52 format, includes module-info.class - multi-release JAR)
• API
• Static methods on JsonIo: toJson(), toJava(), formatJson(), deepCopy()
• Use ReadOptionsBuilder and WriteOptionsBuilder to configure JsonIo
• Use JsonReader.ClassFactory for difficult classes (hard to instantiate & fill)
• Use JsonWriter.JsonClassWriter to customize the output JSON for a particular class
• Updates will be 4.64.0, 4.65.0, ...

4.14.x (supported)

• Version: 4.14.3
• Bundling: Both JPMS (Java Platform Module System) and OSGi (Open Service Gateway initiative)
• Maintained: Bug fixes, CVE's
• Java Package: com.cedarsoftware.util.io
• Java: JDK1.8+ (Class file 52 format, includes module-info.class - multi-release JAR)
• API
• Static methods on JsonReader: jsonToJava(), jsonToMaps(), special: jsonObjectsToJava()
• Static methods on JsonWriter: objectToJson()), formatJson()
• Configuration via Map with constants defined in JsonReader/JsonWriter.
• Use JsonReader.JsonClassReader or JsonReader.JsonClassReaderEx for customer reader
• Use JsonReader.assignInstantiator() when json-io cannot construct a particular class
• Use JsonWriter.JsonClassWriter or JsonWriter.JsonClassWriterEx to customize particular class output JSON
• Updates will be 4.14.4, 4.14.5, ...

Logging

By design, json-io limits its dependences to java-util and no other libraries, keeping it small and easy to work with. json-io uses the Java built-in java.util.logging for all output. See the user guide for ways to route these logs to SLF4J or Log4j 2.

Featured on json.org.

For useful Java utilities, check out java-util