YAML 1.2 serializer/deserializer integrating with a serialization framework, handling scalars, maps, sequences, anchors/aliases, polymorphism styles, and Docker Compose–style extension fields.
kotaml is a supported fork of kaml by Charles Korn.
This library adds YAML support to kotlinx.serialization.
Currently, only Kotlin/JVM is fully supported.
Kotlin/JS and Kotlin/Wasm support are considered highly experimental. It is not yet fully functional, and may be removed or modified at any time.
YAML version 1.2 is supported.
@Serializable
data class Team(
val leader: String,
val members: List<String>
)
val input = """
leader: Amy
members:
- Bob
- Cindy
- Dan
""".trimIndent()
val result = Yaml.default.decodeFromString(Team.serializer(), input)
println(result)
@Serializable
data class Team(
val leader: String,
val members: List<String>
)
val input = Team("Amy", listOf("Bob", "Cindy", "Dan"))
val result = Yaml.default.encodeToString(Team.serializer(), input)
println(result)
It is possible to parse a string or an InputStream directly into a YamlNode, for example
the following code prints Cindy.
val input = """
leader: Amy
members:
- Bob
- Cindy
- Dan
""".trimIndent()
val result = Yaml.default.parseToYamlNode(input)
println(
result
.yamlMap.get<YamlList>("members")!![1]
.yamlScalar
.content
)
Add the following to your Gradle build script:
plugins {
kotlin("jvm").version("2.4.0")
kotlin("plugin.serialization").version("2.4.0")
}
dependencies {
implementation("io.heapy.kotaml:kotaml:0.110.0")
}
Check the releases page for the latest release information, and the Maven Central page for examples of how to reference the library in other build systems.
Pull requests and bug reports are always welcome!
kotaml uses Gradle for builds and testing:
./gradlew assemble./gradlew check./gradlew --continuous checkSupports most major YAML features:
Supports parsing YAML to Kotlin objects (deserializing) and writing Kotlin objects as YAML (serializing)
Supports kotlinx.serialization's polymorphism for sealed and unsealed types
Two styles are available (set YamlConfiguration.polymorphismStyle when creating an instance of Yaml):
using YAML tags to specify the type:
servers:
- !<frontend>
hostname: a.mycompany.com
- !<backend>
database: db-1
using a type property to specify the type:
servers:
- type: frontend
hostname: a.mycompany.com
- type: backend
database: db-1
The fragments above could be generated with:
@Serializable
sealed class Server {
@SerialName("frontend")
@Serializable
data class Frontend(val hostname: String) : Server()
@SerialName("backend")
@Serializable
data class Backend(val database: String) : Server()
}
@Serializable
data class Config(val servers: List<Server>)
val config = Config(listOf(
Frontend("a.mycompany.com"),
Backend("db-1")
))
val result = Yaml.default.encodeToString(Config.serializer(), config)
println(result)
Supports Docker Compose-style extension fields
x-common-labels: &common-labels
labels:
owned-by: myteam@mycompany.com
cost-centre: myteam
servers:
server-a:
<<: *common-labels
kind: frontend
server-b:
<<: *common-labels
kind: backend
# server-b and server-c are equivalent
server-c:
labels:
owned-by: myteam@mycompany.com
cost-centre: myteam
kind: backend
Specify the extension prefix by setting YamlConfiguration.extensionDefinitionPrefix when creating an instance of Yaml (eg. "x-" for the example above).
Extensions can only be defined at the top level of a document, and only if the top level element is a map or object. Any key starting with the extension prefix must have an anchor defined (&...) and will not be included in the deserialised value.
Surfaced from shared tags and platforms — no rankings paid for.