Skip to main content
Version: 2.x

ZIO Blocks Schema

Introduction​

ZIO Blocks Schema is the core type system and serialization framework that provides reified structural metadata for Scala data types. It enables type-safe schema definition, validation, optics-based data access, multi-format serialization, and runtime introspection — all derived from a single Schema definition.

Core Type System:

  • Schema — Primary data type containing reified structure of a Scala data type
  • Reflect — Foundational data structure containing reified structural information
  • Binding — Operational machinery for constructing and deconstructing values
  • Registers — Register-based design for zero-allocation construction and deconstruction
  • Structural Types — Duck typing with ZIO Blocks schemas

Dynamic & Runtime Data:

  • DynamicValue — Schema-less, dynamically-typed representation of any structured value
  • DynamicSchema — Type-erased schema container for serialization and transport
  • Lazy — Deferred computation with monadic abstraction, memoization, and stack-safe evaluation

Navigation & Transformation:

  • Optics — Reflective optics for type-safe, composable access to nested data structures
  • DynamicOptic — Runtime path through nested data structures
  • Path Interpolator — Compile-time string interpolator p"..." for constructing DynamicOptic instances
  • SchemaExpr — Schema-aware expressions for evaluation and query language translation
  • Patch — Type-safe, serializable transformations of data structures
  • Modifier — Mechanism to attach metadata and configuration to schema elements

Serialization:

  • Codec — Base abstraction for encoding and decoding values between formats
  • Format — Unified abstraction bundling serialization and deserialization for a specific format
  • Type Class Derivation — Automatic generation of type class instances from schemas
  • Syntax — Extension methods for fluent JSON encoding/decoding and patching

Formats:

  • JSON Codec — Complete JSON support: ADT for JSON values, fluent navigation, encoding/decoding, diffs, patches, and JSON Schema 2020-12 validation
  • Xml — Type-safe, immutable representation of XML document structures

Validation & Errors:

  • Validation — Declarative constraints on primitive values
  • SchemaError — Structured error type for schema operations
  • Allows — Compile-time capability token proving a type satisfies a structural grammar

Overview​

The ZIO Blocks Schema module revolves around the Schema and Reflect types, which capture the complete structural description of Scala data types at runtime. From a single schema definition, you get automatic derivation of codecs (Codec, Formats), type-safe data access (Optics, DynamicOptic), structural validation (Validation, SchemaError), patching (Patch, JsonPatch), and serialization to multiple formats (Json, Xml, JSON Schema).

The type system is powered by a register-based architecture (Registers) that eliminates boxing overhead, and supports both compile-time (Allows) and runtime (DynamicValue, DynamicSchema) type manipulation. The Deriver system (Type Class Derivation) enables automatic generation of any type class instance from schema metadata.