ZIO Schema

Once a schema is defined, ZIO Schema provides a rich set of operations to manipulate, transform, and interact with data. These operations allow you to combine schemas, transform data types, handle optionality, perform migrations, and manage data patches. Common categories of operations include:

• Composition: Combining schemas using product (<*>, zip) or sum (<+>, orElseEither) types.
• Transformation: Converting between types using transform or transformOrFail.
• Data Manipulation: Converting to/from DynamicValue via toDynamic and fromDynamic.
• Validation & Patching: Validating values with validate and applying changes via diff and patch.
• Schema Evolution: Migrating data between schemas using migrate or coercing schemas with coerce.
• Metadata: Accessing the schema's structure via ast or adding metadata via annotate.

sealed trait Schema[A] {
  def ? : Schema[Option[A]]
  def <*>[B](that: Schema[B]): Schema[(A, B)]
  def <+>[B](that: Schema[B]): Schema[scala.util.Either[A, B]]
  def defaultValue: scala.util.Either[String, A]
  def annotations: Chunk[Any]
  def ast: MetaSchema 
  def annotate(annotation: Any): Schema[A]
  def coerce[B](newSchema: Schema[B]): Either[String, Schema[B]]
  def diff(thisValue: A, thatValue: A): Patch[A]
  def patch(oldValue: A, diff: Patch[A]): scala.util.Either[String, A]
  def fromDynamic(value: DynamicValue): scala.util.Either[String, A] 
  def makeAccessors(b: AccessorBuilder): Accessors[b.Lens, b.Prism, b.Traversal]
  def migrate[B](newSchema: Schema[B]): Either[String, A => scala.util.Either[String, B]]
  def optional: Schema[Option[A]]
  def ordering: Ordering[A]
  def orElseEither[B](that: Schema[B]): Schema[scala.util.Either[A, B]]
  def repeated: Schema[Chunk[A]]
  def serializable: Schema[Schema[A]]
  def toDynamic(value: A): DynamicValue
  def transform[B](f: A => B, g: B => A): Schema[B]
  def transformOrFail[B](f: A => scala.util.Either[String, B], g: B => scala.util.Either[String, A]): Schema[B]
  def validate(value: A)(implicit schema: Schema[A]): Chunk[ValidationError]
  def zip[B](that: Schema[B]): Schema[(A, B)]
}

A BinaryCodec[A] is a specialized version of a Codec specifically designed for binary formats (where the output is Chunk[Byte] and the input elements are Byte).

Beyond simple single-value encoding/decoding, a BinaryCodec[A] provides built-in support for streaming. It allows you to transform a stream of values of type A into a stream of bytes (and vice versa) using ZPipeline.

Key capabilities of BinaryCodec[A]:

• encode(value: A): Chunk[Byte]: Encodes a single value.
• decode(whole: Chunk[Byte]): Either[DecodeError, A]: Decodes a single chunk.
• streamEncoder: A ZPipeline to transform a stream of A into a stream of Byte.
• streamDecoder: A ZPipeline to transform a stream of Byte into a stream of A.

trait BinaryCodec[A] {
  def encode(value: A): Chunk[Byte]
  def decode(whole: Chunk[Byte]): Either[DecodeError, A]

  def streamEncoder: ZPipeline[Any, Nothing, A, Byte]
  def streamDecoder: ZPipeline[Any, DecodeError, Byte, A]
}

A DynamicValue is a self-describing representation of data that combines both the value and its structural type information. Unlike relational models where schema and data are separate, a DynamicValue carries its own structure, making it useful for document-based models (like JSON) or for inspecting data without knowing the original type at compile time.

You can create a DynamicValue from a typed value using DynamicValue.fromSchemaAndValue(schema, value) or by calling schema.toDynamic(value). To convert it back to a typed value, use DynamicValue#toTypedValue[A](implicit schema: Schema[A]).

import zio.schema._

case class Person(name: String, age: Int)
object Person {
  implicit val schema: Schema[Person] = DeriveSchema.gen[Person]
}

val person = Person("John Doe", 42)
// Create DynamicValue
val dynamicPerson = DynamicValue.fromSchemaAndValue(Person.schema, person)
// OR
val dynamicPersonAlt = Person.schema.toDynamic(person)

// Convert back to typed value
val recoveredPerson: Either[String, Person] = dynamicPerson.toTypedValue[Person](Person.schema)
// Note: toTypedValue requires an implicit schema for the target type A

The Schema#migrate method allows you to map one schema to another, which is useful for schema evolution or converting DTOs to domain objects without full serialization.

When you call sourceSchema.migrate(targetSchema), it returns an Either[String, source => Either[String, target]].

• If the migration logic is valid, you receive a Right containing a function. This function takes an instance of the source type and returns an Either[String, target], allowing for potential transformation errors.
• If the migration logic is invalid, you receive a Left with an error message.

This is particularly useful when you want to perform the transformation within a ZIO effect, handling potential errors gracefully.

// Example of using migrate to transform a DTO to a Person
def fromPersonDTO(p: PersonDTO): IO[String, Person] =
  ZIO.fromEither(
    PersonDTO.schema
      .migrate(personDTOMapperSchema) // Returns Either[String, PersonDTO => Either[String, Person]]
      .flatMap(_(p))                 // Applies the transformation function to the DTO
  )