Skip to content

update: first update for serialization documentation restructuring #2978

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 1 commit into
base: master
Choose a base branch
from
+147 −0
Draft

update: first update for serialization documentation restructuring #2978

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions docs/cfg/buildprofiles.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
<?xml version="1.0" encoding="UTF-8"?>

<buildprofiles>
<variables>
<enable-browser-edits>true</enable-browser-edits>
<browser-edits-url>https://github.com/Kotlin/kotlinx.serialization/blob/master/docs/</browser-edits-url>
<allow-indexable-eaps>true</allow-indexable-eaps>
</variables>
<build-profile product="serialization"/>
</buildprofiles>
13 changes: 13 additions & 0 deletions docs/images/serialization.svg
View file
Open in desktop
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Calling the middle step Primitives is misleading (as this is not Kotlin/Java primitive types). Instead the middle steps are actually serialization library calls (with a given set, including primitive types, but also supporting structures and "special" types).

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hey @pdvrieze - thank you for your comments 💯 - we are still in the review process for these updates (just a draft PR at this point), but we will take a look at your feedback during the review

Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
24 changes: 24 additions & 0 deletions docs/serialization.tree
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
<?xml version='1.0' encoding='utf-8'?>
<!DOCTYPE instance-profile SYSTEM "https://resources.jetbrains.com/writerside/1.0/product-profile.dtd">
<instance-profile id="serialization" name="Serialization" start-page="serialization.md">
<snippet id="serialization">
<toc-element topic="serialization.md" toc-title="Introduction"/>
<toc-element toc-title="Get started">
<toc-element topic="serialization-get-started.md"/>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Am I right that these files do not exist for now (in this PR, at least?)

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

you are correct 👍 We discussed we will be using this PR as the basis to merge the other PRs into as we go, so it will eventually contain all of these.

