|
| 1 | +1.3.0-RC / 2021-09-06 |
| 2 | +================== |
| 3 | + |
| 4 | +This is a release candidate for the next version. It contains a lot of interesting features and improvements, |
| 5 | +so we ask you to evaluate it and share your feedback. |
| 6 | +Kotlin 1.5.30 is used by default. |
| 7 | + |
| 8 | +### Java IO stream-based JSON serialization |
| 9 | + |
| 10 | +Finally, in `kotlinx.serialization` 1.3.0 we’re presenting the first experimental version of the serialization API for IO streams: |
| 11 | +`Json.encodeToStream` and `Json.decodeFromStream` extension functions. |
| 12 | +With this API, you can decode objects directly from files, network connections, and other data sources without reading the data to strings beforehand. |
| 13 | +The opposite operation is also available: you can send encoded objects directly to files and other streams in a single API call. |
| 14 | +IO stream serialization is available only on the JVM platform and for the JSON format for now. |
| 15 | + |
| 16 | +Check out more in the [PR](https://github.com/Kotlin/kotlinx.serialization/pull/1569). |
| 17 | + |
| 18 | +### Property-level control over defaults values encoding |
| 19 | + |
| 20 | +Previous versions of the library allowed to specify whether to encode or drop default properties values with |
| 21 | +format configuration flags such as `Json { encodeDefaults = false }`. |
| 22 | +In 1.3.0 we’re extending this feature by adding a new way to fine-tune the serialization of default values: |
| 23 | +you can now control it on the property level using the new `@EncodeDefaults` annotation. |
| 24 | + |
| 25 | +`@EncodeDefaults` annotation has a higher priority over the `encodeDefaults` property and takes one of two possible values: |
| 26 | +- `ALWAYS` (default value) encodes a property value even if it equals to default. |
| 27 | +- `NEVER` doesn’t encode the default value regardless of the format configuration. |
| 28 | + |
| 29 | +Encoding of the annotated properties is not affected by `encodeDefault` format flag |
| 30 | +and works as described for all serialization formats, not only JSON. |
| 31 | + |
| 32 | +To learn more, check corresponding [PR](https://github.com/Kotlin/kotlinx.serialization/pull/1528). |
| 33 | + |
| 34 | +### Excluding null values from JSON serialization |
| 35 | + |
| 36 | +In 1.3.0, we’re introducing one more way to reduce the size of the generated JSON strings: omitting null values. |
| 37 | +A new JSON configuration property `explicitNulls` defines whether `null` property values should be included in the serialized JSON string. |
| 38 | +The difference from `encodeDefaults` is that `explicitNulls = false` flag drops null values even if the property does not have a default value. |
| 39 | +Upon deserializing such a missing property, a `null` or default value (if it exists) will be used. |
| 40 | + |
| 41 | +To maintain backwards compatibility, this flag is set to `true` by default. |
| 42 | +You can learn more in the [documentation](docs/json.md#explicit-nulls) or the [PR](https://github.com/Kotlin/kotlinx.serialization/pull/1535). |
| 43 | + |
| 44 | +### Per-hierarchy polymorphic class discriminators |
| 45 | + |
| 46 | +In previous versions, you could change the discriminator name using the |
| 47 | +[classDiscriminator](https://github.com/Kotlin/kotlinx.serialization/blob/master/docs/json.md#class-discriminator) property of the `Json` instance. |
| 48 | +In 1.3.0, we’re adding a way to set a custom discriminator name for each class hierarchy to enable more flexible serialization. |
| 49 | +You can do it by annotating a class with `@JsonClassDiscriminator` with the discriminator name as its argument. |
| 50 | +A custom discriminator is applied to the annotated class and its subclasses. |
| 51 | +Only one custom discriminator can be used in each class hierarchy, thanks to the new `@InheritableSerialInfo` annotation. |
| 52 | + |
| 53 | +Check out corresponding [PR](https://github.com/Kotlin/kotlinx.serialization/pull/1608) for details. |
| 54 | + |
| 55 | +### Support for Java module system |
| 56 | + |
| 57 | +Now all kotlinx.serialization runtime libraries are shipped as a multi-release JAR with `module-info.class` file for Java versions 9 and higher. |
| 58 | +This enables possibilities to use kotlinx.serialization with modern tools such as `jlink` and various technologies such as `TorandoFX`. |
| 59 | + |
| 60 | +Many thanks to our contributor [Gerard de Leeuw](https://github.com/lion7) and his [PR](https://github.com/Kotlin/kotlinx.serialization/pull/1624) for making this possible. |
| 61 | + |
| 62 | +### Native targets for Apple Silicon |
| 63 | + |
| 64 | +This release includes klibs for new targets, introduced in Kotlin/Native 1.5.30 — |
| 65 | +`macosArm64`, `iosSimulatorArm64`, `watchosSimulatorArm64`, and `tvosSimulatorArm64`. |
| 66 | + |
| 67 | +### Bugfixes and improvements |
| 68 | + |
| 69 | + * Properly handle quoted 'null' literals in lenient mode (#1637) |
| 70 | + * Switch on deep recursive function when nested level of JSON is too deep (#1596) |
| 71 | + * Support for local serializable classes in IR compiler |
| 72 | + * Support default values for `@SerialInfo` annotations in IR compiler |
| 73 | + * Improve error message for JsonTreeReader (#1597) |
| 74 | + * Add guide for delegating serializers and wrapping serial descriptor (#1591) |
| 75 | + * Set target JVM version to 8 for Hocon module in Gradle metadata (#1661) |
1 | 76 |
|
2 | 77 | 1.2.2 / 2021-07-08 |
3 | 78 | ================== |
|
0 commit comments