@zio.dev/zio-blocks 0.0.1

package/reference/modifier.md

@@ -0,0 +1,276 @@
+---
+id: modifier
+title: "Modifier"
+---
+
+`Modifier` is a sealed trait that provides a mechanism to attach metadata and configuration to schema elements. Modifiers serve as annotations for record fields, variant cases, and reflect values, enabling format-specific customization without polluting domain types.
+
+Unlike Scala annotations, modifiers are **pure data** values that can be serialized, making them ideal for runtime introspection and cross-process schema exchange.
+
+```scala
+sealed trait Modifier extends StaticAnnotation
+```
+
+## Modifier Hierarchy
+
+```
+┌────────────────────────────────────────────────────────────────┐
+│                         Modifier                               │
+├────────────────────────────────────────────────────────────────┤
+│  ┌─────────────────────────────────────────────────────────┐   │
+│  │  Modifier.Term                                          │   │
+│  │  (annotates record fields and variant cases)            │   │
+│  │                                                         │   │
+│  │  - transient()      : exclude from serialization        │   │
+│  │  - rename(name)     : change serialized name            │   │
+│  │  - alias(name)      : add alternative name              │   │
+│  │  - config(key, val) : attach key-value metadata         │   │
+│  └─────────────────────────────────────────────────────────┘   │
+│  ┌─────────────────────────────────────────────────────────┐   │
+│  │  Modifier.Reflect                                       │   │
+│  │  (annotates reflect values / types)                     │   │
+│  │                                                         │   │
+│  │  - config(key, val) : attach key-value metadata         │   │
+│  └─────────────────────────────────────────────────────────┘   │
+└────────────────────────────────────────────────────────────────┘
+```
+
+## Term Modifiers
+
+Term modifiers annotate record fields and variant cases. They are used during schema derivation to customize how fields are serialized and deserialized.
+
+### transient
+
+The `transient` modifier marks a field as transient, meaning it will be excluded from serialization. This is useful for computed fields, caches, or sensitive data that shouldn't be persisted.
+
+```scala mdoc:compile-only
+import zio.blocks.schema._
+
+case class User(
+  id: Long,
+  name: String,
+  @Modifier.transient cache: Map[String, String] = Map.empty
+)
+
+object User {
+  implicit val schema: Schema[User] = Schema.derived
+}
+```
+
+When encoding a `User` to JSON, the `cache` field will be omitted:
+
+```json
+{"id": 1, "name": "Alice"}
+```
+
+During decoding, transient fields use their default values. Therefore, **transient fields must have default values** defined in the case class.
+
+### rename
+
+The `rename` modifier changes the serialized name of a field or variant case. This is useful when the field name in your Scala code differs from the expected name in the serialized format.
+
+```scala mdoc:compile-only
+import zio.blocks.schema._
+
+case class Person(
+  @Modifier.rename("user_name") name: String,
+  @Modifier.rename("user_age") age: Int
+)
+
+object Person {
+  implicit val schema: Schema[Person] = Schema.derived
+}
+```
+
+When encoding a `Person` to JSON:
+
+```json
+{"user_name": "Alice", "user_age": 30}
+```
+
+You can also use `rename` on variant cases to customize the discriminator value:
+
+```scala mdoc:compile-only
+import zio.blocks.schema._
+
+sealed trait PaymentMethod
+
+object PaymentMethod {
+  @Modifier.rename("credit_card")
+  case class CreditCard(number: String, cvv: String) extends PaymentMethod
+
+  @Modifier.rename("bank_transfer")
+  case class BankTransfer(iban: String) extends PaymentMethod
+
+  implicit val schema: Schema[PaymentMethod] = Schema.derived
+}
+```
+
+### alias
+
+The `alias` modifier provides an alternative name for a term during decoding. This is useful for supporting multiple names during schema evolution or data migration.
+
+```scala mdoc:compile-only
+import zio.blocks.schema._
+
+@Modifier.rename("NewName")
+@Modifier.alias("OldName")
+@Modifier.alias("LegacyName")
+case class MyClass(value: String)
+
+object MyClass {
+  implicit val schema: Schema[MyClass] = Schema.derived
+}
+```
+
+With this configuration:
+- **Encoding** always uses the `rename` value: `"NewName"`
+- **Decoding** accepts any of: `"NewName"`, `"OldName"`, or `"LegacyName"`
+
+This pattern is particularly useful when migrating data formats without breaking compatibility with existing data.
+
+### config
+
+The `config` modifier attaches arbitrary key-value metadata to a term. The convention for keys is `<format>.<property>`, allowing format-specific configuration.
+
+```scala mdoc:compile-only
+import zio.blocks.schema._
+
+case class Event(
+  @Modifier.config("protobuf.field-id", "1") id: Long,
+  @Modifier.config("protobuf.field-id", "2") name: String
+)
+
+object Event {
+  implicit val schema: Schema[Event] = Schema.derived
+}
+```
+
+The `config` modifier extends both `Term` and `Reflect`, making it usable on both fields and types.
+
+## Reflect Modifiers
+
+Reflect modifiers annotate reflect values (types themselves). Currently, only `config` is a reflect modifier.
+
+### Using config on Types
+
+You can attach configuration to the type itself using the `Schema#modifier` method:
+
+```scala mdoc:compile-only
+import zio.blocks.schema._
+
+case class Person(name: String, age: Int)
+
+object Person {
+  implicit val schema: Schema[Person] = Schema.derived
+    .modifier(Modifier.config("db.table-name", "person_table"))
+    .modifier(Modifier.config("schema.version", "v2"))
+}
+```
+
+Or add multiple modifiers at once:
+
+```scala mdoc:compile-only
+import zio.blocks.schema._
+
+case class Person(name: String, age: Int)
+
+object Person {
+  implicit val schema: Schema[Person] = Schema.derived
+    .modifiers(
+      Seq(
+        Modifier.config("db.table-name", "person_table"),
+        Modifier.config("schema.version", "v2")
+      )
+    )
+}
+```
+
+## Programmatic Modifier Access
+
+You can access modifiers programmatically through the `Reflect` structure:
+
+```scala mdoc:compile-only
+import zio.blocks.schema._
+
+case class Person(
+  @Modifier.rename("full_name") name: String,
+  @Modifier.transient cache: String = ""
+)
+
+object Person {
+  implicit val schema: Schema[Person] = Schema.derived
+}
+
+// Access field modifiers through the reflect
+val reflect = Schema[Person].reflect
+reflect match {
+  case record: Reflect.Record[_, _] =>
+    record.fields.foreach { field =>
+      println(s"Field: ${field.name}")
+      println(s"Modifiers: ${field.modifiers}")
+    }
+  case _ => ()
+}
+```
+
+## Built-in Schema Support
+
+All modifier types have built-in `Schema` instances, enabling them to be serialized and deserialized:
+
+```scala mdoc:compile-only
+import zio.blocks.schema._
+
+// Schema instances for individual modifiers
+Schema[Modifier.transient]
+Schema[Modifier.rename]
+Schema[Modifier.alias]
+Schema[Modifier.config]
+
+// Schema instances for modifier traits
+Schema[Modifier.Term]
+Schema[Modifier.Reflect]
+Schema[Modifier]
+```
+
+This enables scenarios like:
+- Serializing schema metadata across process boundaries
+- Storing schema configuration in databases
+- Building schema registries with full modifier information
+
+## Format Support
+
+Different serialization formats interpret modifiers according to their semantics:
+
+| Modifier    | JSON | BSON | Avro | Protobuf |
+|-------------|------|------|------|----------|
+| `transient` | Field omitted | Field omitted | Field omitted | Field omitted |
+| `rename`    | Custom field name | Custom field name | Custom field name | Custom field name |
+| `alias`     | Accepts alternatives | Accepts alternatives | - | - |
+| `config`    | Format-specific | Format-specific | Format-specific | Format-specific |
+
+## Best Practices
+
+1. **Use `rename` for external APIs**: When integrating with external systems that use different naming conventions (snake_case vs camelCase), use `rename` to match the expected format.
+
+2. **Use `alias` for migrations**: When evolving your data model, add `alias` modifiers to support reading old data while writing with new names.
+
+3. **Use `transient` sparingly**: Only mark fields as transient when they are truly derived or temporary. Remember that transient fields need default values.
+
+4. **Use namespaced keys for `config`**: Follow the `<format>.<property>` convention to avoid conflicts between different formats or tools.
+
+5. **Combine modifiers**: You can apply multiple modifiers to the same field:
+
+```scala mdoc:compile-only
+import zio.blocks.schema._
+
+case class Document(
+  @Modifier.rename("doc_id")
+  @Modifier.config("protobuf.field-id", "1")
+  id: String
+)
+
+object Document {
+  implicit val schema: Schema[Document] = Schema.derived
+}
+```