{"id":22281138,"url":"https://github.com/charleskorn/kaml","last_synced_at":"2025-05-14T21:09:18.368Z","repository":{"id":38361141,"uuid":"161928584","full_name":"charleskorn/kaml","owner":"charleskorn","description":"YAML support for kotlinx.serialization","archived":false,"fork":false,"pushed_at":"2025-04-10T02:49:25.000Z","size":2339,"stargazers_count":542,"open_issues_count":7,"forks_count":56,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-04-10T03:33:24.490Z","etag":null,"topics":["kotlin","serialization","yaml"],"latest_commit_sha":null,"homepage":"","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/charleskorn.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-12-15T17:31:13.000Z","updated_at":"2025-04-10T02:37:49.000Z","dependencies_parsed_at":"2024-03-14T20:30:06.754Z","dependency_job_id":"d1ba623f-e9b3-4167-9a2a-fe7eb95b4755","html_url":"https://github.com/charleskorn/kaml","commit_stats":null,"previous_names":[],"tags_count":89,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charleskorn%2Fkaml","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charleskorn%2Fkaml/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charleskorn%2Fkaml/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charleskorn%2Fkaml/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/charleskorn","download_url":"https://codeload.github.com/charleskorn/kaml/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248166925,"owners_count":21058481,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["kotlin","serialization","yaml"],"created_at":"2024-12-03T16:14:55.918Z","updated_at":"2025-04-10T06:13:50.736Z","avatar_url":"https://github.com/charleskorn.png","language":"Kotlin","funding_links":[],"categories":["kotlin"],"sub_categories":[],"readme":"# kaml\n\n[![Pipeline](https://github.com/charleskorn/kaml/actions/workflows/build.yml/badge.svg)](https://github.com/charleskorn/kaml/actions/workflows/build.yml)\n[![Coverage](https://img.shields.io/codecov/c/github/charleskorn/kaml.svg)](https://codecov.io/gh/charleskorn/kaml)\n[![License](https://img.shields.io/github/license/charleskorn/kaml.svg)](https://opensource.org/licenses/Apache-2.0)\n[![Maven Central](https://img.shields.io/maven-central/v/com.charleskorn.kaml/kaml.svg?label=maven%20central)](https://search.maven.org/search?q=g:%22com.charleskorn.kaml%22%20AND%20a:%22kaml%22)\n\n## What is this?\n\nThis library adds YAML support to [kotlinx.serialization](https://github.com/Kotlin/kotlinx.serialization/).\n\nCurrently, only Kotlin/JVM is fully supported.\n\nKotlin/JS and Kotlin/Wasm support are considered highly experimental. It is not yet fully functional, and may be removed or modified at any time.\n\n(Follow [this issue](https://github.com/charleskorn/kaml/issues/232) for a discussion of adding support for other targets.)\n\nYAML version 1.2 is supported.\n\n## Usage samples\n\n### Parsing from YAML to a Kotlin object\n\n```kotlin\n@Serializable\ndata class Team(\n    val leader: String,\n    val members: List\u003cString\u003e\n)\n\nval input = \"\"\"\n        leader: Amy\n        members:\n          - Bob\n          - Cindy\n          - Dan\n    \"\"\".trimIndent()\n\nval result = Yaml.default.decodeFromString(Team.serializer(), input)\n\nprintln(result)\n```\n\n### Serializing from a Kotlin object to YAML\n\n```kotlin\n@Serializable\ndata class Team(\n    val leader: String,\n    val members: List\u003cString\u003e\n)\n\nval input = Team(\"Amy\", listOf(\"Bob\", \"Cindy\", \"Dan\"))\n\nval result = Yaml.default.encodeToString(Team.serializer(), input)\n\nprintln(result)\n```\n\n### Parsing into YamlNode\n\nIt is possible to parse a string or an InputStream directly into a YamlNode, for example\nthe following code prints `Cindy`.\n```kotlin\nval input = \"\"\"\n        leader: Amy\n        members:\n          - Bob\n          - Cindy\n          - Dan\n    \"\"\".trimIndent()\n\nval result = Yaml.default.parseToYamlNode(input)\n\nprintln(\n    result\n        .yamlMap.get\u003cYamlList\u003e(\"members\")!![1]\n        .yamlScalar\n        .content\n)\n```\n\n## Referencing kaml\n\nAdd the following to your Gradle build script:\n\n**Groovy DSL**\n\n```groovy\nplugins {\n    id 'org.jetbrains.kotlin.jvm' version '1.4.20'\n    id 'org.jetbrains.kotlin.plugin.serialization' version '1.4.20'\n}\n\ndependencies {\n  implementation \"com.charleskorn.kaml:kaml:\u003cversion number here\u003e\" // Get the latest version number from https://github.com/charleskorn/kaml/releases/latest\n}\n```\n\n**Kotlin DSL**\n\n```kotlin\nplugins {\n    kotlin(\"jvm\") version \"1.4.20\"\n    kotlin(\"plugin.serialization\") version \"1.4.20\"\n}\n\ndependencies {\n  implementation(\"com.charleskorn.kaml:kaml:\u003cversion number here\u003e\") // Get the latest version number from https://github.com/charleskorn/kaml/releases/latest\n}\n```\n\nCheck the [releases page](https://github.com/charleskorn/kaml/releases) for the latest release information,\nand the [Maven Central page](https://search.maven.org/artifact/com.charleskorn.kaml/kaml) for examples of how\nto reference the library in other build systems.\n\n## Features\n\n* Supports most major YAML features:\n  * Scalars, including strings, booleans, integers and floats\n  * [Sequences (lists)](https://yaml.org/type/seq.html)\n  * [Maps](https://yaml.org/type/map.html)\n  * [Nulls](https://yaml.org/type/null.html)\n  * [Aliases and anchors](https://yaml.org/spec/1.2/spec.html#id2765878), including [merging aliases to form one map](https://yaml.org/type/merge.html)\n\n* Supports parsing YAML to Kotlin objects (deserializing) and writing Kotlin objects as YAML (serializing)\n\n* Supports [kotlinx.serialization's polymorphism](https://github.com/Kotlin/kotlinx.serialization/blob/master/docs/polymorphism.md) for sealed and unsealed types\n\n  Two styles are available (set `YamlConfiguration.polymorphismStyle` when creating an instance of `Yaml`):\n\n  * using [YAML tags](https://yaml.org/spec/1.2/spec.html#id2761292) to specify the type:\n\n    ```yaml\n    servers:\n      - !\u003cfrontend\u003e\n        hostname: a.mycompany.com\n      - !\u003cbackend\u003e\n        database: db-1\n    ```\n\n  * using a `type` property to specify the type:\n\n    ```yaml\n    servers:\n      - type: frontend\n        hostname: a.mycompany.com\n      - type: backend\n        database: db-1\n    ```\n\n  The fragments above could be generated with:\n\n  ```kotlin\n  @Serializable\n  sealed class Server {\n    @SerialName(\"frontend\")\n    @Serializable\n    data class Frontend(val hostname: String) : Server()\n\n    @SerialName(\"backend\")\n    @Serializable\n    data class Backend(val database: String) : Server()\n  }\n\n  @Serializable\n  data class Config(val servers: List\u003cServer\u003e)\n\n  val config = Config(listOf(\n    Frontend(\"a.mycompany.com\"),\n    Backend(\"db-1\")\n  ))\n\n  val result = Yaml.default.encodeToString(Config.serializer(), config)\n\n  println(result)\n  ```\n\n* Supports [Docker Compose-style extension fields](https://medium.com/@kinghuang/docker-compose-anchors-aliases-extensions-a1e4105d70bd)\n\n  ```yaml\n  x-common-labels: \u0026common-labels\n    labels:\n      owned-by: myteam@mycompany.com\n      cost-centre: myteam\n\n  servers:\n    server-a:\n      \u003c\u003c: *common-labels\n      kind: frontend\n\n    server-b:\n      \u003c\u003c: *common-labels\n      kind: backend\n\n    # server-b and server-c are equivalent\n    server-c:\n      labels:\n        owned-by: myteam@mycompany.com\n        cost-centre: myteam\n      kind: backend\n  ```\n\n  Specify the extension prefix by setting `YamlConfiguration.extensionDefinitionPrefix` when creating an instance of `Yaml` (eg. `\"x-\"` for the example above).\n\n  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 (`\u0026...`) and will not be included in the deserialised value.\n\n## Contributing to kaml\n\nPull requests and bug reports are always welcome!\n\nkaml uses Gradle for builds and testing:\n\n* To build the library: `./gradlew assemble`\n* To run the tests and static analysis tools: `./gradlew check`\n* To run the tests and static analysis tools continuously: `./gradlew --continuous check`\n\n## Reference links\n\n* [YAML 1.2 Specification](http://yaml.org/spec/1.2/spec.html)\n* [snakeyaml-engine-kmp](https://github.com/krzema12/snakeyaml-engine-kmp), a Kotlin Multiplatform port of [snakeyaml-engine](https://bitbucket.org/snakeyaml/snakeyaml-engine/wiki/Home), the YAML parser this library is based on\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcharleskorn%2Fkaml","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcharleskorn%2Fkaml","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcharleskorn%2Fkaml/lists"}