0.25.0

What's changed

• New: YamlMap now has a getKey() method that returns the YamlScalar for the given key in the map.
• Updated: kaml is now built against kotlinx-serialization 1.0.0.

Upgrading

If you're using Gradle, reference kaml in your dependencies block like this:

implementation("com.charleskorn.kaml:kaml:0.25.0")

For other tools, refer to the Maven Central release page for more information.

0.24.0

What's changed

• New: all exceptions thrown during parsing now have the concept of a path, which shows the route taken to get to the location of the error. This makes it much easier to understand where an error is located, especially when merging or aliases are involved. (#37 - thanks to @Vampire for the issue report)

  For example, given the following input YAML:

  colours:
  - name: primary
    r: 100
    g: 200
    b: 203

  If the value primary is invalid for name, the exception would include the path colours[0].name.

  The path in included in toString() for all exceptions.

• Improved: the error message shown when an object has multiple merges (<< keys) has been clarified.

• Improved: YamlNode and subclasses now have a much clearer toString() output, which should make debugging custom deserializers much easier.

• ⚠️ Breaking change: YamlMap now only allows scalars as keys. This should not impact most users as decoding a YAML map with non-scalar keys previously threw an exception anyway.

Upgrading

If you're using Gradle, reference kaml in your dependencies block like this:

implementation("com.charleskorn.kaml:kaml:0.24.0")

For other tools, refer to the Maven Central release page for more information.

0.23.0

What's changed

• New: it is now possible to customise the property name used when encoding and decoding polymorphic types, similar to the classDiscriminator option for kotlinx-serialization's built-in JSON format (#47 - thanks to @ChanTsune for the PR)

  Set YamlConfiguration.polymorphismPropertyName to configure this. The default value is type to preserve the existing default behaviour.

Upgrading

If you're using Gradle, reference kaml in your dependencies block like this:

implementation("com.charleskorn.kaml:kaml:0.23.0")

For other tools, refer to the Maven Central release page for more information.

0.22.0

What's changed

• Updated: kaml is now built with Kotlin 1.4.10.

Upgrading

If you're using Gradle, reference kaml in your dependencies block like this:

implementation("com.charleskorn.kaml:kaml:0.22.0")

For other tools, refer to the Maven Central release page for more information.

0.21.0

What's changed

• New: it is now possible to configure the style for emitted lists and sequences by setting YamlConfiguration.sequenceStyle (#40 - thanks to @knightzmc for the suggestion and PR)

  For example, for the list 1, 2, 3, block style (which was the previous behaviour and is still the default) would emit the list as:

  - 1
  - 2
  - 3

  And in flow style, it would be emitted as:

  [1, 2, 3]

Upgrading

If you're using Gradle, reference kaml in your dependencies block like this:

implementation("com.charleskorn.kaml:kaml:0.21.0")

For other tools, refer to the Maven Central release page for more information.

0.20.0

What's changed

• New: YamlMap now has get(key) and getScalar(key) methods that return the YAML node or scalar value (respectively) in the map for key (#32 - thanks to @Vampire for the suggestion)

• New: it is now possible to change the indentation level and maximum scalar value width when encoding values to YAML (#33 - thanks to @Vampire for the suggestion)

  Set encodingIndentationSize or breakScalarsAt on YamlConfiguration to alter the default values (indent by two spaces, and split scalars onto a new line at 80 characters).

• New: calling toString() on an exception now includes line and column numbers in the result, for example: com.charleskorn.kaml.YamlException at line 123, column 456: Something went wrong (#36 - thanks to @Vampire for the suggestion)

• Changed: ⚠️ Potentially breaking change: Kotlin 1.4's explicit API mode has been enabled. Some internal APIs that were previously exposed are now correctly marked as internal.

  If you were relying on these previously public APIs, please file an issue explaining your use case.

Upgrading

If you're using Gradle, reference kaml in your dependencies block like this:

implementation("com.charleskorn.kaml:kaml:0.20.0")

For other tools, refer to the Maven Central release page for more information.

0.19.0

What's changed

• Updated: kaml is built against Kotlin 1.4 and kotlinx.serialization 1.0.0-RC.

  ⚠️ Potentially breaking change: Note that this introduces two breaking changes to maintain consistency with the built-in formats and the StringFormat interface:

  • Yaml.parse() is now Yaml.decodeFromString()
  • Yaml.stringify() is now Yaml.encodeToString()

Upgrading

If you're using Gradle, reference kaml in your dependencies block like this:

implementation("com.charleskorn.kaml:kaml:0.19.0")

For other tools, refer to the Maven Central release page for more information.

0.18.1

What's changed

• Fixed: using a contextual serializer as the top-level deserializer for an object could fail with errors like Expected an object, but got a list, or Can't decode YAML map into LIST

Upgrading

If you're using Gradle, reference kaml in your dependencies block like this:

implementation("com.charleskorn.kaml:kaml:0.18.1")

For other tools, refer to the Maven Central release page for more information.

0.18.0

What's changed

• New: kaml now supports working with polymorphic types where the type is specified as a type property in YAML (#11 - thanks to @gps for the suggestion).

  This means that there are now two styles available for working with polymorphic types (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.stringify(Config.serializer(), config)
  
  println(result)

• Updated: kaml is now built against Kotlin 1.3.72.

• Changed: clearer exceptions will now be thrown in the following cases:

  • missing tag when deserializing a polymorphic type when using tags for polymorphic type information
  • unknown polymorphic type in tag or type property
  • missing required property for object

Upgrading

If you're using Gradle, reference kaml in your dependencies block like this:

implementation("com.charleskorn.kaml:kaml:0.18.0")

For other tools, refer to the Maven Central release page for more information.

0.17.0

What's changed

• Updated: kaml is now built against Kotlin 1.3.71.

Upgrading

If you're using Gradle, reference kaml in your dependencies block like this:

implementation("com.charleskorn.kaml:kaml:0.17.0")

For other tools, refer to the Maven Central release page for more information.