https://github.com/xn32/json5k
JSON5 library for Kotlin
https://github.com/xn32/json5k
json5 kotlin kotlinx-serialization parser
Last synced: 6 months ago
JSON representation
JSON5 library for Kotlin
- Host: GitHub
- URL: https://github.com/xn32/json5k
- Owner: xn32
- License: apache-2.0
- Created: 2022-10-20T20:47:18.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2023-06-26T19:39:21.000Z (over 2 years ago)
- Last Synced: 2024-06-19T09:42:24.242Z (over 1 year ago)
- Topics: json5, kotlin, kotlinx-serialization, parser
- Language: Kotlin
- Homepage:
- Size: 254 KB
- Stars: 18
- Watchers: 1
- Forks: 2
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# json5k
[](https://github.com/xn32/json5k/actions/workflows/build.yml)
[](https://codecov.io/gh/xn32/json5k)
[](https://search.maven.org/artifact/io.github.xn32/json5k/)
[](https://s01.oss.sonatype.org/content/repositories/snapshots/io/github/xn32/)
[](https://xn32.github.io/json5k/api/)
This is an experimental [JSON5](https://json5.org/) library for Kotlin/JVM and Kotlin/Native.
It makes use of the [kotlinx.serialization](https://github.com/Kotlin/kotlinx.serialization) framework to serialize object hierarchies into standard-compliant JSON5 text and vice versa.
## Key features
- Compliance with [v1.0.0](https://spec.json5.org/1.0.0/) of the JSON5 specification
- Support for polymorphic types and configurable class discriminators
- Concise error messages for deserialization errors
- Support for the serialization of comments for class properties
- Rejection of duplicate keys during deserialization
## Setup instructions
json5k is available on [Maven Central](https://search.maven.org/artifact/io.github.xn32/json5k):
```kotlin
plugins {
kotlin("jvm") version "1.8.10"
kotlin("plugin.serialization") version "1.8.10"
}
repositories {
mavenCentral()
}
dependencies {
implementation("io.github.xn32:json5k:0.3.0")
}
```
Official versions are published for the following targets:
- Java Virtual Machine: `jvm`
- x86-64 platforms: `linuxX64`, `macosX64`, `iosX64`, `mingwX64`
- Apple Silicon platforms: `macosArm64`, `iosArm64`, `iosSimulatorArm64`
Snapshot versions of the `main` branch are available from [here](https://s01.oss.sonatype.org/content/repositories/snapshots/io/github/xn32/).
## Usage examples
### Non-hierarchical values
```kotlin
import io.github.xn32.json5k.Json5
import kotlinx.serialization.decodeFromString
import kotlinx.serialization.encodeToString
// Serialization:
Json5.encodeToString(5142) // 5142
Json5.encodeToString(listOf(4.5, 1.5e2, 1.2e15)) // [4.5,150.0,1.2E15]
Json5.encodeToString(mapOf("a" to 10, "b" to 20)) // {a:10,b:20}
Json5.encodeToString(Double.NEGATIVE_INFINITY) // -Infinity
Json5.encodeToString(null) // null
// Deserialization:
Json5.decodeFromString("113") // 113
Json5.decodeFromString>("[1.2, .4]") // [1.2, 0.4]
Json5.decodeFromString>("{ a: 10, 'b': 20, }") // {a=10, b=20}
Json5.decodeFromString("+Infinity") // Infinity
Json5.decodeFromString("null") // null
// Deserialization errors:
Json5.decodeFromString("190")
// UnexpectedValueError: signed integer in range [-128..127] expected at position 1:1
Json5.decodeFromString>("[ 1.0,,")
// CharError: unexpected character ',' at position 1:7
```
### Serializable classes
```kotlin
import io.github.xn32.json5k.Json5
import kotlinx.serialization.Serializable
import kotlinx.serialization.decodeFromString
import kotlinx.serialization.encodeToString
@Serializable
data class Person(val name: String, val age: UInt? = null)
// Serialization:
Json5.encodeToString(Person("John", 31u)) // {name:"John",age:31}
Json5.encodeToString(Person("Jane")) // {name:"Jane"}
// Deserialization:
Json5.decodeFromString("{ name: 'Carl' }") // Person(name=Carl, age=null)
Json5.decodeFromString("{ name: 'Carl', age: 42 }") // Person(name=Carl, age=42)
// Deserialization errors:
Json5.decodeFromString("{ name: 'Carl', age: 42, age: 10 }")
// DuplicateKeyError: duplicate key 'age' at position 1:26
```
### Classes with `@SerialName` annotations
```kotlin
import io.github.xn32.json5k.Json5
import kotlinx.serialization.SerialName
import kotlinx.serialization.Serializable
import kotlinx.serialization.decodeFromString
import kotlinx.serialization.encodeToString
@Serializable
data class IntWrapper(@SerialName("integer") val int: Int)
// Serialization:
Json5.encodeToString(IntWrapper(10)) // {integer:10}
// Deserialization:
Json5.decodeFromString("{ integer: 10 }") // IntWrapper(int=10)
// Deserialization errors:
Json5.decodeFromString("{ int: 10 }")
// UnknownKeyError: unknown key 'int' at position 1:3
```
### Polymorphic types
```kotlin
import io.github.xn32.json5k.ClassDiscriminator
import io.github.xn32.json5k.Json5
import kotlinx.serialization.SerialName
import kotlinx.serialization.Serializable
import kotlinx.serialization.decodeFromString
import kotlinx.serialization.encodeToString
@Serializable
@ClassDiscriminator("mode")
sealed interface Producer
@Serializable
@SerialName("numbers")
data class NumberProducer(val init: UInt) : Producer
// Serialization:
Json5.encodeToString(NumberProducer(10u)) // {mode:"numbers",init:10}
// Deserialization:
Json5.decodeFromString("{ init: 0, mode: 'numbers' }") // NumberProducer(init=0)
// Deserialization errors:
Json5.decodeFromString("{ init: 0 }")
// MissingFieldError: missing field 'mode' in object at position 1:1
```
### Serialization of comments for class properties
```kotlin
import io.github.xn32.json5k.Json5
import io.github.xn32.json5k.SerialComment
import kotlinx.serialization.Serializable
import kotlinx.serialization.encodeToString
@Serializable
data class Person(
val name: String,
val age: UInt? = null
)
@Serializable
data class Event(
@SerialComment("First day of the event")
val date: String,
@SerialComment("Registered attendees")
val attendees: List
)
val json5 = Json5 {
prettyPrint = true
}
println(
json5.encodeToString(
Event("2022-10-04", listOf(Person("Emma", 31u)))
)
)
```
Running this code will produce the following output:
```
{
// First day of the event
date: "2022-10-04",
// Registered attendees
attendees: [
{
name: "Emma",
age: 31
}
]
}
```
### Configuration options
Control generated JSON5 output as follows:
```kotlin
import io.github.xn32.json5k.Json5
import kotlinx.serialization.Serializable
import kotlinx.serialization.encodeToString
val json5 = Json5 {
prettyPrint = true
indentationWidth = 2
useSingleQuotes = true
quoteMemberNames = true
encodeDefaults = true
}
@Serializable
data class Person(val name: String, val age: UInt? = null)
println(json5.encodeToString(Person("Oliver")))
```
This will result in the following output:
```
{
'name': 'Oliver',
'age': null
}
```
### Further examples
See the unit tests for [serialization](src/commonTest/kotlin/io/github/xn32/json5k/binding/SerializationTest.kt)
and [deserialization](src/commonTest/kotlin/io/github/xn32/json5k/binding/DeserializationTest.kt) for more examples.