sorbet-schema 0.10.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b0c3bb89fee8f842f919e0cf1f53d8f97fb12e4464effb88c7e821134c531a1f
-  data.tar.gz: a78684855bb1bd76e6688b0daa04f026fcb55c23fd2f354daaea8e7a2f0f5cd3
+  metadata.gz: 8ae3eaa249b0881483d4fe8edd8c295ada54733bb78d106525767506e83f20bb
+  data.tar.gz: f36595f7d0831a83234453acccb941dc3bcff703562a87a52dbb1b2dbfd0dce0
 SHA512:
-  metadata.gz: 28656d268e7861ae7e069ff30b024a2d063ee33f5824ca9bc1319cbe91555b2e80b402ee2438b975d299c58f624c4e8afba1ba8649a62c8d05a6efc3fa10fbac
-  data.tar.gz: 9faf4f7458d56d9a66645d1d25aa4d70a83eea9abba3e1021a5fe58a5978d0c309a987d20e5af1dfc538f5d0a550f40ed1afa6a35c39ff2e5173a9b44a6cd118
+  metadata.gz: 1ff4723d4f1a749d3d2ee7255b4c024c783b10acf7701240889d9bc25b3682df9c308a6a525c6a055bb8b4a627ce8214d45dfda6c359b064f90beb43693fe5bc
+  data.tar.gz: f3352237a1b10e95747c313c4937869c2baac94e45cedd1eb29c3b550d5a7c41b731b07505fbb61d7645e7d46efec986d95a95ed2d3472bf9e65cac9403340bf

data/AGENTS.md

@@ -4,7 +4,8 @@ This file is the project's committed home for project-intrinsic agent knowledge:
 
 - 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 (`CSVSerializer`, `MessagePackSerializer`, `ActiveRecordSerializer`) treat their backing gem as optional: no top-level `require`, gem is `add_development_dependency` only (not `add_runtime_dependency`), the `require`/gem-presence check happens lazily in `initialize` with a clear `ArgumentError` on failure, and `T::Struct.serializer`'s factory (`lib/sorbet-schema/t/struct.rb`) mirrors that same guard via `defined?(...)`. Follow this pattern for any new serializer/coercer with a non-stdlib dependency; see `lib/typed/csv_serializer.rb` for the exact shape.
+- 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

data/CHANGELOG.md

@@ -4,6 +4,32 @@ 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)
 
 

data/Gemfile

@@ -12,7 +12,7 @@ group :development do
   gem "standard-performance"
   gem "standard-sorbet"
   gem "sorbet"
-  gem "tapioca", "~> 0.16.6", require: false
+  gem "tapioca", "~> 0.20", require: false
 end
 
 group :development, :test do

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    sorbet-schema (0.10.0)
+    sorbet-schema (0.11.0)
       sorbet-result (~> 1.1)
       sorbet-runtime (~> 0.5)
       sorbet-struct-comparable (~> 1.3)
@@ -32,6 +32,7 @@ GEM
     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)
@@ -42,7 +43,7 @@ GEM
       irb (~> 1.10)
       reline (>= 0.3.8)
     drb (2.2.3)
-    erubi (1.13.0)
+    erubi (1.13.1)
     i18n (1.14.8)
       concurrent-ruby (~> 1.0)
     io-console (0.7.2)
@@ -53,7 +54,7 @@ GEM
     language_server-protocol (3.17.0.3)
     lint_roller (1.1.0)
     logger (1.7.0)
-    minitest (5.24.1)
+    minitest (5.27.0)
     minitest-focus (1.4.0)
       minitest (>= 4, < 6)
     minitest-reporters (1.7.1)
@@ -63,26 +64,29 @@ GEM
       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 (1.6.0)
+    prism (1.9.0)
     psych (5.1.2)
       stringio
     racc (1.8.0)
     rainbow (3.1.1)
     rake (13.2.1)
-    rbi (0.3.7)
+    rbi (0.4.3)
       prism (~> 1.0)
-      rbs (>= 3.4.4)
-    rbs (3.9.5)
+      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)
@@ -104,22 +108,27 @@ GEM
     rubocop-sorbet (0.7.8)
       rubocop (>= 0.90.0)
     ruby-progressbar (1.13.0)
+    rubydex (0.4.1-arm64-darwin)
+    rubydex (0.4.1-x86_64-linux)
     securerandom (0.4.1)
-    sorbet (0.5.11475)
-      sorbet-static (= 0.5.11475)
+    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)
@@ -141,25 +150,25 @@ GEM
       rubocop-sorbet (~> 0.7.0)
     stringio (3.1.1)
     strscan (3.1.0)
-    tapioca (0.16.6)
+    tapioca (0.20.0)
+      benchmark
       bundler (>= 2.2.25)
       netrc (>= 0.11.0)
       parallel (>= 1.21.0)
-      rbi (~> 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)
     uri (1.1.1)
-    yard (0.9.36)
-    yard-sorbet (0.9.0)
-      sorbet-runtime
-      yard
     zeitwerk (2.6.16)
 
 PLATFORMS
@@ -187,7 +196,7 @@ DEPENDENCIES
   standard
   standard-performance
   standard-sorbet
-  tapioca (~> 0.16.6)
+  tapioca (~> 0.20)
 
 BUNDLED WITH
    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}')
