Catch breaking JSON and CBOR changes before they ship. A CI gate for kotlinx-serialization @Serializable models, like buf breaking but for JSON and CBOR.

1. You change a model. Rename a field, drop a default, add a required property.
2. Old data is still out there. Older app versions, queues, caches and databases hold the previous shape.
3. The PR fails, with a fix. serialkompat diffs against your target branch and says what breaks and how to fix it.

 @Serializable
 data class Order(
     val id: String,
     val amountCents: Long,
-    val note: String? = null,
 )

$ ./gradlew serialkompatCheck
serialkompat: 1 active finding(s) (1 breaking, 0 warning), 0 acknowledged

  BREAK  PROPERTY_REMOVED  com.example.Order  (backward)
    field 'note' was removed from com.example.Order
    fix: Removing a field drops its data for tolerant readers; keep it (or bridge a rename with @JsonNames) until nothing uses it; else bump major.

BUILD FAILED

• No baseline file. The old schema is extracted live from your target branch on every run.
• Both directions. New code reading old data, and old code reading new data.
• Proven, not guessed. Every rule is round-trip tested against real kotlinx-serialization, under your Json { } / Cbor { } config.

Not a runtime validator, migration tool or JSON-schema linter.

The plugin is on the Gradle Plugin Portal, so no repository setup is needed. In the module that holds your @Serializable models:

// build.gradle.kts
plugins {
    kotlin("jvm")
    kotlin("plugin.serialization")
    id("com.chrisjenx.serialkompat") version "0.3.1"
}

serialkompat {
    types.set(listOf("com.example.Order"))  // root @Serializable types to guard
}

serialkompatCheck runs as part of ./gradlew check. The quick start walks through the first PR (the check has to be skipped on the PR that adds the plugin).

1. Your PR runs serialkompatCheck.
2. It extracts the old schema from your target branch (baselineRef) in a temporary git worktree.
3. It extracts the new schema from your compiled classes, by reading each serializer's own SerialDescriptor.
4. It diffs the two.
5. It classifies each change per direction (backward and forward) under your Json { } or Cbor { } config.
6. Every rule is proven by an oracle test against real kotlinx-serialization.

Details: Architecture.

./gradlew build          # compile, test, spotless, API check (BCV), docs gates, docs-sample tests
./gradlew spotlessApply  # auto-format
./gradlew apiDump        # update public-API baselines after an intended API change
./gradlew koverHtmlReport

Requires JDK 17+. Toolchain versions are pinned in gradle/wrapper/gradle-wrapper.properties and gradle/libs.versions.toml. Maintainers: see RELEASING.md.

Contributions welcome — this project is built test-first. See CONTRIBUTING.md and our Code of Conduct. Good starting points are issues labelled good first issue.

Apache License 2.0 © 2026 Chris Jenkins and serialkompat contributors.