feat: adding JSON overview and Json configuration docs #3102

daniCsorbaJB · 2025-10-30T17:17:42Z

This is the fifth part of the Kotlin Serialization rewrite task.

Related Youtrack ticket: KT-81979

docs-website/topics/configure-json-serialization.md

sandwwraith · 2025-11-17T11:13:07Z

docs-website/topics/configure-json-serialization.md

+
+* Serialize Kotlin objects to JSON strings using the [`encodeToString()`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-json/kotlinx.serialization.json/-json/encode-to-string.html) function.
+* Deserialize JSON strings back to Kotlin objects with the [`decodeFromString()`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-json/kotlinx.serialization.json/-json/decode-from-string.html) function.
+* Work directly with the [`JsonElement`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-json/kotlinx.serialization.json/-json-element/) when handling complex JSON structures using the [`encodeToJsonElement()`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-json/kotlinx.serialization.json/encode-to-json-element.html) and the [`decodeFromJsonElement()`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-json/kotlinx.serialization.json/decode-from-json-element.html) functions.


I see we can nicely add encodeToStream/decodeFromStream to the list here. IMO it's OK to add a separate page for them + Okio integration

yes it definitely fits neatly here 👍

Use JVM streams with the encodeToStream() .decodeFromStream(), and .decodeToSequence() functions to work with JSON directly from input and output streams.

Great. Oh, and Okio's encodeToSink/decodeFromSource can also go there

docs-website/topics/configure-json-serialization.md

docs-website/topics/serialization-json-configuration.md

sandwwraith

I didn't look through io-sources.md since it is not finished

docs-website/topics/serialization-json-configuration.md

sandwwraith · 2025-12-03T17:57:01Z

docs-website/topics/serialization-json-configuration.md

+
+The following sections cover the various `Json` class configuration features.
+
+### Pretty printing


I do not think that placing this setting first is a great idea; its use cases are quite niche. I think we can still put it into 'Customize Json structure' even though it is not directly related.

hmm 🤔 if it doesn't fit that one, perhaps we could place it afterward? (so before customize JSON serialization) or perhaps even at the very bottom? (before what's next)🤔

Although it might be ok to just place it in there after all. It feels like a choice of inflating its importance or slightly miscategorizing it. 🤔 Both feel undesired — perhaps placing it at the bottom would be my preference of these options. What do you think?

I'm fine with placing it last in the 'Customize Json structure' section. IMO it is lost completely at the end of the whole page

sandwwraith · 2025-12-03T17:58:59Z

docs-website/topics/serialization-json-configuration.md

+
+In this example, `Inner` throws a `SerializationException` for unknown keys because it isn't annotated with `@JsonIgnoreUnknownKeys`.
+
+### Coerce input values


This setting is quite useful, can we place it first in the section?

sure thing 👍 — my only concern is it might be a bit more complex than the ones before — so perhaps it might be better as the second? What do you think? 🤔 (perh after isLenient)

Lenient parsing is also quite rare option. We can do the following order then:

- Ignore unknown keys - Coerce input values - Trailing commas - Comments - Lenient parsing

nice — this order sounds good to me 👌
I changed it in the next commit

docs-website/topics/configure-json-serialization.md

sandwwraith · 2025-12-05T13:48:01Z

docs-website/topics/serialization-json-configuration.md

+### Allow special floating-point values
+
+By default, special floating-point values like [`Double.NaN`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-double/-na-n.html)
+and infinities aren't supported in JSON because the JSON specification prohibits them.


We can give here link to https://datatracker.ietf.org/doc/html/rfc8259#section-6, although it is not strictly necessary

Do you want to add it or not?

🤔 I think we can — I don't think it would take the attention away, and if someone is interested, they can follow it. — I added it 👍

docs-website/topics/serialization-json-configuration.md

docs-website/topics/serialization-json-io-sources.md

sandwwraith · 2025-12-05T15:33:04Z

docs-website/topics/serialization-json-io-sources.md

