Summary

• Implement pure, serializable migration core for ZIO Schema 2 (DynamicMigration + MigrationAction + DynamicSchemaExpr schemas).
• Add Schema.structural derivation for structural records/variants and structural bindings (Scala 3).
• Add selector macros + builder syntax for optic-style paths (Scala 2/3).
• Add build-time validation, DefaultValue resolution, correct transform context, and extended runtime path traversal.

Examples

Structural schema + addField

type PersonV1 = { def name: String }
@schema case class PersonV2(name: String, age: Int)

implicit val v1Schema: Schema[PersonV1] = Schema.structural[PersonV1]

val v1ToV2 =
  MigrationBuilder[PersonV1, PersonV2]
    .addField(_.age, 0)
    .build

Rename + composition

@schema case class PersonV3(fullName: String, age: Int)

val v2ToV3 =
  MigrationBuilder[PersonV2, PersonV3]
    .renameField(_.name, _.fullName)
    .buildPartial

val v1ToV3 = v1ToV2 ++ v2ToV3

Selector grammar (paths)

MigrationBuilder[Old, New] .dropField(.address.street) .optionalizeField(.email) .buildPartial

Notable behavior

• build() validates structural changes (including optionality) by simulating actions.
• DefaultValue resolves at build time (forward strict; reverse best-effort).
• Typed Migration.apply returns a MigrationError for structural-only schemas; use applyDynamic.

Tests

• sbt -no-colors schemaJVM/test schemaJS/test

Demo / Video

https://github.com/user-attachments/assets/75fbdf84-8b30-4ddb-8f3b-21e07d8b88df

Notes / limitations

• Scala 2 cannot derive Schema.structural for true structural/union types.
• Typed apply for structural schemas is intentionally unsupported (use applyDynamic).

Review guide

• Serialization schemas: schema/shared/src/main/scala/zio/blocks/schema/migration/MigrationSchemas.scala
• Structural derivation: schema/shared/src/main/scala-3/zio/blocks/schema/SchemaCompanionVersionSpecific.scala (+ bindings)
• Selector macros + syntax: schema/shared/src/main/scala-2|3/zio/blocks/schema/migration/*
• Validation: schema/shared/src/main/scala/zio/blocks/schema/migration/MigrationValidator.scala
• Tests: schema/shared/src/test/scala/zio/blocks/schema/migration/*

Issues

• Addresses #519
• Refs #882, #941
• /claim #519