This library adds YAML support to kotlinx.serialization.
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)
-
Supports most major YAML features:
- Scalars, including strings, booleans, integers and floats
- Sequences (lists)
- Maps
- Nulls
- Aliases and anchors, including merging aliases to form one map
-
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 ofYaml
):-
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) @SerialName("backend") @Serializable data class Backend(val database: String) } @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: [email protected] 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: [email protected] cost-centre: myteam kind: backend
Specify the extension prefix by setting
YamlConfiguration.extensionDefinitionPrefix
when creating an instance ofYaml
(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.
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.
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
- YAML 1.2 Specification
- snakeyaml-engine, the YAML parser this library is based on