A concise and lightweight Kotlin DSL to build JSON objects and render their String representations
Using no other dependency than Kotlin
Available on Maven Central
// for an empty object
obj { }
// for an object
obj {
"attribute" to 42
"another" to true
}
// for an empty array
arr
// for an array
arr["element", 12.345, null]|
Note
|
Any combination of these elements is possible |
val obj = obj {
"key" to 3.4
"anotherKey" to arr["test", "test2", 1, 2.433, true]
"nullValue" to null
"emptyObject" to obj { }
"emptyArray" to arr
"custom" to Date()
}
println(obj) (1)
println(obj.pretty()) (2)(1)
{"key":3.4,"anotherKey":["test","test2",1,2.433,true],"nullValue":null,"emptyObject":{},"emptyArray":[],"custom":"Tue Dec 11 13:14:14 CET 2018"}
(2)
{
"key": 3.4,
"anotherKey": [
"test",
"test2",
1,
2.433,
true
],
"nullValue": null,
"emptyObject": {
},
"emptyArray": [
],
"custom": "Tue Dec 11 13:14:14 CET 2018"
}val array = arr[
"example",
obj {
"apple" to "pie"
"key" to 3.14
"anotherKey" to arr["first", "second", 1, 2.433, true]
}
]
println(array) (1)
println(array.pretty()) (2)(1)
["example",{"apple":"pie","key":3.14,"anotherKey":["first","second",1,2.433,true]}]
(2)
[
"example",
{
"apple": "pie",
"key": 3.14,
"anotherKey": [
"first",
"second",
1,
2.433,
true
]
}
]When using the pretty() method on obj or arr, you can define the number of whitespaces used for tabulation. Default value is 2.
// "compact", single line mode
obj { ... }
// 2 whitespaces tabulation
obj { ... }.pretty()
// 3 whitespaces tabulation
arr[ ... ].pretty(3)If you know what the content you will render, you should favor using DSL elements to build your Json.
However, sometimes you may need to include an external source of Json. You can use the rawJson(validJson: String?) method to do so.
obj {
"rawContent" to rawJson(externalJsonSource())
}|
Warning
|
You need to ensure the parameter Beware that rendering will not escape |
|
Note
|
pretty() will not work on rawJson Strings, however toString() will inline provided content
|
-
A JSON key (attribute) can only be of
KotlintypeString(will render escaping"and\chars)
|
Note
|
In IntelliJ, a compilation error will appear, and code will be flagged as not reachable
|
-
A JSON value of an obj { } or an arr[…] can be one of the following
Kotlinor Koson DSL instances-
String?(will render escaping"and\chars) -
Number? -
Boolean? -
Any?(will render using.toString(), escaping"and\chars) -
null -
obj { }
-
arr[…]
-
arr (empty array)
-
rawJson("{…}") (will render as is)
-
Benchmarks have been conducted with the jmh OpenJDK tool. Benchmark project can be found under benchmarks folder.
Two tests were done with the same objects and arrays
-
Rendering a big object (String representation)
-
Rendering a big array (String representation)
Kson was put side to side with one of the most popular JSON builder for Java : JSON-java
Testing environment : 3.3 GHz Intel Core i5-6600, 4 cores, VM version: OpenJDK 11.0.1, 64-Bit Server VM, 11.0.1+13
| Benchmark | Score | Error | Units |
|---|---|---|---|
BigObject - JSON-java |
17120,661 |
± 45,741 |
ops/s |
BigObject - Koson |
17433,982 |
± 372,361 |
ops/s |
BigObject (pretty) - JSON-java |
8902,486 |
± 19,417 |
ops/s |
BigObject (pretty) - Koson |
10252,254 |
± 71,377 |
ops/s |
BigArray - JSON-java |
15272,946 |
± 139,435 |
ops/s |
BigArray - Koson |
14816,130 |
± 132,266 |
ops/s |
BigArray (pretty) - JSON-java |
7744,935 |
± 41,067 |
ops/s |
BigArray (pretty) - Koson |
8607,388 |
± 31,712 |
ops/s |
To run the tests locally with java 8 or later, do
cd benchmarks
mvn clean install
java -jar target/benchmarks.jar