+```
+
+> You can iterate through sequences returned by `.decodeToSequence()` only once
+> because they are tied to the underlying stream.


I would add here "Closing the stream before returned sequence is evaluated completely may result in IOException."

should we be "absolute" here?
Not sure if I understand correctly — so please correct me if I'm wrong:
Closing the stream early may result in IOException.

The may is based if the sequence was fully evaluated or not? 🤔

So could we write:
Closing the stream before the sequence is fully evaluated causes an IOException.

The "may" is based on whether you try to use it after closing or not. If you take the first element from the sequence, then close the stream, Iterator.next() function will throw IOExc. However, if you do not attempt to access the next element, it will be discarded, even if the sequence is not fully evaluated and there are still unparsed elements. Besides, there's buffering and such, so it is non-trivial to say whether there would be an exception at all if all the data got into the buffer.

So it is "Closing the stream before the returned sequence is evaluated completely may result in IOException" or even more, "If the sequence is not evaluated completely, but the underlying stream is closed, accessing it may result in an exception."

NB: I checked kotlinx-io docs and they throw IllegalStateException if the stream is accessed after closing, so it is not limited only to IOException here.

I see — thank you! 🤔 it might be a bit heavy for a note to add an encompassing explanation when this happens. So what do you think about this version (slight modification on your second suggestion, shifting the focs to the part about accessing the sequence causing the exception, and just saying exception instead of IOException):

Accessing a sequence may result in an exception if its underlying stream is closed before the sequence is completely evaluated.

Accessing a sequence may result in an exception if its underlying stream is closed before the sequence is completely evaluated.

Sounds great, let's take this version 👍🏻

docs-website/topics/serialization-json-io-sources.md

sandwwraith · 2025-12-05T15:37:09Z

docs-website/topics/serialization-json-io-sources.md

+```
+
+> You can iterate through sequences returned by `.decodeSourceToSequence()` only once
+> because they are tied to the underlying `Source`.


Please add "Closing the stream before returned sequence is evaluated completely may result in IOException." here as well

sandwwraith · 2025-12-05T15:37:20Z

docs-website/topics/serialization-json-io-sources.md

+> You can iterate through sequences returned by `.decodeSourceToSequence()` only once
+> because they are tied to the underlying `Source`.
+> 
+{style="note"}


Should we have What's next section?

yes — good point! 💯 I think we should reuse the one from Customize the Json instance

What's next

Explore advanced JSON element handling to manipulate and work with JSON data before it's parsed or serialized.

Discover how to transform JSON during serialization and deserialization for more control over your data.

I think adding * Learn how to [customize Json instances](serialization-json-configuration.md) to address different use cases for serialization and deserialization. is also worth it.

sandwwraith

See unresolved conversations

sandwwraith · 2025-12-09T16:40:43Z

docs-website/topics/serialization-json-io-sources.md

+> 
 {style="note"}
+
+## Okio


Should we've added this part here? It wasn't in the inital doc.

nope, unintentional thank you — removed it 👍

sandwwraith · 2025-12-09T16:48:55Z

docs-website/topics/serialization-json-io-sources.md

+```
+
+> You can iterate through sequences returned by `.decodeToSequence()` only once
+> because they are tied to the underlying stream.


The "may" is based on whether you try to use it after closing or not. If you take the first element from the sequence, then close the stream, Iterator.next() function will throw IOExc. However, if you do not attempt to access the next element, it will be discarded, even if the sequence is not fully evaluated and there are still unparsed elements. Besides, there's buffering and such, so it is non-trivial to say whether there would be an exception at all if all the data got into the buffer.

So it is "Closing the stream before the returned sequence is evaluated completely may result in IOException" or even more, "If the sequence is not evaluated completely, but the underlying stream is closed, accessing it may result in an exception."

NB: I checked kotlinx-io docs and they throw IllegalStateException if the stream is accessed after closing, so it is not limited only to IOException here.

… config

feat: adding JSON overview and Json configuration docs

49c7a15

daniCsorbaJB requested a review from sandwwraith October 31, 2025 14:44

sandwwraith requested changes Nov 17, 2025

View reviewed changes

daniCsorbaJB added 2 commits November 20, 2025 16:30

update: implementing first round of review comments

92e0a2a

feat: adding page for io serialization and implementing review comments

8082cc1

sandwwraith requested changes Dec 3, 2025

View reviewed changes

daniCsorbaJB added 3 commits December 4, 2025 16:03

update: created new page for I/O serialization

502b424

update: implementing additional review comments

34b33df

update: small update to section ordering

0ef93d7

sandwwraith requested changes Dec 5, 2025

View reviewed changes

update: implementing comments related to the IO sources page

83119de

sandwwraith requested changes Dec 9, 2025

View reviewed changes

update: small additional updates for streams and minor update to json…

cc6771e

… config


		The following sections cover the various `Json` class configuration features.

		### Pretty printing


		In this example, `Inner` throws a `SerializationException` for unknown keys because it isn't annotated with `@JsonIgnoreUnknownKeys`.

		### Coerce input values

feat: adding JSON overview and Json configuration docs #3102

Are you sure you want to change the base?

feat: adding JSON overview and Json configuration docs #3102

Conversation

daniCsorbaJB commented Oct 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sandwwraith left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

daniCsorbaJB Dec 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

What's next

Uh oh!

Choose a reason for hiding this comment

daniCsorbaJB commented Oct 30, 2025 •

edited

Loading

daniCsorbaJB Dec 10, 2025 •

edited

Loading