ktoml is a TOML parser for Kotlin Multiplatform with no Java in the dependency tree

A TOML library written in common Kotlin, with no Java code

ktoml is described as a fully native and multiplatform Kotlin serialization library for serialization and deserialization of the TOML format. It uses the native kotlinx.serialization, provided by Kotlin, and the README states plainly that this library contains no Java code and no Java dependencies.

That is the whole reason it exists as a separate project. The README explains the motivation directly: TOML is actually the most readable and user-friendly configuration file format, so the authors decided to support it for the kotlinx serialization library. And it links the kotlinx.serialization issue where the community asked for exactly this.

The framing is worth noting, because it means ktoml is not competing with TOML parsers in general. It is filling a gap in the Kotlin ecosystem, and the project says as much when it asks for help testing and contributing, and when it links the community request that prompted it.

The licence is MIT, the primary language is Kotlin, and the documentation site is at orchestr7.github.io/ktoml/.

The repository is not archived and the last push was on 2026-10-20, so the work is current even though the newest release tag is v0.7.1 from 2025-08-22.

Three artifacts, because reading a file and reading bytes are different problems

The library is published as three Maven artifacts, and the split is about where the input comes from rather than about features.

ktoml-core is the parser and the serializer, and it is the only one you need for the common case. The README says that for basic scenarios of decoding strings you can simply use ktoml-core.

ktoml-file adds deserialization from a file, and it pulls in okio to do the reading, which is added as a dependency to your project if you import ktoml-file. And ktoml-source is the streaming variant, for the case where you need an okio Source, for example for streaming reads.

So the dependency you take depends on how the bytes arrive. A string in memory needs only the core artifact. A file on disk needs the file artifact and accepts the okio dependency. A stream needs the source artifact.

That is a sensible factoring, and it is also the thing to check against your own build, because the whole point of the no Java dependencies claim is that your common code stays clean, while the platform specific parts pull in what they need.

The three artifacts are also what a version bump has to move together, since they are released as a set at the same version.

Adding it to Maven or Gradle, and the plugin you cannot forget

The library is hosted on Maven Central, and the README gives the dependency coordinates in three build formats. The Maven form lists the core and the file artifact with a version.

<dependency>
  <groupId>com.akuleshov7</groupId>
  <artifactId>ktoml-core</artifactId>
  <version>0.7.1</version>
</dependency>
<dependency>
  <groupId>com.akuleshov7</groupId>
  <artifactId>ktoml-file</artifactId>
  <version>0.7.1</version>
</dependency>

The Gradle Groovy form is the same two coordinates in a shorter syntax.

implementation 'com.akuleshov7:ktoml-core:0.7.1'
implementation 'com.akuleshov7:ktoml-file:0.7.1'

And the Gradle Kotlin DSL form uses the double quoted function call syntax.

implementation("com.akuleshov7:ktoml-core:0.7.1")
implementation("com.akuleshov7:ktoml-file:0.7.1")

There is one instruction that is easy to skip and impossible to debug later. The README says to add the serialization plugin, `kotlin("plugin.serialization")`, to your project, otherwise the `@Serialization` annotation will not work properly. Since the whole library is built on kotlinx.serialization, forgetting the plugin means the annotations on your data classes do nothing and the behaviour is baffling rather than obviously broken.

One naming detail is worth noticing. The repository is under the orchestr7 organisation, but the Maven coordinates use the com.akuleshov7 group id, and the badges in the README point at akuleshov7 GitHub URLs as well. The group id and the repository owner are not the same string, so copy the coordinates from the dependency snippets rather than deriving them from the URL.

The supported platform list, and why js and wasm are core-only

All the code is written in the Kotlin common module, which the README says means it can be built for each and every Kotlin native platform. But to reduce scope, ktoml supports a specific list.

The JVM is there, along with mingwx64, linuxx64, macosx64, macosArm64 for M1, ios, and iosSimulatorArm64. Then the three web targets, js, wasmJs and wasmWasi, and each of those three is marked as obviously only for ktoml-core.

