kaml

YAML support for kotlinx.serialization

License	The Apache License, Version 2.0
Categories	Data
GroupId	com.charleskorn.kaml
ArtifactId	kaml-metadata
Last Version	0.31.0
Release Date	Apr 25, 2021
Type	pom.sha512
Description	kaml YAML support for kotlinx.serialization
Project URL	https://github.com/charleskorn/kaml
Source Code Management	http://github.com/charleskorn/kaml

Download kaml-metadata

Filename	Size
kaml-metadata-0.31.0.pom
kaml-metadata-0.31.0-sources.jar	13 KB
kaml-metadata-0.31.0-javadoc.jar	261 bytes

Dependencies

compile (1)

Group / Artifact	Type	Version
org.jetbrains.kotlin : kotlin-stdlib-jdk8	jar	1.4.32

Project Modules

There are no modules declared in this project.

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.decodeFromString(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.encodeToString(Team.serializer(), input)

println(result)

Referencing kaml

Add the following to your Gradle build script:

Groovy DSL

plugins {
    id 'org.jetbrains.kotlin.jvm' version '1.4.20'
    id 'org.jetbrains.kotlin.plugin.serialization' version '1.4.20'
}

dependencies {
  implementation "com.charleskorn.kaml:kaml:<version number here>" // Get the latest version number from https://github.com/charleskorn/kaml/releases/latest
}

Kotlin DSL

plugins {
    kotlin("jvm") version "1.4.20"
    kotlin("plugin.serialization") version "1.4.20"
}

dependencies {
  implementation("com.charleskorn.kaml:kaml:<version number here>") // Get the latest version number from https://github.com/charleskorn/kaml/releases/latest
}

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.

Features

• 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 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)
  
    @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 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.

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

Versions

Version
0.31.0 Apr 25, 2021
0.30.0 Apr 6, 2021
0.29.0 Mar 23, 2021