uPickle Documentation

For developers looking to master uPickle, the following resources are recommended:

• Blog Post: How to work with JSON in Scala provides a hands-on introduction.
• Book: Hands-on Scala Programming contains an entire chapter (Chapter 8) dedicated to JSON and Binary Data Serialization using uPickle.

Converting between MessagePack and JSON is lossy because some MessagePack constructs (like binary data) cannot be exactly represented in JSON.

Key differences include:

• Large Longs: In JSON, values $> 2^{53}$ are represented as ujson.Str (strings). In MessagePack, they are represented as upack.Int64 or upack.UInt64.
• Byte Arrays: Array[Byte] is represented as a list of numbers in JSON, but as upack.Binary in MessagePack.

Note: Round-tripping between Scala data types <-> JSON and Scala data types <-> MessagePack is always safe, but JSON <-> MessagePack is not.

Use the @key("...") annotation to control the name used for a field during serialization. This is useful for:

• Backwards Compatibility: Renaming a field in Scala while keeping the old name in the JSON.
• Tag Overriding: Changing the type tag used for members of a sealed trait hierarchy (default is $type).
• Compatibility: Changing the key used for sealed hierarchy members to match other JSON libraries.

The @flatten annotation allows you to merge fields of a nested structure into the parent structure during serialization and deserialization.

Use Cases

1. Case Classes: Flatten fields of a nested case class into the parent.
2. Iterables: Flatten key-value pairs of an Iterable[(String, _)] (like a Map[String, String]) into the parent structure.

Limitations

• You cannot flatten more than two collections to the same level.
• When flattening an Iterable, the key type must be String.

case class A(i: Int, @@flatten b: B)
case class B(msg: String)
implicit val rw: ReadWriter[A] = macroRW
implicit val rw: ReadWriter[B] = macroRW
write(A(1, B("Hello"))) // {"i":1, "msg": "Hello"}

The ujson.Value hierarchy consists of the following types:

• ujson.Str(value: String): A JSON string.
• ujson.Obj(value: LinkedHashMap[String, Value]): A JSON object.
• ujson.Arr(value: mutable.ArrayBuffer[Value]): A JSON array.
• ujson.Num(value: Double): A JSON number.
• ujson.Bool: A JSON boolean (ujson.True or ujson.False).
• ujson.Null: A JSON null value.

ujson.Obj and ujson.Arr provide apply methods for convenient construction.

// Constructing an object
val obj = ujson.Obj("a" -> 1, "b" -> "two")

// Constructing an array
val arr = ujson.Arr(1, 2, 3)

// Constructing a boolean
val b = ujson.Bool(true)

uPickle allows you to write Scala objects to JSON strings or MessagePack byte arrays, and read them back.

Note on Scala Versions:

• In Scala 3, use the convenient upickle.{read, write}.
• In Scala 2.x, you must use the more verbose upickle.default.{read, write}.

Supported Types

• Primitives: Boolean, Byte, Char, Short, Int, Long, Float, Double.
• Collections: Seq, List, Vector, Set, SortedSet, Option, Array, Map, Tuple (1-22).
• Others: Duration, Either, UUID, null, and sealed trait/sealed class hierarchies.
• Case Classes: Up to 64 fields.

Serialization Formats

• JSON: Human-readable text.
• MessagePack: Binary format via upack, providing faster serialization and smaller payloads.

uPickle 4.0.0 is a major breaking change affecting serialization formats (e.g., Options, sealed traits) and binary compatibility.

To upgrade while preserving your existing serialization format:

1. Define a Custom Configuration.
2. Replace all usages of upickle.default with your custom configuration.
3. In your configuration, set:
   • override def objectTypeKeyWriteFullyQualified = true (forwards and backwards compatible).
   • override def optionsAsNulls = false (Note: This is not forwards or backwards compatible; use this if you cannot perform a 'big bang' upgrade of all data/code simultaneously).