sorbet-schema 0.9.3 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d6e96bccc5924a52824327d2d5bc3b8e79b887ac31d13b292581c347c1d43480
-  data.tar.gz: 36896e42540d07c714b8075c7c2b89b4d47c5d09d1e098e83ecf050f6c68fa50
+  metadata.gz: 8ae3eaa249b0881483d4fe8edd8c295ada54733bb78d106525767506e83f20bb
+  data.tar.gz: f36595f7d0831a83234453acccb941dc3bcff703562a87a52dbb1b2dbfd0dce0
 SHA512:
-  metadata.gz: c0a12cf7754d2e13eaebb5a0b042a2abea848dc79aeda84b2887f0c949b523c2aa8a1b3a842562ee053c15dcb3b5a13c6caf1e760bbf9c7f297ea39285c5e1e3
-  data.tar.gz: b72bc80795f41444f06b2aa9bc7186f3669993c95cb7e3e500e021fc2c053c2ac5088d2e3a0efae32aa4e1bd0d35c138602de08fba9f31ded554b43ae7aefd4d
+  metadata.gz: 1ff4723d4f1a749d3d2ee7255b4c024c783b10acf7701240889d9bc25b3682df9c308a6a525c6a055bb8b4a627ce8214d45dfda6c359b064f90beb43693fe5bc
+  data.tar.gz: f3352237a1b10e95747c313c4937869c2baac94e45cedd1eb29c3b550d5a7c41b731b07505fbb61d7645e7d46efec986d95a95ed2d3472bf9e65cac9403340bf

data/.ruby-version

@@ -1 +1 @@
-3.3.4
+3.4.7

data/AGENTS.md

