From 1d60d4cf735660944a9d0823e4c625c23810e5f2 Mon Sep 17 00:00:00 2001 From: Zac Sweers Date: Thu, 9 Dec 2021 15:37:50 -0500 Subject: [PATCH] Document Json.ignore in the README (#1456) --- README.md | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 67f1584..2192939 100644 --- a/README.md +++ b/README.md @@ -739,7 +739,7 @@ class ColorAdapter { Use `@JsonQualifier` when you need different JSON encodings for the same type. Most programs shouldn’t need this `@JsonQualifier`, but it’s very handy for those that do. -### Omit fields with `transient` +### Omitting fields Some models declare fields that shouldn’t be included in JSON. For example, suppose our blackjack hand has a `total` field with the sum of the cards: @@ -769,14 +769,15 @@ class BlackjackHand( By default, all fields are emitted when encoding JSON, and all fields are accepted when decoding -JSON. Prevent a field from being included by adding Java’s `transient` keyword or Kotlin's `@Transient` annotation: +JSON. Prevent a field from being included by annotating them with `@Json(ignore = true)`.
Java ```java public final class BlackjackHand { - private transient int total; + @Json(ignore = true) + private int total; ... } @@ -788,16 +789,20 @@ public final class BlackjackHand { ```kotlin class BlackjackHand(...) { - @Transient var total: Int + @Json(ignore = true) + var total: Int = 0 ... } ```
-Transient fields are omitted when writing JSON. When reading JSON, the field is skipped even if the -JSON contains a value for the field. Instead, it will get a default value. +These fields are omitted when writing JSON. When reading JSON, the field is skipped even if the +JSON contains a value for the field. Instead, it will get a default value. In Kotlin, these fields +_must_ have a default value if they are in the primary constructor. +Note that you can also use Java’s `transient` keyword or Kotlin's `@Transient` annotation on these fields +for the same effect. ### Default Values & Constructors