0
# Ktor Client JSON Plugin
1

2
The Ktor Client JSON plugin provides automatic JSON serialization and deserialization for HTTP client requests and responses. It supports multiple serialization backends including Gson, Jackson, and Kotlinx Serialization, with configurable content type matching and type filtering.
3

4
**Note: This plugin is deprecated.** Use the [ContentNegotiation plugin](https://ktor.io/docs/migrating-2.html#serialization-client) for new projects.
5

6
## Package Information
7

8
- **Package Name**: io.ktor:ktor-client-json-jvm
9
- **Package Type**: Maven/Gradle
10
- **Language**: Kotlin
11
- **Installation**: `implementation("io.ktor:ktor-client-json:2.3.13")`
12

13
## Core Imports
14

15
```kotlin
16
import io.ktor.client.plugins.json.*
17
import io.ktor.client.plugins.gson.*
18
import io.ktor.client.plugins.jackson.*
19
import io.ktor.client.plugins.kotlinx.serializer.*
20
```
21

22
## Basic Usage
23

24
```kotlin
25
import io.ktor.client.*
26
import io.ktor.client.plugins.json.*
27
import io.ktor.client.plugins.gson.*
28
import io.ktor.client.request.*
29
import io.ktor.client.statement.*
30

31
// Install JSON plugin with default Gson serializer
32
val client = HttpClient {
33
    install(JsonPlugin) {
34
        serializer = GsonSerializer()
35
    }
36
}
37

38
// Using data classes for automatic serialization
39
@Serializable
40
data class User(val name: String, val email: String)
41

42
// POST request with automatic JSON serialization
43
val response: HttpResponse = client.post("https://api.example.com/users") {
44
    contentType(ContentType.Application.Json)
45
    setBody(User("Alice", "alice@example.com"))
46
}
47

48
// GET request with automatic JSON deserialization
49
val user: User = client.get("https://api.example.com/users/1").body()
50
```
51

52
## Architecture
53

54
The Ktor Client JSON plugin is built around several key components:
55

56
- **JsonPlugin**: Main plugin class that intercepts HTTP requests and responses
57
- **JsonSerializer Interface**: Abstract serializer interface for different JSON backends
58
- **Gson Integration**: GsonSerializer implementation using Google Gson
59
- **Jackson Integration**: JacksonSerializer implementation using Jackson ObjectMapper
60
- **Kotlinx Serialization**: KotlinxSerializer implementation using kotlinx.serialization
61
- **Content Type Matching**: Flexible content type detection including +json variants
62
- **Type Filtering**: Configurable type ignore lists to prevent unwanted serialization
63

64
## Capabilities
65

66
### JSON Plugin Installation
67

68
Core plugin configuration and installation for HTTP clients. Provides content type negotiation, serializer selection, and type filtering.
69

70
```kotlin { .api }
71
@Deprecated("Please use ContentNegotiation plugin")
72
class JsonPlugin internal constructor(
73
    val serializer: JsonSerializer,
74
    val acceptContentTypes: List<ContentType>,
75
    private val receiveContentTypeMatchers: List<ContentTypeMatcher>,
76
    private val ignoredTypes: Set<KClass<*>>
77
)
78

79
@KtorDsl
80
class Config {
81
    var serializer: JsonSerializer?
82
    var acceptContentTypes: List<ContentType>
83
    var receiveContentTypeMatchers: List<ContentTypeMatcher>
84
    
85
    fun accept(vararg contentTypes: ContentType)
86
    fun receive(matcher: ContentTypeMatcher)
87
    inline fun <reified T> ignoreType()
88
    fun ignoreType(type: KClass<*>)
89
    inline fun <reified T> removeIgnoredType()
90
    fun removeIgnoredType(type: KClass<*>)
91
    fun clearIgnoredTypes()
92
}
93

94
fun HttpClientConfig<*>.Json(block: JsonPlugin.Config.() -> Unit)
95
```
96

97
[JSON Plugin Configuration](./json-plugin.md)
98

99
### JSON Serialization Interface
100

101
Abstract serializer interface for implementing JSON backends. Defines the core serialization contract for request/response transformation.
102

103
```kotlin { .api }
104
@Deprecated("Please use ContentNegotiation plugin")
105
interface JsonSerializer {
106
    fun write(data: Any, contentType: ContentType): OutgoingContent
107
    fun write(data: Any): OutgoingContent
108
    fun read(type: TypeInfo, body: Input): Any
109
}
110

111
expect fun defaultSerializer(): JsonSerializer
112
```
113

114
[JSON Serializer Interface](./json-serializer.md)
115

116
### Gson Serialization
117

118
Google Gson-based JSON serialization implementation with configurable Gson builder support.
119

120
```kotlin { .api }
121
@Deprecated("Please use ContentNegotiation plugin")
122
class GsonSerializer(block: GsonBuilder.() -> Unit = {}) : JsonSerializer {
123
    override fun write(data: Any, contentType: ContentType): OutgoingContent
124
    override fun read(type: TypeInfo, body: Input): Any
125
}
126
```
127

128
[Gson Serialization](./gson-serializer.md)
129

130
### Jackson Serialization
131

132
Jackson-based JSON serialization implementation with configurable ObjectMapper support and advanced data binding features.
133

134
```kotlin { .api }
135
@Deprecated("Please use ContentNegotiation plugin")
136
class JacksonSerializer(
137
    jackson: ObjectMapper = jacksonObjectMapper(),
138
    block: ObjectMapper.() -> Unit = {}
139
) : JsonSerializer {
140
    override fun write(data: Any, contentType: ContentType): OutgoingContent
141
    override fun read(type: TypeInfo, body: Input): Any
142
}
143
```
144

145
[Jackson Serialization](./jackson-serializer.md)
146

147
### Kotlinx Serialization
148

149
Kotlinx Serialization-based JSON implementation with configurable Json instance and advanced serialization features.
150

151
```kotlin { .api }
152
@Deprecated("Please use ContentNegotiation plugin")
153
class KotlinxSerializer(private val json: Json = DefaultJson) : JsonSerializer {
154
    override fun write(data: Any, contentType: ContentType): OutgoingContent
155
    override fun read(type: TypeInfo, body: Input): Any
156
    
157
    companion object {
158
        val DefaultJson: Json
159
    }
160
}
161
```
162

163
[Kotlinx Serialization](./kotlinx-serializer.md)
164

165
## Types
166

167
```kotlin { .api }
168
// Content type matching
169
interface ContentTypeMatcher {
170
    fun contains(contentType: ContentType): Boolean
171
}
172

173
// Type information for deserialization
174
expect class TypeInfo {
175
    val type: KClass<*>
176
    val reifiedType: Type
177
    val kotlinType: KType?
178
}
179

180
// HTTP content types
181
object ContentType {
182
    object Application {
183
        val Json: ContentType
184
    }
185
}
186

187
// Outgoing HTTP content
188
abstract class OutgoingContent
189
class TextContent(
190
    val text: String,
191
    val contentType: ContentType
192
) : OutgoingContent
193

194
// Input stream for reading response bodies
195
interface Input {
196
    fun readText(): String
197
}
198
```