kaml

What is this?

This library adds YAML support to kotlinx.serialization.

YAML version 1.2 is supported.

Usage samples

Parsing from YAML to a Kotlin object

@Serializable
data class Team(
    val leader: String,
    val members: List<String>
)

val input = """
        leader: Amy
        members:
          - Bob
          - Cindy
          - Dan
    """.trimIndent()

val result = Yaml.default.parse(Team.serializer(), input)

println(result)

Serializing from a Kotlin object to YAML

@Serializable
data class Team(
    val leader: String,
    val members: List<String>
)

val input = Team("Amy", listOf("Bob", "Cindy", "Dan"))

val result = Yaml.default.stringify(Team.serializer(), input)

println(result)

Supported YAML features

Scalars, including strings, booleans, integers and floats
Sequences (lists)
Maps
Nulls
Aliases and anchors
Merging aliases to form one map
Docker Compose-style extension fields

Specify the extension prefix by setting extensionDefinitionPrefix when creating an instance of Yaml.

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.

Referencing kaml

Add the following to your Gradle build script:

implementation("com.charleskorn.kaml:kaml:<version number here>")

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.

Contributing to kaml

Pull requests and bug reports are always welcome!

kaml uses batect to simplify development environment setup:

To build the library: ./batect build
To run the tests and static analysis tools: ./batect check
To run the tests and static analysis tools continuously: ./batect continuousCheck

Other commands are available by running ./batect --list-tasks

Reference links

YAML 1.2 Specification
snakeyaml-engine, the YAML parser this library is based on

HeartPattern/kaml