Ktor Server ↔ Ktor Client: Content Negotiation Interoperability

Direct answer

As of current Ktor releases, there is no single unified json(...) call that abstracts over kotlinx.serialization and Gson. ContentNegotiation remains a per-engine plugin on server and client. A unified serializer API is discussed in the community but not implemented, so any claims about its design are speculative and marked for review.

Confirmed facts

• Ktor Server and Ktor Client both use the ContentNegotiation plugin to convert objects to/from wire formats. Interoperability is mediated by HTTP Content-Type and Accept headers.
• kotlinx.serialization is the first-party serializer. It requires @Serializable on data classes, is type-safe and multiplatform. Gson relies on reflection and does not require annotations.
• Behavior diverges on configuration: unknown JSON properties are ignored by Gson by default, while kotlinx.serialization fails unless ignoreUnknownKeys = true is set. Naming strategies, null handling and default values must be matched manually.

Likely explanation and trade-offs

A unified JSON serializer API would reduce boilerplate and make cross-team contracts easier to document. The likely cost is an abstraction layer that must normalize serializer-specific options. That risks loss of fine-grained control, added indirection, and harder debugging when one engine needs an option the other does not support. Backward compatibility would most plausibly be preserved by keeping existing install(ContentNegotiation) { json(...) } registrations per engine and adding a new additive helper, not replacing the current API.

Enforcing identical serializer configurations across server and client cannot be guaranteed by Ktor. Ktor runs in separate processes; it can only negotiate media type. Round-trip correctness depends on the application ensuring the same JSON schema, naming policy, null handling and unknown-key policy on both sides.

Steps needed for this case

1. Confirm which serializer is installed on server and client and that Accept: application/json from client matches Content-Type: application/json from server.
2. Align naming and null policies explicitly, e.g., both use camelCase or both use snake_case, and both agree on how nulls are emitted and accepted.
3. Test edge cases with null values and unknown properties using the actual payloads exchanged.

One missing diagnostic detail that changes the recommendation: which exact serializer and naming policy is currently configured on each side, server vs client. Without that, specific configuration parity cannot be prescribed.

Uncertainty note: The existence and design of a future unified API, and any official backward-compatibility plan, is not confirmed in released documentation and should be verified against current Ktor release notes before planning.