{"id":13428635,"url":"https://github.com/FasterXML/jackson-module-kotlin","last_synced_at":"2025-03-16T01:32:45.004Z","repository":{"id":20133923,"uuid":"23404083","full_name":"FasterXML/jackson-module-kotlin","owner":"FasterXML","description":"Module that adds support for serialization/deserialization of Kotlin (http://kotlinlang.org) classes and data classes.","archived":false,"fork":false,"pushed_at":"2025-03-09T04:48:09.000Z","size":2402,"stargazers_count":1140,"open_issues_count":75,"forks_count":177,"subscribers_count":21,"default_branch":"2.19","last_synced_at":"2025-03-10T05:07:30.483Z","etag":null,"topics":["deserialization","hacktoberfest","jackson","json","kotlin","kotlin-library","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/FasterXML.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["k163377","cowtowncoder"],"tidelift":"maven/com.fasterxml.jackson.module:jackson-module-kotlin"}},"created_at":"2014-08-27T20:20:03.000Z","updated_at":"2025-03-09T15:07:40.000Z","dependencies_parsed_at":"2023-02-10T20:16:05.863Z","dependency_job_id":"1f74a98b-ed33-4db5-8d9e-605203488be0","html_url":"https://github.com/FasterXML/jackson-module-kotlin","commit_stats":{"total_commits":1468,"total_committers":63,"mean_commits":23.3015873015873,"dds":0.5783378746594006,"last_synced_commit":"a15c278c37d28235a1cb26fc7ac6499ee78bcae1"},"previous_names":[],"tags_count":146,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FasterXML%2Fjackson-module-kotlin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FasterXML%2Fjackson-module-kotlin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FasterXML%2Fjackson-module-kotlin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FasterXML%2Fjackson-module-kotlin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/FasterXML","download_url":"https://codeload.github.com/FasterXML/jackson-module-kotlin/tar.gz/refs/heads/2.19","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243814905,"owners_count":20352037,"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":["deserialization","hacktoberfest","jackson","json","kotlin","kotlin-library","serialization"],"created_at":"2024-07-31T01:01:02.018Z","updated_at":"2025-03-16T01:32:44.997Z","avatar_url":"https://github.com/FasterXML.png","language":"Kotlin","readme":"[![Maven Central](https://maven-badges.herokuapp.com/maven-central/com.fasterxml.jackson.module/jackson-module-kotlin/badge.svg)](https://mvnrepository.com/artifact/com.fasterxml.jackson.module/jackson-module-kotlin)\n[![Change log](https://img.shields.io/badge/change%20log-%E2%96%A4-yellow.svg)](./release-notes/VERSION-2.x)\n[![Tidelift](https://tidelift.com/badges/package/maven/com.fasterxml.jackson.module:jackson-module-kotlin)](https://tidelift.com/subscription/pkg/maven-com-fasterxml-jackson-module-jackson-module-kotlin?utm_source=maven-com-fasterxml-jackson-module-jackson-module-kotlin\u0026utm_medium=referral\u0026utm_campaign=readme)\n[![Kotlin Slack](https://img.shields.io/badge/chat-kotlin%20slack-orange.svg)](https://slack.kotlinlang.org/)\n\n# Overview\n\nModule that adds support for serialization/deserialization of [Kotlin](https://kotlinlang.org)\nclasses and data classes.\nPreviously a default constructor must have existed on the Kotlin object for Jackson to deserialize into the object.\nWith this module, single constructor classes can be used automatically,\nand those with secondary constructors or static factories are also supported.\n\n# Status\n\n* release `2.18.2` (for Jackson `2.18.x`) [![GitHub Actions build](https://github.com/FasterXML/jackson-module-kotlin/actions/workflows/main.yml/badge.svg?branch=2.18)](https://github.com/FasterXML/jackson-module-kotlin/actions?query=branch%3A2.18)\n* release `2.17.3` (for Jackson `2.17.x`) [![GitHub Actions build](https://github.com/FasterXML/jackson-module-kotlin/actions/workflows/main.yml/badge.svg?branch=2.17)](https://github.com/FasterXML/jackson-module-kotlin/actions?query=branch%3A2.17)\n* release `2.16.2` (for Jackson `2.16.x`) [![GitHub Actions build](https://github.com/FasterXML/jackson-module-kotlin/actions/workflows/main.yml/badge.svg?branch=2.16)](https://github.com/FasterXML/jackson-module-kotlin/actions?query=branch%3A2.16)\n* release `2.15.4` (for Jackson `2.15.x`) [![GitHub Actions build](https://github.com/FasterXML/jackson-module-kotlin/actions/workflows/main.yml/badge.svg?branch=2.15)](https://github.com/FasterXML/jackson-module-kotlin/actions?query=branch%3A2.15)\n\nReleases require that you have included Kotlin stdlib and reflect libraries already.\n\nGradle:\n```\nimplementation \"com.fasterxml.jackson.module:jackson-module-kotlin:2.18.+\"\n```\n\nMaven:\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003ecom.fasterxml.jackson.module\u003c/groupId\u003e\n    \u003cartifactId\u003ejackson-module-kotlin\u003c/artifactId\u003e\n    \u003cversion\u003e2.18.2\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n# Usage\n\nFor any Kotlin class or data class constructor, the JSON property names will be inferred\nfrom the parameters using Kotlin runtime type information.\n\nTo use, just register the Kotlin module with your ObjectMapper instance:\n\n```kotlin\n// With Jackson 2.12 and later\nimport com.fasterxml.jackson.module.kotlin.jacksonObjectMapper\n...\nval mapper = jacksonObjectMapper()\n// or\nimport com.fasterxml.jackson.module.kotlin.registerKotlinModule\n...\nval mapper = ObjectMapper().registerKotlinModule()\n// or\nimport com.fasterxml.jackson.module.kotlin.jsonMapper\nimport com.fasterxml.jackson.module.kotlin.kotlinModule\n...\nval mapper = jsonMapper {\n  addModule(kotlinModule())\n}\n```\n\nIn 2.17 and later, the `jacksonObjectMapper {}` and `registerKotlinModule {}` lambdas allow configuration for `KotlinModule`.  \nSee [#Configuration](#Configuration) for details on the available configuration items.\n\nA simple data class example:\n```kotlin\nimport com.fasterxml.jackson.module.kotlin.jacksonObjectMapper\nimport com.fasterxml.jackson.module.kotlin.readValue\n\ndata class MyStateObject(val name: String, val age: Int)\n\n...\nval mapper = jacksonObjectMapper()\n\nval state = mapper.readValue\u003cMyStateObject\u003e(json)\n// or\nval state: MyStateObject = mapper.readValue(json)\n// or\nmyMemberWithType = mapper.readValue(json)\n```\n\nAll inferred types for the extension functions carry in full generic information (reified generics).\nTherefore, using `readValue()` extension without the `Class` parameter will reify the type and automatically create a `TypeReference` for Jackson.\n\nAlso, there are some convenient operator overloading extension functions for JsonNode inheritors.\n```kotlin\nimport com.fasterxml.jackson.databind.node.ArrayNode\nimport com.fasterxml.jackson.databind.node.ObjectNode\nimport com.fasterxml.jackson.databind.node.JsonNodeFactory\nimport com.fasterxml.jackson.module.kotlin.*\n\n// ...\nval objectNode: ObjectNode = JsonNodeFactory.instance.objectNode()\nobjectNode.put(\"foo1\", \"bar\").put(\"foo2\", \"baz\").put(\"foo3\", \"bax\")\nobjectNode -= \"foo1\"\nobjectNode -= listOf(\"foo2\")\nprintln(objectNode.toString()) // {\"foo3\":\"bax\"}\n\n// ...\nval arrayNode: ArrayNode = JsonNodeFactory.instance.arrayNode()\narrayNode += \"foo\"\narrayNode += true\narrayNode += 1\narrayNode += 1.0\narrayNode += \"bar\".toByteArray()\nprintln(arrayNode.toString()) // [\"foo\",true,1,1.0,\"YmFy\"]\n```\n\n# Compatibility\n## Kotlin\n(NOTE: incomplete! Please submit corrections/additions via PRs!)\n\nDifferent `kotlin-core` versions are supported by different Jackson Kotlin module minor versions.\nHere is an incomplete list of supported versions:\n\n* Jackson 2.19.x: Kotlin-core 1.9 - 2.1\n* Jackson 2.18.x: Kotlin-core 1.8 - 2.1\n* Jackson 2.17.x: Kotlin-core 1.7 - 2.0\n* Jackson 2.16.x: Kotlin-core 1.6 - 1.9\n* Jackson 2.15.x: Kotlin-core 1.5 - 1.8\n* Jackson 2.14.x: Kotlin-core 1.4 - 1.8\n* Jackson 2.13.x: Kotlin-core 1.4 - 1.7\n\nPlease note that the versions supported by 2.17 are tentative and may change depending on the release date.\n\n## Android\nSupported Android SDK versions are determined by `jackson-databind`.\nPlease see [this link](https://github.com/FasterXML/jackson-databind#android) for details.\n\n# Annotations\n\nYou can intermix non-field values in the constructor and `JsonProperty` annotation in the constructor.\nAny fields not present in the constructor will be set after the constructor call.\nAn example of these concepts:\n\n```kotlin\n   @JsonInclude(JsonInclude.Include.NON_EMPTY)\n   class StateObjectWithPartialFieldsInConstructor(val name: String, @JsonProperty(\"age\") val years: Int)    {\n        @JsonProperty(\"address\") lateinit var primaryAddress: String   // set after construction\n        var createdDt: DateTime by Delegates.notNull()                // set after construction\n        var neverSetProperty: String? = null                          // not in JSON so must be nullable with default\n    }\n```\n\nNote that using `lateinit` or `Delegates.notNull()` will ensure that the value is never `null` when read, while letting it be instantiated after the construction of the class.\n\n# Caveats\n\n* The `@JsonCreator` annotation is optional unless you have more than one constructor that is valid, or you want to use a static factory method (which also must have `platformStatic` annotation, e.g. `@JvmStatic`).  In these cases, annotate only one method as `JsonCreator`.\n* During deserialization, if the definition on `Kotlin` is a non-null primitive and `null` is entered explicitly on `JSON`, processing will continue with an unintended default value. [This problem is fixed by enabling `DeserializationFeature.FAIL_ON_NULL_FOR_PRIMITIVES` on `ObjectMapper`](https://github.com/FasterXML/jackson-module-kotlin/issues/242#issuecomment-792570655).\n* Serializing a member or top-level Kotlin class that implements Iterator requires a workaround, see [Issue #4](https://github.com/FasterXML/jackson-module-kotlin/issues/4) for easy workarounds.\n* If using proguard:\n    * `kotlin.Metadata` annotations may be stripped, preventing deserialization. Add a proguard rule to keep the `kotlin.Metadata` class: `-keep class kotlin.Metadata { *; }`\n    * If you're getting `java.lang.ExceptionInInitializerError`, you may also need: `-keep class kotlin.reflect.** { *; }`\n    * If you're still running into problems, you might also need to add a proguard keep rule for the specific classes you want to (de-)serialize. For example, if all your models are inside the package `com.example.models`, you could add the rule `-keep class com.example.models.** { *; }`\n    * Also, please refer to [this page](https://github.com/FasterXML/jackson-docs/wiki/JacksonOnAndroid) for settings related to `jackson-databind`.\n \n# Support for Kotlin Built-in classes\n\nThese Kotlin classes are supported with the following fields for serialization/deserialization\n(and other fields are hidden that are not relevant):\n\n* Pair _(first, second)_\n* Triple _(first, second, third)_\n* IntRange _(start, end)_\n* CharRange _(start, end)_\n* LongRange _(start, end)_\n\nDeserialization for `value class` is also supported since 2.17.  \nPlease refer to [this page](./docs/value-class-support.md) for more information on using `value class`, including serialization.\n\n(others are likely to work, but may not be tuned for Jackson)\n\n# Sealed classes without @JsonSubTypes\nSubclasses can be detected automatically for sealed classes, since all possible subclasses are known\nat compile-time to Kotlin. This makes `com.fasterxml.jackson.annotation.JsonSubTypes` redundant.\nA `com.fasterxml.jackson.annotation.@JsonTypeInfo` annotation at the base-class is still necessary. \n\n```kotlin\n  @JsonTypeInfo(use = JsonTypeInfo.Id.NAME)\n  sealed class SuperClass{\n      class A: SuperClass()\n      class B: SuperClass()\n  }\n\n...\nval mapper = jacksonObjectMapper()\nval root: SuperClass = mapper.readValue(json)\nwhen(root){\n    is A -\u003e \"It's A\"\n    is B -\u003e \"It's B\"\n}\n```\n\n\n# Configuration\n\nThe Kotlin module may be given a few configuration parameters at construction time;\nsee the [inline documentation](https://github.com/FasterXML/jackson-module-kotlin/blob/master/src/main/kotlin/com/fasterxml/jackson/module/kotlin/KotlinModule.kt)\nfor details on what options are available and what they do.\n\n```kotlin\nval kotlinModule = KotlinModule.Builder()\n    .enable(KotlinFeature.StrictNullChecks)\n    .build()\nval mapper = JsonMapper.builder()\n    .addModule(kotlinModule)\n    .build()\n```\n\nIf your `ObjectMapper` is constructed in Java, there is a builder method\nprovided for configuring these options:\n\n```java\nKotlinModule kotlinModule = new KotlinModule.Builder()\n        .enable(KotlinFeature.StrictNullChecks)\n        .build();\nObjectMapper objectMapper = JsonMapper.builder()\n        .addModule(kotlinModule)\n        .build();\n```\n\n# Development\n\n## Maintainers\n\nFollowing developers have committer access to this project.\n\n* Author: Jayson Minard (@apatrida) wrote this module originally (no longer active)\n* Active Maintainers:\n    * Dmitry Spikhalskiy (@Spikhalskiy) -- since 2.14\n    * Drew Stephens (@dinomite)\n    * Vyacheslav Artemyev (@viartemev)\n    * WrongWrong (@k163377) -- since 2.15\n* Co-maintainers:\n    * Tatu Saloranta (@cowtowncoder)\n\nYou may at-reference maintainers as necessary but please keep in mind that all\nmaintenance work is strictly voluntary (no one gets paid to work on this\nor any other Jackson components) so there is no guarantee for timeliness of\nresponses.\n\nAll Pull Requests should be reviewed by at least one of active maintainers;\nbigger architectural/design questions should be agreed upon by majority of\nactive maintainers.\n\n## Releases \u0026 Branches\n\nThis module follows the release schedule of the rest of Jackson—the current version is consistent\nacross all Jackson components \u0026 modules. See the [jackson-databind README](https://github.com/FasterXML/jackson#actively-developed-versions) for details.\n\n## Contributing\n\nWe welcome any contributions—reports of issues, ideas for enhancements, and pull requests related to either of those.\n\nSee the [main Jackson contribution guidelines](https://github.com/FasterXML/jackson/blob/master/CONTRIBUTING.md) for more details.\n\n### Branches\n\nIf you are going to write code, choose the appropriate base branch:\n\n- `2.18` for bugfixes against the current stable version\n- `2.19` for additive functionality \u0026 features or [minor](https://semver.org), backwards compatible changes to existing behavior to be included in the next minor version release\n- `master` for significant changes to existing behavior, which will be part of Jackson 3.0\n\n### Failing tests\n\nThere are a number of tests for functionality that is broken, mostly in the [failing](https://github.com/FasterXML/jackson-module-kotlin/tree/master/src/test/kotlin/com/fasterxml/jackson/module/kotlin/test/github/failing)\npackage but a few as part of other test suites.  Instead of ignoring these tests (with JUnit's `@Ignore` annotation)\nor excluding them from being run as part of automated testing, the tests are written to demonstrate the failure\n(either making a call that throws an exception or with an assertion that fails) but not fail the build, except if the\nunderlying issue is fixed.  This allows us to know when the tested functionality has been incidentally fixed by\nunrelated code changes.\n\nSee the [tests readme](https://github.com/FasterXML/jackson-module-kotlin/tree/master/src/test/kotlin/com/fasterxml/jackson/module/kotlin/README.md) for more information.\n","funding_links":["https://github.com/sponsors/k163377","https://github.com/sponsors/cowtowncoder","https://tidelift.com/funding/github/maven/com.fasterxml.jackson.module:jackson-module-kotlin","https://tidelift.com/badges/package/maven/com.fasterxml.jackson.module:jackson-module-kotlin","https://tidelift.com/subscription/pkg/maven-com-fasterxml-jackson-module-jackson-module-kotlin?utm_source=maven-com-fasterxml-jackson-module-jackson-module-kotlin\u0026utm_medium=referral\u0026utm_campaign=readme"],"categories":["Libraries","Kotlin"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FFasterXML%2Fjackson-module-kotlin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FFasterXML%2Fjackson-module-kotlin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FFasterXML%2Fjackson-module-kotlin/lists"}