@@ -81,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.
@@ -119,7 +142,7 @@ See [Getting Started](#getting-started) for more information on how to use the J
 
 #### 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`:
 
@@ -149,7 +172,7 @@ result = csv_serializer.serialize(max)
 result.payload # == "name,age\nMax,29\n"
 ```
 
-CSV is a flat, row-based format, so nested `T::Struct`s, `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) when a struct has one. 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.
+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
 
@@ -183,14 +206,15 @@ 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 `T::Struct`s, `Hash`es, and `Array`s round-trip without any `inline_serializer` needed.
+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 to be available. This is only checked when going through `.serializer(:activerecord)`, which raises an `ArgumentError` if the gem isn't loaded; calling `Typed::ActiveRecordSerializer.new` directly without ActiveRecord loaded instead raises a `NameError`, since the class itself references the `ActiveRecord` constant. The `Typed::ActiveRecordSerializer` converts between `ActiveRecord::Base` model instances and `T::Struct`s, 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:
+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))
@@ -202,7 +226,7 @@ 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, so a `T::Struct` field whose type is itself a `T::Struct` backed by a `belongs_to` association will have its own nested associations resolved too.
+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:
 
@@ -213,6 +237,48 @@ PersonModel.includes(:location).find_each do |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!
@@ -230,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)
 
@@ -270,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)
   ]
 )
 
@@ -292,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]
@@ -306,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
 
@@ -315,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/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

data/lib/sorbet-schema/t/struct.rb

@@ -1,40 +1,59 @@
 # typed: true
 
 module T
-  class Struct
-    class << self
-      def schema
-        Typed::Schema.from_struct(self)
-      end
-
-      def serializer(type, options: {})
-        case type
-        when :hash
-          Typed::HashSerializer.new(**T.unsafe({schema:, **options}))
-        when :json
-          Typed::JSONSerializer.new(schema:)
-        when :csv
-          Typed::CSVSerializer.new(schema:)
-        when :yml
-          Typed::YMLSerializer.new(schema:)
-        when :msgpack
-          Typed::MessagePackSerializer.new(schema:)
-        when :activerecord
-          raise ArgumentError, "activerecord gem is required for ActiveRecord serialization" unless defined?(ActiveRecord)
+  module StructClassMethods
+    def schema
+      T.bind(self, Typed::StructClass)
+      Typed::Schema.from_struct(self)
+    end
 
-          Typed::ActiveRecordSerializer.new(**T.unsafe({schema:, **options}))
-        else
-          raise ArgumentError, "unknown serializer for #{type}"
+    def serializer(type, options: {})
+      T.bind(self, Typed::StructClass)
+      # The RBI shim promises a serializer parameterized by the attached class,
+      # while this case has different serializer subclasses on each branch.
+      T.unsafe(case type
+      when :hash
+        Typed::HashSerializer.new(**T.unsafe({schema:, **options}))
+      when :json
+        Typed::JSONSerializer.new(schema:)
+      when :csv
+        Typed::CSVSerializer.new(schema:)
+      when :yml
+        Typed::YMLSerializer.new(schema:)
+      when :msgpack
+        Typed::MessagePackSerializer.new(schema:)
+      when :activerecord
+        begin
+          require "active_record" unless defined?(ActiveRecord::Base)
+        rescue LoadError
+          raise ArgumentError, "activerecord gem is required for ActiveRecord serialization - add it to your Gemfile"
         end
-      end
 
-      def deserialize_from(serializer_type, source, options: {})
-        T.unsafe(serializer(serializer_type, options:).deserialize(source))
-      end
+        Typed::ActiveRecordSerializer.new(**T.unsafe({schema:, **options}))
+      else
+        raise ArgumentError, "unknown serializer for #{type}"
+      end)
     end
 
+    def deserialize_from(serializer_type, source, options: {})
+      T.unsafe(serializer(serializer_type, options:).deserialize(source))
+    end
+  end
+
+  module StructInstanceMethods
     def serialize_to(serializer_type, options: {})
-      self.class.serializer(serializer_type, options:).serialize(self)
+      T.bind(self, Typed::StructValue)
+      T.unsafe(self.class.serializer(serializer_type, options:)).serialize(self)
     end
   end
+
+  class Struct
+    extend StructClassMethods
+    include StructInstanceMethods
+  end
+
+  class ImmutableStruct
+    extend StructClassMethods
+    include StructInstanceMethods
+  end
 end

data/lib/sorbet-schema/version.rb

@@ -1,5 +1,5 @@
 # typed: strict
 
 module SorbetSchema
-  VERSION = "0.10.0"
+  VERSION = "0.11.0"
 end

data/lib/sorbet-schema.rb

@@ -12,6 +12,7 @@ loader.push_dir(__dir__.to_s)
 loader.ignore(__FILE__)
 loader.ignore("#{__dir__}/sorbet-schema/**/*.rb")
 loader.inflector.inflect(
+  "json_schema" => "JSONSchema",
   "json_serializer" => "JSONSerializer",
   "csv_serializer" => "CSVSerializer",
   "yml_serializer" => "YMLSerializer"
@@ -33,4 +34,6 @@ require_relative "sorbet-schema/t/struct"
 # Sorbet-aware namespace to super-charge your projects
 module Typed
   Value = T.type_alias { T.untyped }
+  StructValue = T.type_alias { T.any(T::Struct, T::ImmutableStruct) }
+  StructClass = T.type_alias { T.any(T.class_of(T::Struct), T.class_of(T::ImmutableStruct)) }
 end