json5-kotlin

JSON5 Implementation for Kotlin/JVM
✨ JSON5 Support 🔧 kotlinx.serialization ⚡ High Performance 🛡️ Type Safe

About json5-kotlin

A robust JSON5 parser and serializer for Kotlin that extends JSON with helpful features like comments, trailing commas, and unquoted keys while maintaining full backward compatibility with JSON.

🚀Modern Architecture

Built with kotlinx.serialization for seamless integration with Kotlin projects and type-safe serialization.

🔄Full Compatibility

All valid JSON is valid JSON5, ensuring backward compatibility with existing JSON data.

⚙️Easy Integration

Simple drop-in replacement for standard JSON with enhanced functionality.

📊Performance Tested

Thoroughly benchmarked against other implementations to ensure reliable performance.

Ready to get started?

Add JSON5 support to your Kotlin project in minutes

View on GitHub Quick Start Guide

JSON5 Features

JSON5 extends JSON with the following developer-friendly features:

💬Comments

Both line comments // and block comments /* */ are supported.

{
  // This is a line comment
  "name": "John", /* block comment */
  "age": 30
}

🔤Unquoted Keys

Object keys can be unquoted if they're valid identifiers.

{
  name: "John",
  age: 30,
  isActive: true
}

✂️Trailing Commas

Trailing commas are allowed in objects and arrays.

{
  "items": [
    "apple",
    "banana",  // ← trailing comma OK
  ],
}

📝Single Quotes

Strings can use single quotes in addition to double quotes.

{
  'name': 'John',
  "age": 30
}

📏Multi-line Strings

Strings can span multiple lines with backslash at line end.

{
  "description": "This is a \
very long string that \
spans multiple lines"
}

🔢Extended Numbers

Support for hexadecimal, infinity, NaN, and leading/trailing decimal points.

{
  hex: 0xFF,
  leadingDecimal: .5,
  trailingDecimal: 2.,
  infinity: Infinity,
  notANumber: NaN
}

Quick Start Guide

Installation

Add the dependency to your build.gradle.kts:

repositories {
    maven {
        name = "GitHubPackages"
        url = uri("https://maven.pkg.github.com/hossain-khan/json5-kotlin")
        credentials {
            username = project.findProperty("gpr.user") as String? ?: System.getenv("USERNAME")
            password = project.findProperty("gpr.key") as String? ?: System.getenv("TOKEN")
        }
    }
}

dependencies {
    implementation("hossain.dev:json5kt:1.2.0") // Or, latest release
}

Basic Usage

import dev.hossain.json5kt.JSON5

// Parse JSON5 string
val json5String = """
{
  // User information
  name: 'John Doe',
  age: 30,
  skills: [
    'Kotlin',
    'JSON5',  // trailing comma
  ],
}
"""

val user = JSON5.decodeFromString<User>(json5String)

// Serialize to JSON5
val json5Output = JSON5.encodeToString(user)

Integration with kotlinx.serialization

@Serializable
data class User(
    val name: String,
    val age: Int,
    val skills: List<String>
)

// Configure JSON5 with custom settings
val json5 = JSON5 {
    prettyPrint = true
    ignoreUnknownKeys = true
}

val user = json5.decodeFromString<User>(json5String)

Need Help?

Check out the full documentation and examples

View Documentation Example App

JSON5 Performance Benchmark

Interactive Performance Comparison: JSON5 vs JSON vs External-JSON5

Generated from benchmark data: June 25, 2025

JSON5 (This Project)
kotlinx.serialization integration
JSON (Standard)
kotlinx.serialization baseline
External-JSON5
at.syntaxerror.json5:2.1.0

Key Performance Insights

4.45×
JSON faster than JSON5
2.51×
JSON faster than External-JSON5
1.77×
External-JSON5 faster than JSON5
0.149ms
JSON5 average time
0.033ms
JSON average time
0.084ms
External-JSON5 average time
Performance by Data Type and Operation
Serialization vs Deserialization Performance
Overall Performance Comparison (Lower is Better)
Performance Ratios - How Many Times Slower

Methodology

Test Environment: JVM warmup with 100 iterations, followed by 1000 iterations per test case.

Data Types: SimplePerson, ComplexPerson, Company, NumberTypes, CollectionTypes, SimplePersonList100, ComplexPersonList50

Operations: Serialization (object to JSON string) and Deserialization (JSON string to object)

Libraries:

  • JSON5: This project's implementation with kotlinx.serialization integration
  • JSON: Standard kotlinx.serialization JSON implementation (baseline)
  • External-JSON5: at.syntaxerror.json5:2.1.0 library