That qualifier is the interesting part. The file and source artifacts depend on okio, and okio has its own platform story, so the web targets get the parser and the serializer but not the file reading layer. It is a reasonable trade, since a browser application would not be reading local files anyway, but it means a KMP project targeting wasm cannot use the same artifact set as a JVM project, and that difference will show up in your build configuration rather than in the code.

The README also notes that js(LEGACY) is not supported, with a link to the kotlinx.serialization issue explaining why.

The last line of the platform section is the most permissive thing in the README: other platforms could be added later on demand, by creating a corresponding issue, or easily built by users on their machines. Since the code is in the common module, that is a credible claim, and it is the reason the platform list is a scope decision rather than a technical limit.

What the parser covers, and the one thing it does not

The supported features list in the README is long and specific, and it is organised as parsing and decoding on one side, then serialization with tree related limitations.

On the parsing side, the list covers table sections, single and dotted. Key-value pairs, single and dotted. Long, Integer, Byte and Short types, and the unsigned integer types. Double and Float types. Basic strings and literal strings, and the Char type. Booleans. Simple arrays, and comments. Inline tables, and nested inline tables. Multiline strings. Arrays including multiline and nested ones. Maps for anonymous key-value pairs. Arrays of tables and inline arrays of tables. And the date and time types, mapped to the kotlinx-datetime types, so offset date-time to Instant, local date-time to LocalDateTime, local date to LocalDate and local time to LocalTime.

There is exactly one item marked as not supported, and it is at the end of the list: arrays of different types.

That is the one real gap, and it is a gap in the format rather than in the implementation. TOML 1.0 specifies that arrays must be homogeneous, so an array holding a string and a number is not a valid TOML document, and there is nothing for a conforming parser to decode.

The date and time mapping is worth a second look, because it is the kind of detail that causes silent mismatches. The values are not strings, they are kotlinx-datetime types, so a field declared as an offset date-time arrives as an Instant. That is a more useful API than a string, and it also means the kotlinx-datetime library becomes a transitive dependency of anything using those types.

Where ktoml is the wrong choice

Two clear cases, and one judgement call.

The first is a JVM only project. If your application only ever runs on the JVM, the multiplatform constraint buys you nothing, and you are paying for the abstraction while inheriting a library at 0.x with an active development warning. The README does say the library is still being developed and tested and lists limitations, which is an honest statement but also a statement about the maturity of the thing you are adopting.

The second is if you need TOML features outside the listed set. Arrays of different types are out, and the README is careful to frame its goal as comprehensively supporting all primitive types offered by Kotlin, which is a wider goal than the TOML standard itself, and it notes that the standard does not define Java-like types such as Char or Short. So there is a deliberate gap between what Kotlin can express and what the format defines, and ktoml resolves it in Kotlin's favour by mapping the Kotlin types onto TOML primitives.

The judgement call is the version. The newest release tag is v0.7.1 from 2025-08-22, with v0.7.0 in May 2025 and v0.6.0 in March 2025, while the last push to the repository was on 2026-10-20. So the working tree is well ahead of the last published release. If you pin to a release you are pinning to something from the middle of 2025, and if you track main you are tracking a library whose version number does not move.

The counterweight is the test suite. The repository has a toml-test directory, which is the conformance suite for the format, and the project also has a CustomSerializers.md document and the usual quality tooling in the build. A library with a conformance suite in the tree is a better bet than one without.

Editorial conclusion

Adopt ktoml if you are writing Kotlin Multiplatform code and need TOML configuration that works the same on the JVM, on Native and in a browser, and you want to reuse kotlinx.serialization rather than hand writing a parser. Do not adopt it if you only need TOML on the JVM, where the wider ecosystem already has options, or if you need homogeneous arrays, which the README lists as unsupported. Before you start, add the kotlinx.serialization plugin to your build, since the annotations will not work without it, and read the toml-test directory in the repository, which is the conformance suite the project tests against.

Frequently asked questions

Official sources

1. License: MIT
2. orchestr7/ktoml on GitHub
3. Project website
4. README
5. Releases