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

sandwwraith · 2025-12-03T18:03:46Z

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`](serialization-json-elements.md) 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.
+* Use extension functions, such as [`.encodeToStream()`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-json/kotlinx.serialization.json/encode-to-stream.html), [`.decodeFromStream()`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-json/kotlinx.serialization.json/decode-from-stream.html), or Okio's [`.encodeToSink`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-json-io/kotlinx.serialization.json.io/encode-to-sink.html) to [serialize and deserialize JSON directly from I/O sources without creating intermediate strings](serialization-json-io-sources.md).


Okio's [.encodeToSink] is not correct wording, as it is our function, not Okio's. Also, you should mention kotlinx-io

thank you, I also spotted this while updating rest of the page 👍 so now it should be corrected

Should we also mention that these integrations are experimental?

sure 👍 good idea — added it

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

sandwwraith · 2025-12-05T13:52:27Z

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

+
+By default, the JSON encoder omits default property values because they are automatically applied to missing properties during decoding.
+This behavior is especially useful for nullable properties with null defaults, as it avoids writing unnecessary `null` values.
+For more details, see the [Manage serialization of default properties](serialization-customization-options.md#manage-the-serialization-of-default-properties-with-encodeddefault) section.


probably link is broken, because it is not encodeDdefault

sandwwraith · 2025-12-05T13:53:47Z

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

+
+### Lenient parsing
+
+By default, the `Json` parser enforces strict JSON rules to ensure compliance with the [RFC-4627](https://www.ietf.org/rfc/rfc4627.txt) specification, 


It is obsoleted by RFC-8259

sandwwraith · 2025-12-05T14:43:10Z

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

+
+In this example, the JSON contents of the input stream are deserialized into a single `Project` instance.
+
+If your input contains multiple JSON objects in a top-level JSON array, you can use [`.decodeToSequence()`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-json/kotlinx.serialization.json/decode-to-sequence.html) to process the elements lazily.


This is factually incorrect: we support not only top-level Json arrays, but also whitespace-separated objects. See https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-json/kotlinx.serialization.json/-decode-sequence-mode/ for details.

sandwwraith · 2025-12-05T14:43:39Z

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

+* [`.decodeFromSource()`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-json-io/kotlinx.serialization.json.io/decode-from-source.html) and [`.decodeFromBufferedSource()`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-json-okio/kotlinx.serialization.json.okio/decode-from-buffered-source.html) to read a single JSON value from a `Source` or `BufferedSource`.
+* [`.decodeSourceToSequence()`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-json-io/kotlinx.serialization.json.io/decode-source-to-sequence.html) and [`.decodeBufferedSourceToSequence()`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-json-okio/kotlinx.serialization.json.okio/decode-buffered-source-to-sequence.html) to lazily decode multiple JSON values as a `Sequence<T>`.
+
+> The JSON I/O extension functions use UTF-8 encoding and throw `SerializationException` for invalid JSON data and `IOException` for I/O failures.


This note is applicable to JVM streams as well. I believe we should move it to the top of the document.

sandwwraith · 2025-12-05T14:52:05Z

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

+</tab>
+</tabs>
+
+The next sections cover examples using `kotlinx-io` types with these APIs.  


We probably should mention that kotlinx-io itself is a library in an Alpha (https://kotlinlang.org/docs/components-stability.html#kotlin-libraries) status, while Okio is stable.

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."

sandwwraith · 2025-12-05T15:36:44Z

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

+}
+```
+
+If your input contains a large JSON array or multiple top-level JSON objects,


"a large JSON array or multiple top-level JSON objects" is a more correct version

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?

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


		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


		### Lenient parsing

		By default, the `Json` parser enforces strict JSON rules to ensure compliance with the [RFC-4627](https://www.ietf.org/rfc/rfc4627.txt) specification,


		In this example, the JSON contents of the input stream are deserialized into a single `Project` instance.

		If your input contains multiple JSON objects in a top-level JSON array, you can use [`.decodeToSequence()`](https://kotlinlang.org/api/kotlinx.serialization/kotlinx-serialization-json/kotlinx.serialization.json/decode-to-sequence.html) to process the elements lazily.

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!

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!

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

daniCsorbaJB commented Oct 30, 2025 •

edited

Loading