{"id":13407059,"url":"https://github.com/Kotlin/kotlinx.serialization","last_synced_at":"2025-03-14T11:30:56.863Z","repository":{"id":37417574,"uuid":"97827246","full_name":"Kotlin/kotlinx.serialization","owner":"Kotlin","description":"Kotlin multiplatform / multi-format serialization ","archived":false,"fork":false,"pushed_at":"2025-03-07T11:14:21.000Z","size":10661,"stargazers_count":5554,"open_issues_count":268,"forks_count":636,"subscribers_count":100,"default_branch":"master","last_synced_at":"2025-03-10T04:45:03.295Z","etag":null,"topics":["cbor","json","kotlin","protobuf","serialization"],"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/Kotlin.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-07-20T11:25:23.000Z","updated_at":"2025-03-10T04:18:22.000Z","dependencies_parsed_at":"2024-01-12T20:10:51.977Z","dependency_job_id":"a9a7e059-35d2-46e3-909d-ee2cb0b3702a","html_url":"https://github.com/Kotlin/kotlinx.serialization","commit_stats":{"total_commits":1270,"total_committers":183,"mean_commits":6.939890710382514,"dds":0.5,"last_synced_commit":"db217e4ca83715eb0bd2b0777c5428f8c060eac2"},"previous_names":[],"tags_count":58,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kotlin%2Fkotlinx.serialization","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kotlin%2Fkotlinx.serialization/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kotlin%2Fkotlinx.serialization/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kotlin%2Fkotlinx.serialization/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Kotlin","download_url":"https://codeload.github.com/Kotlin/kotlinx.serialization/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243048124,"owners_count":20227592,"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":["cbor","json","kotlin","protobuf","serialization"],"created_at":"2024-07-30T20:00:18.830Z","updated_at":"2025-03-14T11:30:56.846Z","avatar_url":"https://github.com/Kotlin.png","language":"Kotlin","funding_links":[],"categories":["Libraries","开源库","Kotlin","Android 应用","Android Kotlin Project Showcase","必备开发库","Serializer","json"],"sub_categories":["序列化","Serializer","🗃 Serializer","网络服务_其他","Kotlin 基础","Bluetooth"],"readme":"# Kotlin multiplatform / multi-format reflectionless serialization\n\n[![Kotlin Stable](https://kotl.in/badges/stable.svg)](https://kotlinlang.org/docs/components-stability.html)\n[![JetBrains official project](https://jb.gg/badges/official.svg)](https://confluence.jetbrains.com/display/ALL/JetBrains+on+GitHub)\n[![GitHub license](https://img.shields.io/badge/license-Apache%20License%202.0-blue.svg?style=flat)](http://www.apache.org/licenses/LICENSE-2.0)\n[![TeamCity build](https://img.shields.io/teamcity/http/teamcity.jetbrains.com/s/KotlinTools_KotlinxSerialization_Ko.svg)](https://teamcity.jetbrains.com/viewType.html?buildTypeId=KotlinTools_KotlinxSerialization_Ko\u0026guest=1)\n[![Kotlin](https://img.shields.io/badge/kotlin-2.1.0-blue.svg?logo=kotlin)](http://kotlinlang.org)\n[![Maven Central](https://img.shields.io/maven-central/v/org.jetbrains.kotlinx/kotlinx-serialization-core/1.8.0)](https://central.sonatype.com/artifact/org.jetbrains.kotlinx/kotlinx-serialization-core/1.8.0)\n[![KDoc link](https://img.shields.io/badge/API_reference-KDoc-blue)](https://kotlinlang.org/api/kotlinx.serialization/)\n[![Slack channel](https://img.shields.io/badge/chat-slack-blue.svg?logo=slack)](https://kotlinlang.slack.com/messages/serialization/)\n\nKotlin serialization consists of a compiler plugin, that generates visitor code for serializable classes,\n runtime library with core serialization API and support libraries with various serialization formats.\n\n* Supports Kotlin classes marked as `@Serializable` and standard collections.\n* Provides [JSON](formats/README.md#JSON), [Protobuf](formats/README.md#ProtoBuf), [CBOR](formats/README.md#CBOR), [Hocon](formats/README.md#HOCON) and [Properties](formats/README.md#properties) formats.\n* Complete multiplatform support: JVM, JS and Native.\n\n## Table of contents\n\n\u003c!--- TOC --\u003e\n\n* [Introduction and references](#introduction-and-references)\n* [Setup](#setup)\n  * [Gradle](#gradle)\n    * [1) Setting up the serialization plugin](#1-setting-up-the-serialization-plugin)\n    * [2) Dependency on the JSON library](#2-dependency-on-the-json-library)\n  * [Android](#android)\n  * [Multiplatform (Common, JS, Native)](#multiplatform-common-js-native)\n  * [Maven](#maven)\n  * [Bazel](#bazel)\n\n\u003c!--- END --\u003e\n\n* **Additional links**\n  * [Kotlin Serialization Guide](docs/serialization-guide.md)\n  * [Full API reference](https://kotlinlang.org/api/kotlinx.serialization/)\n  * [Submitting issues and PRs](CONTRIBUTING.md)\n  * [Building this library](docs/building.md)\n\n## Introduction and references\n\nHere is a small example.\n\n```kotlin\nimport kotlinx.serialization.*\nimport kotlinx.serialization.json.*\n\n@Serializable \ndata class Project(val name: String, val language: String)\n\nfun main() {\n    // Serializing objects\n    val data = Project(\"kotlinx.serialization\", \"Kotlin\")\n    val string = Json.encodeToString(data)  \n    println(string) // {\"name\":\"kotlinx.serialization\",\"language\":\"Kotlin\"} \n    // Deserializing back into objects\n    val obj = Json.decodeFromString\u003cProject\u003e(string)\n    println(obj) // Project(name=kotlinx.serialization, language=Kotlin)\n}\n``` \n\n\u003e You can get the full code [here](guide/example/example-readme-01.kt).\n\n\u003c!--- TEST_NAME ReadmeTest --\u003e\n\n\u003c!--- TEST \n{\"name\":\"kotlinx.serialization\",\"language\":\"Kotlin\"}\nProject(name=kotlinx.serialization, language=Kotlin)\n--\u003e\n\n**Read the [Kotlin Serialization Guide](docs/serialization-guide.md) for all details.**\n\nYou can find auto-generated documentation website on [kotlinlang.org](https://kotlinlang.org/api/kotlinx.serialization/).\n\n## Setup\n\n[New versions](https://plugins.gradle.org/plugin/org.jetbrains.kotlin.plugin.serialization) of the serialization plugin are released in tandem with each new Kotlin compiler version.\n\nUsing Kotlin Serialization requires Kotlin compiler `1.4.0` or higher.\nMake sure you have the corresponding Kotlin plugin installed in the IDE, no additional plugins for IDE are required.\n\n### Gradle\n\nTo set up kotlinx.serialization, you have to do two things:\n1) Add the **[serialization plugin](#1-setting-up-the-serialization-plugin)**.\n2) Add the **[serialization library dependency](#2-dependency-on-the-json-library)**.\n\n#### 1) Setting up the serialization plugin\n\nYou can set up the serialization plugin with the Kotlin plugin using the\n[Gradle plugins DSL](https://docs.gradle.org/current/userguide/plugins.html#sec:plugins_block):\n\nKotlin DSL:\n\n```kotlin\nplugins {\n    kotlin(\"jvm\") version \"2.1.0\" // or kotlin(\"multiplatform\") or any other kotlin plugin\n    kotlin(\"plugin.serialization\") version \"2.1.0\"\n}\n```       \n\nGroovy DSL:\n\n```gradle\nplugins {\n    id 'org.jetbrains.kotlin.multiplatform' version '2.1.0'\n    id 'org.jetbrains.kotlin.plugin.serialization' version '2.1.0'\n}\n```\n\n\u003e Kotlin versions before 1.4.0 are not supported by the stable release of Kotlin serialization.\n\n\u003cdetails\u003e\n  \u003csummary\u003eUsing \u003ccode\u003eapply plugin\u003c/code\u003e (the old way)\u003c/summary\u003e\n\nFirst, you have to add the serialization plugin to your classpath as the other [compiler plugins](https://kotlinlang.org/docs/reference/compiler-plugins.html):\n\nKotlin DSL:\n\n```kotlin\nbuildscript {\n    repositories { mavenCentral() }\n\n    dependencies {\n        val kotlinVersion = \"2.1.0\"\n        classpath(kotlin(\"gradle-plugin\", version = kotlinVersion))\n        classpath(kotlin(\"serialization\", version = kotlinVersion))\n    }\n}\n```\n\nGroovy DSL:\n\n```gradle\nbuildscript {\n    ext.kotlin_version = '2.1.0'\n    repositories { mavenCentral() }\n\n    dependencies {\n        classpath \"org.jetbrains.kotlin:kotlin-serialization:$kotlin_version\"\n    }\n}\n```\n\nThen you can `apply plugin` (example in Groovy):\n\n```gradle\napply plugin: 'kotlin' // or 'kotlin-multiplatform' for multiplatform projects\napply plugin: 'kotlinx-serialization'\n```\n\u003c/details\u003e\n\n#### 2) Dependency on the JSON library\n\nAfter setting up the plugin, you have to add a dependency on the serialization library.\nNote that while the plugin has version the same as the compiler one, runtime library has different coordinates, repository and versioning.\n\nKotlin DSL:\n\n```kotlin\nrepositories {\n    mavenCentral()\n}\n\ndependencies {\n    implementation(\"org.jetbrains.kotlinx:kotlinx-serialization-json:1.8.0\")\n}\n```\n\nGroovy DSL:\n\n```gradle\nrepositories {\n    mavenCentral()\n}\n\ndependencies {\n    implementation \"org.jetbrains.kotlinx:kotlinx-serialization-json:1.8.0\"\n}\n```\n\n\u003eWe also provide `kotlinx-serialization-core` artifact that contains all serialization API but does not have a bundled serialization format with it\n\n### Android\n\nBy default, proguard rules are supplied with the library.\n[These rules](rules/common.pro) keep serializers for _all_ serializable classes that are retained after shrinking,\nso you don't need additional setup.\n\n**However, these rules do not affect serializable classes if they have named companion objects.**\n\nIf you want to serialize classes with named companion objects, you need to add and edit rules below to your `proguard-rules.pro` configuration. \n\nNote that the rules for R8 differ depending on the [compatibility mode](https://r8.googlesource.com/r8/+/refs/heads/master/compatibility-faq.md) used.\n\n\u003cdetails\u003e\n\u003csummary\u003eExample of named companion rules for ProGuard and R8 compatibility mode\u003c/summary\u003e\n\n```proguard\n# Serializer for classes with named companion objects are retrieved using `getDeclaredClasses`.\n# If you have any, replace classes with those containing named companion objects.\n-keepattributes InnerClasses # Needed for `getDeclaredClasses`.\n\n-if @kotlinx.serialization.Serializable class\ncom.example.myapplication.HasNamedCompanion, # \u003c-- List serializable classes with named companions.\ncom.example.myapplication.HasNamedCompanion2\n{\n    static **$* *;\n}\n-keepnames class \u003c1\u003e$$serializer { # -keepnames suffices; class is kept when serializer() is kept.\n    static \u003c1\u003e$$serializer INSTANCE;\n}\n```\n\u003c/details\u003e\n\n\n\u003cdetails\u003e\n\u003csummary\u003eExample of named companion rules for R8 full mode\u003c/summary\u003e\n\n```proguard\n# Serializer for classes with named companion objects are retrieved using `getDeclaredClasses`.\n# If you have any, replace classes with those containing named companion objects.\n-keepattributes InnerClasses # Needed for `getDeclaredClasses`.\n\n-if @kotlinx.serialization.Serializable class\ncom.example.myapplication.HasNamedCompanion, # \u003c-- List serializable classes with named companions.\ncom.example.myapplication.HasNamedCompanion2\n{\n    static **$* *;\n}\n-keepnames class \u003c1\u003e$$serializer { # -keepnames suffices; class is kept when serializer() is kept.\n    static \u003c1\u003e$$serializer INSTANCE;\n}\n\n# Keep both serializer and serializable classes to save the attribute InnerClasses\n-keepclasseswithmembers, allowshrinking, allowobfuscation, allowaccessmodification class\ncom.example.myapplication.HasNamedCompanion, # \u003c-- List serializable classes with named companions.\ncom.example.myapplication.HasNamedCompanion2\n{\n    *;\n}\n```\n\u003c/details\u003e\n\nIn case you want to exclude serializable classes that are used, but never serialized at runtime,\nyou will need to write custom rules with narrower [class specifications](https://www.guardsquare.com/manual/configuration/usage).\n\n### Multiplatform (Common, JS, Native)\n\nMost of the modules are also available for Kotlin/JS and Kotlin/Native.\nYou can add dependency to the required module right to the common source set:\n```gradle\ncommonMain {\n    dependencies {\n        // Works as common dependency as well as the platform one\n        implementation \"org.jetbrains.kotlinx:kotlinx-serialization-json:$serialization_version\"\n    }\n}\n```\nThe same artifact coordinates can be used to depend on platform-specific artifact in platform-specific source-set.\n\n### Maven\n\nEnsure the proper version of Kotlin and serialization version:\n\n```xml\n\u003cproperties\u003e\n    \u003ckotlin.version\u003e2.1.0\u003c/kotlin.version\u003e\n    \u003cserialization.version\u003e1.8.0\u003c/serialization.version\u003e\n\u003c/properties\u003e\n```\n\nAdd serialization plugin to Kotlin compiler plugin:\n\n```xml\n\u003cbuild\u003e\n    \u003cplugins\u003e\n        \u003cplugin\u003e\n            \u003cgroupId\u003eorg.jetbrains.kotlin\u003c/groupId\u003e\n            \u003cartifactId\u003ekotlin-maven-plugin\u003c/artifactId\u003e\n            \u003cversion\u003e${kotlin.version}\u003c/version\u003e\n            \u003cexecutions\u003e\n                \u003cexecution\u003e\n                    \u003cid\u003ecompile\u003c/id\u003e\n                    \u003cphase\u003ecompile\u003c/phase\u003e\n                    \u003cgoals\u003e\n                        \u003cgoal\u003ecompile\u003c/goal\u003e\n                    \u003c/goals\u003e\n                \u003c/execution\u003e\n            \u003c/executions\u003e\n            \u003cconfiguration\u003e\n                \u003ccompilerPlugins\u003e\n                    \u003cplugin\u003ekotlinx-serialization\u003c/plugin\u003e\n                \u003c/compilerPlugins\u003e\n            \u003c/configuration\u003e\n            \u003cdependencies\u003e\n                \u003cdependency\u003e\n                    \u003cgroupId\u003eorg.jetbrains.kotlin\u003c/groupId\u003e\n                    \u003cartifactId\u003ekotlin-maven-serialization\u003c/artifactId\u003e\n                    \u003cversion\u003e${kotlin.version}\u003c/version\u003e\n                \u003c/dependency\u003e\n            \u003c/dependencies\u003e\n        \u003c/plugin\u003e\n    \u003c/plugins\u003e\n\u003c/build\u003e\n```\n\nAdd dependency on serialization runtime library:\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003eorg.jetbrains.kotlinx\u003c/groupId\u003e\n    \u003cartifactId\u003ekotlinx-serialization-json\u003c/artifactId\u003e\n    \u003cversion\u003e${serialization.version}\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n### Bazel\n\nTo setup the Kotlin compiler plugin for Bazel, follow [the\nexample](https://github.com/bazelbuild/rules_kotlin/tree/master/examples/plugin/src/serialization)\nfrom the `rules_kotlin` repository.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FKotlin%2Fkotlinx.serialization","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FKotlin%2Fkotlinx.serialization","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FKotlin%2Fkotlinx.serialization/lists"}