<toc-element topic="serialization-serialize-builtin-types.md"/>
<toc-element topic="serialization-customization-options.md"/>
</toc-element>
<toc-element toc-title="Configure JSON serialization">
<toc-element topic="configure-json-serialization.md" toc-title="Overview"/>
<toc-element topic="serialization-json-configuration.md"/>
<toc-element topic="serialization-json-elements.md"/>
<toc-element topic="serialization-transform-json.md" toc-title="JSON transformation"/>
</toc-element>
<toc-element topic="serialization-polymorphism.md"/>
<toc-element toc-title="Custom serializers">
<toc-element topic="create-custom-serializers.md"/>
<toc-element topic="third-party-classes.md"/>
</toc-element>
<toc-element topic="alternative-serialization-formats.md" toc-title="Alternative serialization formats"/>
</snippet>
</instance-profile>
78 changes: 78 additions & 0 deletions docs/topics/serialization.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,78 @@
[//]: # (title: Serialization)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm finding it a bit complicated when both old and new markdown files are located in the same folder. Let's do the following:

  • Leave old .md in docs folder. The folder should be as-is because people are using it right now, and unrelated files will confuse them.
  • The new files should be in the new folder. Let's name it docs-website, for example (or any other name you see fit).
  • Changes should be self-contained, with no errors. (Except maybe references to the files that are parts of subsequent PRs, such as For more information, see [Serialize classes](serialization-customization-options.md).
  • Then we can iterate on each toc-element that can be one or a couple of .md files


Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I do not quite like this page. Correct me if I'm wrong — it is supposed to replace the current one on https://kotlinlang.org/docs/serialization.html , right?

In that case, it feels lacking in comparison to both the current page and GitHub's readme. I find it very valuable that both of these contain setup instructions on the go, so if you are already familiar with the library and need to remind yourself about dependency coordinates, you just need to copy it without clicking around. It also helps people who rush to code and want to experiment with everything themselves.

In other words, this page in PR lacks basic setup instructions and simple examples. I suggest taking them from the current https://kotlinlang.org/docs/serialization.html page. Other setup cases (e.g., Maven) can be put in a separate get-started.md or setup.md

So the structure on this page could look like this:

  1. Introduction (Serialization is the process of converting data used by an application to a format that can be transferred over a network or stored in a database or a file......)
  2. Kotlin serialization libraries (from this doc)
  3. Example: JSON serialization with Gradle setup (from current website)
  4. Supported formats
  5. What's next and references

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

it is supposed to replace the current one on https://kotlinlang.org/docs/serialization.html , right?

You are correct 👍

It would serve as an entry point and a quick overview. So it would change in scope. The current serialization page is that way right now because the entire documentation wasn't integrated into the website.

It would serve as something similar to these entry points: Kotlin for data analysis or coroutines.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Aaaand coroutines guide does not mention (at least on overview and get started) that you should have some library added to Gradle. I think that may be confusing for some users. I would suggest that serialization page, even as overview, should contain basic setup instructions

**Serialization** is the process of converting data used by an application to a format that can be transferred over a
network or stored in a database or a file. Deserialization is the opposite process of converting external data back into a runtime object.
Together, they are essential to most applications that exchange data with third parties.

Some data serialization formats, such as [JSON](https://www.json.org/json-en.html) and [Protocol Buffers](https://protobuf.dev/) are particularly common.
Being language-neutral and platform-neutral, these formats enable data exchange between systems written in any modern language.

To convert an object tree to a string or to a sequence of bytes, it must go through two mutually intertwined processes:

1. Serialization: Objects are transformed into a sequence of their primitive values.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe this particular explanation about primitives stream is too low-level for overview page. It confuses and distracts from the main purpose, so I suggest putting it aside until the paragraph about custom serializers.

To be honest, I think it is a bit outdated and does not fit anywhere except plugin's KEEP (https://github.com/Kotlin/KEEP/blob/main/proposals/KEEP-0149-serialization.md#core-api-overview-and-mental-model)

This universal process varies depending on the object and is managed by a serializer.
Comment on lines +12 to +13
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is misleading. Serialization translates objects to a sequence of encoder calls. There is no intermediate format, and such a format would not actually work (many formats allow for "special casing").

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Well, if we laid out every call to encodeInt/encodeString/encode... with its parameter, we will get a sequence of primitives (in memory, not on a wire)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The main challenge is that readers may assume there is such intermediate "file"/memory object. Maybe describe it as:

  • The serializer translates the object into a sequence of generic calls to the format(encoder) for the structure and individual elements of the object. It knows about individual objects, but not about formats
  • The encoder then uses this to write the data in a manner appropriate to the format. It takes the generic structure and element information, and does not know about objects.
  • There are special cases where serializers know about formats (by testing the type) that can support unusual cases. (For example JsonTransformingSerializer)
  • Similarly a format may know about certain serializers to handle them in a more appropriate way. E.g. unsigned types, ByteArrays, the default list serializers.

2. Encoding: The primitive sequence is converted into the desired output format, controlled by an encoder.

![Serialization flow](serialization.svg){width=700}

The reverse process involves parsing the input format, decoding the primitive values, and then deserializing the resulting
stream into objects.
Comment on lines +18 to +19
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The reverse process involves the decoder invoking the input format to guide it in parsing the input (there is no intermediate format and that cannot exist - note that formats may not allow parsing without the knowledge of specific data structures (generally non-self-describing binary formats)).

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe an interesting observation to add somewhere is that while encoding can generally simply skip elements either in the serializer or in the format, this is not true for decoders. Decoders must read the byte/text streams and consume them (even if it is just to explicitly ignore the parsing results).


If you're new to serialization in Kotlin, we recommend starting with the [Get Started with Serialization](serialization-get-started.md) guide.
This section provides a step-by-step guide to help you set up and use Kotlin serialization in your projects.
By following these steps, you can quickly get up to speed with the basics before diving into more complex topics.

## Kotlin serialization libraries

The `kotlinx.serialization` library offers support for all platforms, including JVM, JavaScript, Native.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It may be worthwhile to clarify more that the serialization library provides the format agnostic infrastructure. Then the -json and -cbor libraries are format implementations (they are fundamentally different and are independent even though first-party).

It works with various serialization formats, such as JSON, CBOR, and Protocol buffers. For the complete list of supported serialization,
see the [supported formats](#supported-serialization-formats) section.

All Kotlin serialization libraries are part of the `org.jetbrains.kotlinx:` group, with names
starting with `kotlinx-serialization-` and suffixes that reflect the serialization format.
For example:

* `org.jetbrains.kotlinx:kotlinx-serialization-json` provides JSON serialization for Kotlin projects.
* `org.jetbrains.kotlinx:kotlinx-serialization-cbor` provides CBOR serialization.

Platform-specific dependencies are automatically managed, so you don’t need to add them manually.
Use the same dependencies for JVM, JavaScript, Native, and multiplatform projects.

The `kotlinx.serialization` libraries follow their own versioning structure, independent of Kotlin.
You can check out the releases on [GitHub](https://github.com/Kotlin/kotlinx.serialization/releases) to find the latest versions.

## Supported serialization formats

`kotlinx.serialization` includes libraries for various serialization formats:

* [JSON](https://www.json.org/json-en.html): [`kotlinx-serialization-json`](https://github.com/Kotlin/kotlinx.serialization/blob/master/formats/README.md#json)
* [Protocol buffers](https://protobuf.dev/): [`kotlinx-serialization-protobuf`](https://github.com/Kotlin/kotlinx.serialization/blob/master/formats/README.md#protobuf)
* [CBOR](https://cbor.io/): [`kotlinx-serialization-cbor`](https://github.com/Kotlin/kotlinx.serialization/blob/master/formats/README.md#cbor)
* [Properties](https://en.wikipedia.org/wiki/.properties): [`kotlinx-serialization-properties`](https://github.com/Kotlin/kotlinx.serialization/blob/master/formats/README.md#properties)
* [HOCON](https://github.com/lightbend/config/blob/master/HOCON.md): [`kotlinx-serialization-hocon`](https://github.com/Kotlin/kotlinx.serialization/blob/master/formats/README.md#hocon) (only on JVM)

All libraries except JSON serialization (`kotlinx-serialization-json`) are [experimental](components-stability.md), which means their API can be changed without notice.
For more details about JSON serialization, see [JSON serialization overview](configure-json-serialization.md).

There are also community-maintained libraries that support more serialization formats, such as [YAML](https://yaml.org/) or [Apache Avro](https://avro.apache.org/).

You can find out more about experimental serialization formats in [Alternative and custom serialization formats](alternative-serialization-formats.md).

## Supported serialization types

Kotlin serialization supports a variety of built-in types, including all primitive types and composite types from the Kotlin standard library like the `List` type.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As far as I see, this and What's next section mainly serve as the index for further reading, just like Table of contents in the current guide.
I like how you expanded each reference with explanations instead of simply giving the link. However, it feels disconnected now, given that it consists of two paragraphs now. By-passers will likely not understand that they should read this topic to understand what sections of the documentation are there.
I.e. I would expect that What's next contains all follow-up links and will probably skip Supported serialization types section. I suggest removing this section and merging it with What's next:

## What's next
* Learn the basics of Kotlin serialization in the [Get started with serialization guide](serialization-get-started.md).
* Learn how built-in types, collections, and Serializable classes are processed by kotlinx.serialization (link to builtin types)
* Learn Json customization options [JSON serialization overview](configure-json-serialization.md).
* Learn how to write and customize your serializers (custom serializers link)
* ... etc
* ```

For more information, see [Serialize built-in types](serialization-serialize-builtin-types.md).

> Not all types from the Kotlin standard library are serializable. In particular, [ranges](ranges.md) and the [`Regex`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.text/-regex/) class are not serializable at the moment.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ranges.md does not exist (even in full version of the PR)

Copy link
Author

@daniCsorbaJB daniCsorbaJB Jul 21, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's how the linking is set up in our doc-base. If we integrate these serialization docs in kotlinlang.org it will point to this page with this link (https://kotlinlang.org/docs/ranges.html)

> Support for their serialization may be added in the future.
>
{style="note"}

Additionally, classes annotated with `@Serializable` are fully supported for serialization, enabling the conversion of class instances to and from formats like JSON.
For more information, see [Serialize classes](serialization-customization-options.md).

## What's next
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I know that this is common approach in all our docs, but I don't quite like the 'What's next' name of the section. It feels logical when you read page top-to-bottom, but if you're using it just as a reference/starter it feels out of place. I would rename it to something 'What this guide can also offer you' or 'Next sections of the guide' or just 'Table of contents in this guide'.

But maybe you know better, since this name was picked a long ago.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm 🤔
If users eventually read this on kotlinlang.org, I think the consistency could help them feel a sense of familiarity with the documentation. Since users use What's next everywhere else, this could help reinforce that further. That said, I'm not against renaming this section, although I would refrain from using words like "guide." For the user seeing this page on kotlinlang.org, they might not necessarily think of this as a guide, more like an entry point to everything related to serialization.

For example, we have a tutorial in multiplatform docs about Create a multiplatform app using Ktor and SQLDelight for some of our users, they would meet serialization here for the first time. Up until this point, they've seen that every time on the bottom of a page, there are next steps after reading said page.

but if you're using it just as a reference/starter it feels out of place.

That's a very good point! 👍 I think we could at least add some additional points here, even if they might be redundant for someone who is reading from top to bottom. We could even divide it further based on experience, using some intro statements before each list.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Btw, coroutines page does exactly this: https://kotlinlang.org/docs/coroutines-guide.html
Although this 'guide' page is kinda not the root one: we have https://kotlinlang.org/docs/coroutines-overview.html as a starter.


* Learn the basics of Kotlin serialization in the [Get started with serialization guide](serialization-get-started.md).
* To explore more complex JSON serialization scenarios, see [JSON serialization overview](configure-json-serialization.md).
* Dive into the [Serialize classes](serialization-customization-options.md) section to learn how to serialize classes and how to modify the default behavior of the `@Serializable` annotation.
7 changes: 7 additions & 0 deletions docs/v.list
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE vars SYSTEM "https://resources.jetbrains.com/stardust/vars.dtd">

<!-- Variables to be used throughout the documentation -->
<vars>

</vars>
15 changes: 15 additions & 0 deletions docs/writerside.cfg
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
<?xml version='1.0' encoding='utf-8'?>
<!DOCTYPE ihp SYSTEM "https://resources.jetbrains.com/writerside/1.0/ihp.dtd">

<ihp version="2.0">
<module name="serialization"/>
<topics dir="topics"/>
<images dir="images"/>
<vars src="v.list"/> <!-- be careful with renaming the file, might lead to build errors / bugs -->
<settings>
<!-- ToC within topics, usually displayed on the left, depth is measured by header levels -->
<default-property element-name="chapter" property-name="show-structure-depth" value="2"/>
<wrs-supernova use-version="242.21870"/>
</settings>
<instance src="serialization.tree"/>
</ihp>