@@ -0,0 +1,16 @@
+# Project agent memory
+
+This file is the project's committed home for project-intrinsic agent knowledge: build, test, release, architecture, and sharp-edge notes that should travel with the code.
+
+- Add durable project-specific notes here as they are discovered through real work.
+- Ruby 3.4+ unbundles former stdlib gems (e.g. `csv`) from the default load path, so `require "csv"` is not free — it needs the gem actually installed.
+- Format-specific serializers keep their backing gems optional: load the gem in `initialize`, raise a clear `ArgumentError` on `LoadError`, and keep class-body signatures safe to reflect without the gem installed. See `lib/typed/csv_serializer.rb` and `lib/typed/active_record_serializer.rb`; the latter uses a generic model output instead of referencing `ActiveRecord::Base` in signatures. Verify eager loading changes with `bundle exec tapioca gem` in a consumer bundle without `activerecord`, and keep the factory's missing-gem behavior consistent.
+- Every `Typed::Serializer` subclass (all six format serializers) and `Typed::Schema` are generic over the struct type via a `StructT = type_member { {upper: T::InexactStruct} }` re-declared in each subclass — `T::InexactStruct` is Sorbet's common superclass for `T::Struct` and `T::ImmutableStruct`; Sorbet cannot propagate their union as a type-member bound. This lets every deserialize path (`deserialize_from`, `.serializer(:x).deserialize`, `.schema.from_x`, direct serializer construction) return the concrete struct type with no `T.cast`. `Typed::Schema#target` is `T.all(T::Class[StructT], StructClass)`, not the bare `T::Class[StructT]`: Sorbet runtime erases `T::Class[X]` to `T::Class[T.untyped]`, while the `StructClass` intersection restores the runtime restriction to `T::Struct`/`T::ImmutableStruct` descendants. See `lib/typed/serializer.rb`, `lib/typed/schema.rb`, and `lib/typed/hash_serializer.rb`'s `self.new` override (the one class that needs it, for direct-construction type inference) for the exact shape when adding a new serializer.
+- After adding a new *required* runtime gem dependency (not this optional-serializer case), run `bundle exec tapioca gem` (add the gem to `sorbet/tapioca/require.rb` first if it isn't required anywhere else) so `bundle exec rake` (which runs `srb tc`) has an RBI to check against.
+
+## Maintaining this file
+
+Keep this file for knowledge useful to almost every future agent session in this project.
+Do not repeat what the codebase already shows; point to the authoritative file or command instead.
+Prefer rewriting or pruning existing entries over appending new ones.
+When updating this file, preserve this bar for all agents and keep entries concise.

data/CHANGELOG.md

@@ -4,6 +4,56 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.11.0](https://github.com/maxveldink/sorbet-schema/compare/v0.10.0...v0.11.0) (2026-10-11)
+
+
+### ⚠ BREAKING CHANGES
+
+* **typed:** ActiveRecord serializer annotations now take the model type first and struct type second: `Typed::ActiveRecordSerializer[PersonModel, Person]`. Direct `.new(schema: Person.schema, model_class: PersonModel)` infers both types. Regenerate consumer gem RBIs after upgrading.
+* **typed:** `Typed::Serializer::DeserializeResult` and `Typed::Coercion::StructCoercer::Target` now accept immutable as well as mutable structs. `DeserializeResult` is `Typed::Result[Typed::StructValue, Typed::DeserializeError]`, where `Typed::StructValue` is the union of `T::Struct` and `T::ImmutableStruct`. Update annotations that assume these aliases only contain `T::Struct`; use `Typed::StructValue` when handling both, or obtain a concrete struct result through a parameterized schema or serializer.
+* **typed:** Props with a `name:` option now use that name for both input and output in Hash, JSON, CSV, YAML, and MessagePack. For `const :event_id, String, name: "eventId"`, migrate payload keys and CSV headers from `event_id` to `eventId`. The old key no longer populates the field: required fields fail validation, while optional fields may use their default or nil. ActiveRecord continues to use Ruby attribute names.
+* **typed:** Schema and serializers now require a struct type argument in Sorbet annotations. Use `Typed::Schema[Person]`, `Typed::HashSerializer[Person]` (and the equivalent JSON, CSV, YML, and MessagePack types), and `Typed::Serializer[Input, Output, Person]` instead of the former unparameterized classes or two-argument base serializer. Custom serializer subclasses must redeclare `StructT = type_member { {upper: T::InexactStruct} }` and use it in their schema, serialize, and deserialize signatures (including `Typed::Schema[StructT]` and `Typed::Result[StructT, Typed::DeserializeError]`). Regenerate consumer gem RBIs and update custom `.schema` overrides to return a parameterized schema. Prefer `Schema.from_struct(Person)` or `Typed::Schema[Person].new(...)` to preserve concrete type inference.
+
+### Features
+
+* **typed:** generate a JSON Schema from a schema ([#152](https://github.com/maxveldink/sorbet-schema/issues/152)) ([575ae72](https://github.com/maxveldink/sorbet-schema/commit/575ae72eabd7f0a3ade6299732128a586041b5bf))
+* **typed:** honor the prop name: option as the serialized key ([08490d2](https://github.com/maxveldink/sorbet-schema/commit/08490d26c04385cd00a651b9e10506ad75ce960f))
+* **typed:** make Serializer and Schema generic over struct type ([086e867](https://github.com/maxveldink/sorbet-schema/commit/086e8671aeda7868e6dde98b8d23621918059e4b))
+* **typed:** support immutable nested JSON Schema ([#162](https://github.com/maxveldink/sorbet-schema/issues/162)) ([d74d6cd](https://github.com/maxveldink/sorbet-schema/commit/d74d6cdd63017a268f1ecd78f1e68314460767c9))
+* **typed:** support immutable structs ([288c972](https://github.com/maxveldink/sorbet-schema/commit/288c972cd87cb194b19743d3eb5bb7c2e9f7f617))
+
+
+### Bug Fixes
+
+* **activerecord:** load the optional gem lazily and raise `ArgumentError` when unavailable, including direct construction that previously raised `NameError` ([bf7e894](https://github.com/maxveldink/sorbet-schema/commit/bf7e8948353b58a692f9ad7d115440edc7b1ebb5))
+* **json:** return `Failure(ParseError)` for non-object JSON roots (arrays, scalars, and null); update callers that rescue exceptions for these inputs ([bf7e894](https://github.com/maxveldink/sorbet-schema/commit/bf7e8948353b58a692f9ad7d115440edc7b1ebb5))
+* **schema:** preserve optionality, nullability, defaults, serialized names, and descriptions when updating a field with `add_serializer` ([bf7e894](https://github.com/maxveldink/sorbet-schema/commit/bf7e8948353b58a692f9ad7d115440edc7b1ebb5))
+* **typed:** harden JSON parsing, field updates, and ActiveRecord loading ([bf7e894](https://github.com/maxveldink/sorbet-schema/commit/bf7e8948353b58a692f9ad7d115440edc7b1ebb5))
+
+## [0.10.0](https://github.com/maxveldink/sorbet-schema/compare/v0.9.3...v0.10.0) (2026-08-07)
+
+
+### ⚠ BREAKING CHANGES
+
+* bump local Ruby to 3.4, add to matrix ([#138](https://github.com/maxveldink/sorbet-schema/issues/138))
+
+### Features
+
+* add Typed::CSVSerializer ([#12](https://github.com/maxveldink/sorbet-schema/issues/12)) ([#144](https://github.com/maxveldink/sorbet-schema/issues/144)) ([b2377f0](https://github.com/maxveldink/sorbet-schema/commit/b2377f083782c0eb39ab442b14cb4bf18a2a8922))
+* add Typed::MessagePackSerializer ([#145](https://github.com/maxveldink/sorbet-schema/issues/145)) ([d367da8](https://github.com/maxveldink/sorbet-schema/commit/d367da83b2d9e72f5099b70594243178c3df432c))
+* add Typed::YMLSerializer ([#13](https://github.com/maxveldink/sorbet-schema/issues/13)) ([#143](https://github.com/maxveldink/sorbet-schema/issues/143)) ([bcc7eb8](https://github.com/maxveldink/sorbet-schema/commit/bcc7eb810f32b46d454df3a0c19468b0de09f498))
+* **typed:** add ActiveRecord serializer ([#140](https://github.com/maxveldink/sorbet-schema/issues/140)) ([a815f9f](https://github.com/maxveldink/sorbet-schema/commit/a815f9f42cb36c26ead45630384eb6b5022cd43d))
+
+
+### Bug Fixes
+
+* **typed:** make csv and msgpack gem dependencies optional ([#146](https://github.com/maxveldink/sorbet-schema/issues/146)) ([db22258](https://github.com/maxveldink/sorbet-schema/commit/db222586207129fc46d981a8efd28413aea99c7b))
+
+
+### Miscellaneous Chores
+
+* bump local Ruby to 3.4, add to matrix ([#138](https://github.com/maxveldink/sorbet-schema/issues/138)) ([1cf6a5b](https://github.com/maxveldink/sorbet-schema/commit/1cf6a5bdb77137ee34aa5c1bca66dd1ede37f875))
+
 ## [0.9.3](https://github.com/maxveldink/sorbet-schema/compare/v0.9.2...v0.9.3) (2025-12-06)
 
 

data/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

data/Gemfile

@@ -12,7 +12,7 @@ group :development do
   gem "standard-performance"
   gem "standard-sorbet"
   gem "sorbet"
-  gem "tapioca", require: false
+  gem "tapioca", "~> 0.20", require: false
 end
 
 group :development, :test do
@@ -24,4 +24,7 @@ group :development, :test do
   gem "debug"
 
   gem "sorbet-struct-comparable"
+
+  gem "activerecord", ">= 6.0"
+  gem "sqlite3"
 end

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    sorbet-schema (0.9.3)
+    sorbet-schema (0.11.0)
       sorbet-result (~> 1.1)
       sorbet-runtime (~> 0.5)
       sorbet-struct-comparable (~> 1.3)
@@ -10,15 +10,42 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
+    activemodel (8.1.2)
+      activesupport (= 8.1.2)
+    activerecord (8.1.2)
+      activemodel (= 8.1.2)
+      activesupport (= 8.1.2)
+      timeout (>= 0.4.0)
+    activesupport (8.1.2)
+      base64
+      bigdecimal
+      concurrent-ruby (~> 1.0, >= 1.3.1)
+      connection_pool (>= 2.2.5)
+      drb
+      i18n (>= 1.6, < 2)
+      json
+      logger (>= 1.4.2)
+      minitest (>= 5.1)
+      securerandom (>= 0.3)
+      tzinfo (~> 2.0, >= 2.0.5)
+      uri (>= 0.13.1)
     ansi (1.5.0)
     ast (2.4.2)
+    base64 (0.3.0)
+    benchmark (0.5.0)
     benchmark-ips (2.14.0)
     bigdecimal (3.1.8)
     builder (3.3.0)
+    concurrent-ruby (1.3.6)
+    connection_pool (3.0.2)
+    csv (3.3.6)
     debug (1.9.2)
       irb (~> 1.10)
       reline (>= 0.3.8)
-    erubi (1.13.0)
+    drb (2.2.3)
+    erubi (1.13.1)
+    i18n (1.14.8)
+      concurrent-ruby (~> 1.0)
     io-console (0.7.2)
     irb (1.14.0)
       rdoc (>= 4.0.0)
@@ -26,7 +53,8 @@ GEM
     json (2.7.2)
     language_server-protocol (3.17.0.3)
     lint_roller (1.1.0)
-    minitest (5.24.1)
+    logger (1.7.0)
+    minitest (5.27.0)
     minitest-focus (1.4.0)
       minitest (>= 4, < 6)
     minitest-reporters (1.7.1)
@@ -34,25 +62,31 @@ GEM
       builder
       minitest (>= 5.0)
       ruby-progressbar
+    msgpack (1.8.4)
     netrc (0.11.0)
-    parallel (1.25.1)
+    parallel (1.28.0)
     parser (3.3.3.0)
       ast (~> 2.4.1)
       racc
-    prism (0.30.0)
+    prism (1.9.0)
     psych (5.1.2)
       stringio
     racc (1.8.0)
     rainbow (3.1.1)
     rake (13.2.1)
-    rbi (0.1.13)
-      prism (>= 0.18.0, < 1.0.0)
-      sorbet-runtime (>= 0.5.9204)
+    rbi (0.4.3)
+      prism (~> 1.0)
+      rbs (>= 4.0.1)
+    rbs (4.2.0)
+      logger
+      prism (>= 1.6.0)
+      tsort
     rdoc (6.7.0)
       psych (>= 4.0.0)
     regexp_parser (2.9.2)
     reline (0.5.9)
       io-console (~> 0.5)
+    require-hooks (0.5.1)
     rexml (3.3.1)
       strscan
     rubocop (1.64.1)
@@ -74,23 +108,31 @@ GEM
     rubocop-sorbet (0.7.8)
       rubocop (>= 0.90.0)
     ruby-progressbar (1.13.0)
-    sorbet (0.5.11475)
-      sorbet-static (= 0.5.11475)
+    rubydex (0.4.1-arm64-darwin)
+    rubydex (0.4.1-x86_64-linux)
+    securerandom (0.4.1)
+    sorbet (0.6.13543)
+      sorbet-static (= 0.6.13543)
     sorbet-result (1.1.0)
       sorbet-runtime (~> 0.5)
-    sorbet-runtime (0.5.11475)
-    sorbet-static (0.5.11475-universal-darwin)
-    sorbet-static (0.5.11475-x86_64-linux)
-    sorbet-static-and-runtime (0.5.11475)
-      sorbet (= 0.5.11475)
-      sorbet-runtime (= 0.5.11475)
+    sorbet-runtime (0.6.13543)
+    sorbet-static (0.6.13543-universal-darwin)
+    sorbet-static (0.6.13543-x86_64-linux)
+    sorbet-static-and-runtime (0.6.13543)
+      sorbet (= 0.6.13543)
+      sorbet-runtime (= 0.6.13543)
     sorbet-struct-comparable (1.3.0)
       sorbet-runtime (>= 0.5)
-    spoom (1.3.3)
+    spoom (1.8.10)
       erubi (>= 1.10.0)
       prism (>= 0.28.0)
+      rbi (>= 0.4.2)
+      rbs (>= 4.0.0.dev.5)
+      rexml (>= 3.2.6)
       sorbet-static-and-runtime (>= 0.5.10187)
       thor (>= 0.19.2)
+    sqlite3 (2.9.0-arm64-darwin)
+    sqlite3 (2.9.0-x86_64-linux-gnu)
     standard (1.39.1)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.0)
@@ -108,44 +150,53 @@ GEM
       rubocop-sorbet (~> 0.7.0)
     stringio (3.1.1)
     strscan (3.1.0)
-    tapioca (0.15.0)
+    tapioca (0.20.0)
+      benchmark
       bundler (>= 2.2.25)
       netrc (>= 0.11.0)
       parallel (>= 1.21.0)
-      rbi (>= 0.1.4, < 0.2)
-      sorbet-static-and-runtime (>= 0.5.11087)
-      spoom (>= 1.2.0)
+      rbi (>= 0.4.1)
+      require-hooks (>= 0.2.2)
+      rubydex (>= 0.1.0.beta10)
+      sorbet-static-and-runtime (>= 0.6.12698)
+      spoom (>= 1.7.16)
       thor (>= 1.2.0)
-      yard-sorbet
-    thor (1.3.1)
+      tsort
+    thor (1.5.0)
+    timeout (0.6.0)
+    tsort (0.2.0)
+    tzinfo (2.0.6)
+      concurrent-ruby (~> 1.0)
     unicode-display_width (2.5.0)
-    yard (0.9.36)
-    yard-sorbet (0.9.0)
-      sorbet-runtime
-      yard
+    uri (1.1.1)
     zeitwerk (2.6.16)
 
 PLATFORMS
   arm64-darwin-22
   arm64-darwin-23
   arm64-darwin-25
+  arm64-darwin-27
   x86_64-linux
 
 DEPENDENCIES
+  activerecord (>= 6.0)
   benchmark-ips
   bigdecimal
+  csv (~> 3.3)
   debug
   minitest
   minitest-focus
   minitest-reporters
+  msgpack (~> 1.7)
   rake
   sorbet
   sorbet-schema!
   sorbet-struct-comparable
+  sqlite3
   standard
   standard-performance
   standard-sorbet
-  tapioca
+  tapioca (~> 0.20)
 
 BUNDLED WITH
-   2.5.15
+   2.7.2

data/README.md

@@ -1,6 +1,6 @@
 # Sorbet Schema
 
-Extendable serialization and deserialization to various formats for Sorbet `T::Struct`s.
+Serialize and deserialize Sorbet `T::Struct` and `T::ImmutableStruct` values.
 
 ## Installation
 
@@ -14,11 +14,11 @@ If bundler is not being used to manage dependencies, install the gem by executin
 
 ## Usage
 
-Sorbet Schema is designed to be compatible with Sorbet's `T::Struct` class, and seeks to update many of the common pitfalls developers encountering when deserializing to and serializing from a `T::Struct`.
+Sorbet Schema supports both `T::Struct` and `T::ImmutableStruct`, and addresses common pitfalls when deserializing and serializing either kind of struct.
 
 ### Getting Started
 
-While you can directly define a `Typed::Schema` to be used for your serialization needs, you'll typically use the provided helper class method to generate a `Schema` from an existing `T::Struct`.
+While you can directly define a `Typed::Schema` to be used for your serialization needs, you'll typically use the provided helper class method to generate a `Schema` from an existing `T::Struct` or `T::ImmutableStruct`.
 
 ```ruby
 class Person < T::Struct
@@ -44,7 +44,7 @@ result = json_serializer.serialize(max)
 result.payload # == '{"name":"Max","age":29}'
 ```
 
-Alternatively, you can use the built-in helper methods added to `T::Struct`s to quickly use the built-in serializers.
+Alternatively, use the built-in helper methods on either struct class to quickly use the built-in serializers.
 
 ```ruby
 result = Person.deserialize_from(:json, '{"name":"Max","age":29}')
@@ -54,6 +54,8 @@ result = max.serialize_to(:json)
 result.payload # == '{"name":"Max","age":29}'
 ```
 
+`:hash`, `:json`, `:csv`, `:yml`, and `:msgpack` are all supported as the first argument to `deserialize_from`/`serialize_to` (and the equivalent `from_hash`/`from_json`/`from_csv`/`from_yml`/`from_msgpack` methods on `Typed::Schema`), corresponding to the built-in serializers below.
+
 Notice that both `deserialize` and `serialize` return `Typed::Result`s (from the [sorbet-result gem](https://github.com/maxveldink/sorbet-result)) that need to be checked for success or failure before being used. Check out that gem's README for more information on how to interact with `Result`s.
 
 One benefit of using `Result`s is we can add much more details information about why a format is unsuccessfully deserialized or serialized, to provide call sites with more information for error handling, messaging and formatting.
@@ -79,6 +81,29 @@ result = json_serializer.deserialize('{"name":"Max","age":"29"}')
 max = result.payload # == Person.new(name: "Max", age: 29)
 ```
 
+### Immutable structs
+
+Use `T::ImmutableStruct` when deserialization must create a frozen struct:
+
+```ruby
+class ImmutablePerson < T::ImmutableStruct
+  const :name, String
+  const :age, Integer
+end
+
+result = ImmutablePerson.deserialize_from(:json, '{"name":"Ada","age":37}')
+ada = result.payload
+ada.frozen? # => true
+
+ada.serialize_to(:json).payload # => '{"name":"Ada","age":37}'
+```
+
+The helper, serializer factory, and schema APIs retain the concrete immutable
+result type in Sorbet. Nested fields, array elements, and hash values declared
+as immutable structs are constructed as frozen instances as well. Sorbet does
+not recursively freeze strings, arrays, hashes, or mutable child structs.
+`T::InexactStruct` and its other subclasses remain unsupported.
+
 ### Rails Example
 
 Here's an extended example of how Sorbet Schema can be combined with a normal Rails request to easily convert between formats.
@@ -109,13 +134,15 @@ end
 
 These are the currently available serializers. For more information about implementing a custom one (or contributing one back!), see [Custom Coercers](#custom-coercers).
 
+`HashSerializer`, `JSONSerializer`, and `YMLSerializer` work out of the box with no extra dependencies. `CSVSerializer` and `MessagePackSerializer` require you to add the `csv` and `msgpack` gems, respectively, to your own Gemfile - they are not pulled in as runtime dependencies of `sorbet-schema` itself. Referencing `:csv`/`:msgpack` via `serializer`/`deserialize_from`/`serialize_to` without the gem installed raises a clear `ArgumentError` telling you which gem to add.
+
 #### JSONSerializer
 
 See [Getting Started](#getting-started) for more information on how to use the JSONSerializer.
 
 #### HashSerializer
 
-While not strictly serialization, converting `T::Struct`s to and from Ruby `Hash`es has traditionally had many pitfalls ([well-documented](https://sorbet.org/docs/tstruct#legacy-code-and-historical-context) in the Sorbet docs). The `Typed::HashSerializer` aims to address several common issues, while providing the same `Result` handling for invalid or missing data and coercion behavior.
+While not strictly serialization, converting structs to and from Ruby `Hash`es has traditionally had many pitfalls ([well-documented](https://sorbet.org/docs/tstruct#legacy-code-and-historical-context) in the Sorbet docs). The `Typed::HashSerializer` supports both struct classes with the same `Result` handling for invalid or missing data and coercion behavior.
 
 To use it, simply instantiate and use it like the `JSONSerializer`:
 
@@ -129,6 +156,129 @@ max = result.payload # == Person.new(name: "Max", age: 29)
 
 By default, the `HashSerializer` will _not_ serialize values when converting to a Hash. For instance, if a field is an `T::Enum` type, when it is serialized to a `Hash` the value will be the `Enum` and not the `String` representation. The `should_serialize_values` option can be passed during initialization to serialize the values when converting to the `Hash`.
 
+#### CSVSerializer
+
+Accepts and returns a CSV string representing a single record, with a header row followed by one data row:
+
+```ruby
+csv_serializer = Typed::CSVSerializer.new(schema: Person.schema)
+
+# Deserialize from target format
+result = csv_serializer.deserialize("name,age\nMax,29\n")
+max = result.payload # == Person.new(name: "Max", age: 29)
+
+# Serialize to target format
+result = csv_serializer.serialize(max)
+result.payload # == "name,age\nMax,29\n"
+```
+
+CSV is a flat, row-based format, so nested structs, `Hash`es, and `Array`s cannot be represented as their own columns. Rather than writing a lossy representation into a cell that can never be parsed back correctly, `CSVSerializer#serialize` returns a `Typed::SerializeError` naming the offending field(s). Prefer this serializer for schemas with scalar fields only, or use an `inline_serializer` (see [Inline Serializers](#inline-serializers)) to flatten a nested field into a scalar before serializing it to CSV.
+
+#### YMLSerializer
+
+Works just like the `JSONSerializer`, but with YAML strings:
+
+```ruby
+yml_serializer = Typed::YMLSerializer.new(schema: Person.schema)
+
+# Deserialize from target format
+result = yml_serializer.deserialize("---\nname: Max\nage: 29\n")
+max = result.payload # == Person.new(name: "Max", age: 29)
+
+# Serialize to target format
+result = yml_serializer.serialize(max)
+result.payload # == "---\nname: Max\nage: 29\n"
+```
+
+#### MessagePackSerializer
+
+Works just like the `JSONSerializer`, but with [MessagePack](https://msgpack.org/) binary-encoded strings, using the [`msgpack`](https://github.com/msgpack/msgpack-ruby) gem:
+
+```ruby
+message_pack_serializer = Typed::MessagePackSerializer.new(schema: Person.schema)
+
+# Deserialize from target format
+result = message_pack_serializer.deserialize(MessagePack.pack({"name" => "Max", "age" => 29}))
+max = result.payload # == Person.new(name: "Max", age: 29)
+
+# Serialize to target format
+result = message_pack_serializer.serialize(max)
+result.payload # == MessagePack.pack({"name" => "Max", "age" => 29})
+```
+
+Unlike `CSVSerializer`, MessagePack natively supports nested maps and arrays, so nested structs, `Hash`es, and `Array`s round-trip without any `inline_serializer` needed.
+
+#### ActiveRecordSerializer
+
+Requires the `activerecord` gem in your application's Gemfile. The gem is loaded lazily when a serializer is constructed; both `.serializer(:activerecord)` and direct construction raise a clear `ArgumentError` if it is unavailable. Loading or reflecting on the serializer class does not require ActiveRecord to be installed. The `Typed::ActiveRecordSerializer` converts between `ActiveRecord::Base` model instances and either supported struct class, matching fields by attribute name and mapping associated records through the model's declared associations. It requires a `model_class` option, in addition to `schema`, so it knows which `ActiveRecord::Base` subclass to deserialize from and serialize to:
+
+```ruby
+ar_serializer = Typed::ActiveRecordSerializer.new(schema: Person.schema, model_class: PersonModel)
+# Sorbet infers ActiveRecordSerializer[PersonModel, Person], retaining both result types.
+
+# Deserialize from target format
+result = ar_serializer.deserialize(PersonModel.new(name: "Max", age: 29))
+max = result.payload # == Person.new(name: "Max", age: 29)
+
+result = ar_serializer.serialize(max)
+result.payload # == PersonModel instance with name: "Max", age: 29
+```
+
+When serializing, only fields that map to a column (or to an association's declared foreign key) on `model_class` are assigned; the rest are ignored.
+
+Nested `belongs_to` associations are deserialized recursively to arbitrary depth, including immutable struct fields backed by a `belongs_to` association.
+
+Deserializing reads through the model's association readers, so it is subject to the same N+1 query behavior as any other Rails association access. Preloading with `includes` works transparently and is the recommended way to avoid a query per record per association when deserializing a collection:
+
+```ruby
+# 1 query for people + 1 query for locations, instead of 1 + N
+PersonModel.includes(:location).find_each do |person_model|
+  ar_serializer.deserialize(person_model)
+end
+```
+
+### Differing Serialized Keys
+
+Sorbet's `name:` prop option is honored, so a struct can keep snake_case props while reading and writing the key an external payload actually uses:
+
+```ruby
+class WebhookPayload < T::Struct
+  const :event_id, String, name: "eventId"
+  const :email_address, String, name: "emailAddress"
+end
+
+WebhookPayload.deserialize_from(:hash, {eventId: "evt-1", emailAddress: "user@example.com"})
+# <Typed::Success value=#<WebhookPayload event_id="evt-1", email_address="user@example.com">>
+
+WebhookPayload.new(event_id: "evt-1", email_address: "user@example.com").serialize_to(:hash)
+# {eventId: "evt-1", emailAddress: "user@example.com"}
+```
+
+`Typed::Field` exposes this as `serialized_name`, which defaults to `name` when the prop declares no `name:` option. Hand-built schemas can set it directly: `Typed::Field.new(name: :event_id, type: String, serialized_name: :eventId)`.
+
+### JSON Schema
+
+A schema can describe the hash it deserializes from as a JSON Schema (draft 2020-12), e.g. to hand it to an API client or an LLM tool definition:
+
+```ruby
+class Job < T::Struct
+  const :title, String, extra: {description: "Job title"}
+  const :start_date, T.nilable(Date)
+end
+
+Job.schema.to_json_schema
+# => {
+#   "type" => "object",
+#   "properties" => {
+#     "title" => {"type" => "string", "description" => "Job title"},
+#     "start_date" => {"type" => ["string", "null"], "format" => "date"}
+#   },
+#   "required" => ["title"]
+# }
+```
+
+Properties are keyed by the serialized name, values are in serialized form (a `T::Enum` as the `enum` of its serialized values, a `Date` as a string), and a field is required when it is neither nilable nor defaulted. Deserialization ignores unknown keys, so objects are open by default; `to_json_schema(additional_properties: false)` closes every struct object, e.g. to catch typos in a config file or for LLM structured-output APIs that require it. Nested `T::Struct` and `T::ImmutableStruct` values are described through their own `schema`; pass `struct_schema:` to `Typed::JSONSchema.generate` to resolve them differently. A type without a JSON form raises `Typed::JSONSchema::UnsupportedTypeError`.
+
 ### Customization
 
 From the get-go, Sorbet Schema is designed to be extensible to model more complex data validation requirements and many serialization formats. We try out best to include built-in, battle-tested coercers and serializers from real world use cases and would love to see/upstream any customizations that the community have found useful!
@@ -146,13 +296,13 @@ class DateCoercer < Coercer
   Target = type_member { {fixed: Date} }
 
   sig { override.params(type: T::Types::Base).returns(T::Boolean) }
-  def used_for_type?(type)
+  def self.used_for_type?(type)
     T::Utils.coerce(type) == T::Utils.coerce(Date)
   end
 
   sig { override.params(type: T::Types::Base, value: Value).returns(Result[Target, CoercionError]) }
   def coerce(type:, value:)
-    return Failure.new(CoercionError.new("Type must be a Date.")) unless used_for_type?(type)
+    return Failure.new(CoercionError.new("Type must be a Date.")) unless self.class.used_for_type?(type)
 
     return Success.new(value) if value.is_a?(Date)
 
@@ -186,11 +336,15 @@ The serializer can be used when creating a `Schema` and defining its `fields`, o
 ```ruby
 my_date_serializer = ->(date) { date.strftime("%Y/%m") }
 
-# use directly on a Schema
-Typed::Schema.new(
+# use directly on a Schema - `Typed::Schema` is generic over its target struct,
+# so prefer `from_struct`, which infers the type argument, over `Schema.new`
+Typed::Schema.from_struct(SchemaWithDateField).add_serializer(:date, my_date_serializer)
+
+# or, if you need custom `fields` up front, specify the type argument explicitly
+Typed::Schema[SchemaWithDateField].new(
   target: SchemaWithDateField,
   fields: [
-    Typed::Field.new(name: :date, type: Date, serializer: my_date_serializer)
+    Typed::Field.new(name: :date, type: Date, inline_serializer: my_date_serializer)
   ]
 )
 
@@ -208,10 +362,12 @@ require "json"
 class JSONSerializer < Serializer
   Input = type_member { {fixed: String} }
   Output = type_member { {fixed: String} }
+  StructT = type_member { {upper: T::InexactStruct} }
 
-  sig { override.params(source: Input).returns(Result[T::Struct, DeserializeError]) }
+  sig { override.params(source: Input).returns(Result[StructT, DeserializeError]) }
   def deserialize(source)
     parsed_json = JSON.parse(source)
+    return Failure.new(ParseError.new(format: :json)) unless parsed_json.is_a?(Hash)
 
     creation_params = schema.fields.each_with_object(T.let({}, Params)) do |field, hsh|
       hsh[field.name] = parsed_json[field.name.to_s]
@@ -222,7 +378,7 @@ class JSONSerializer < Serializer
     Failure.new(ParseError.new(format: :json))
   end
 
-  sig { override.params(struct: T::Struct).returns(Result[Output, SerializeError]) }
+  sig { override.params(struct: StructT).returns(Result[Output, SerializeError]) }
   def serialize(struct)
     return Failure.new(SerializeError.new("'#{struct.class}' cannot be serialized to target type of '#{schema.target}'.")) if struct.class != schema.target
 
@@ -231,7 +387,7 @@ class JSONSerializer < Serializer
 end
 ```
 
-Since `Serializer` is a generic class, we need to define our `Input` and `Output` types. For JSON, deserialization and serialization both use JSON strings, so these are both strings.
+Since `Serializer` is a generic class, we need to define our `Input`, `Output`, and `StructT` types. For JSON, deserialization and serialization both use JSON strings, so `Input`/`Output` are both `String`. `StructT` is the struct type the serializer round-trips to/from - it must always be re-declared as `type_member { {upper: T::InexactStruct} }` in the subclass (Sorbet requires each generic type member to be re-declared down the inheritance chain). Schemas themselves continue to accept only `T::Struct` and `T::ImmutableStruct` descendants, while using `StructT` in `deserialize`/`serialize` preserves the concrete type at every deserialize entry point.
 
 Next, the `deserialize` and `serialize` methods must be implemented. Notice that both of these return `Result`s.
 

data/Rakefile

@@ -4,6 +4,7 @@ require "bundler/gem_tasks"
 require "minitest/test_task"
 
 Minitest::TestTask.create do |t|
+  t.framework = %(require "test_helper")
   t.test_globs = ["test/**/*_test.rb"]
 end
 

data/benchmarks/helpers.rb

@@ -236,4 +236,3 @@ module BenchmarkHelpers
     }
   end
 end
-

data/benchmarks/many_fields_serialization.rb

@@ -24,4 +24,3 @@ Benchmark.ips do |x|
 
   x.compare!
 end
-

data/benchmarks/simple_serialization.rb

@@ -24,4 +24,3 @@ Benchmark.ips do |x|
 
   x.compare!
 end
-

data/lib/sorbet-schema/serialize_value.rb

@@ -9,7 +9,7 @@ class SerializeValue
       HashTransformer.serialize_values(value)
     elsif value.is_a?(Array)
       value.map { |item| serialize(item) }
-    elsif value.is_a?(T::Struct)
+    elsif value.is_a?(T::Struct) || value.is_a?(T::ImmutableStruct)
       value.serialize_to(:hash, options: {should_serialize_values: true}).payload_or(value)
     elsif value.respond_to?(:serialize)
       value.serialize