Title: Feature Proposal: Opt-in Sorbet `T::Struct` Generation from Schema Components · Issue #61 · openapi-ruby/openapi-ruby · GitHub
Open Graph Title: Feature Proposal: Opt-in Sorbet `T::Struct` Generation from Schema Components · Issue #61 · openapi-ruby/openapi-ruby
X Title: Feature Proposal: Opt-in Sorbet `T::Struct` Generation from Schema Components · Issue #61 · openapi-ruby/openapi-ruby
Description: Problem Schema components defined with OpenapiRuby::Components::Base are documentation-only at runtime. Projects using Sorbet for type checking face a duplication problem: every request/response schema that needs typed access in applicat...
Open Graph Description: Problem Schema components defined with OpenapiRuby::Components::Base are documentation-only at runtime. Projects using Sorbet for type checking face a duplication problem: every request/response sc...
X Description: Problem Schema components defined with OpenapiRuby::Components::Base are documentation-only at runtime. Projects using Sorbet for type checking face a duplication problem: every request/response sc...
Opengraph URL: https://github.com/openapi-ruby/openapi-ruby/issues/61
X: @github
Domain: github.com
{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Feature Proposal: Opt-in Sorbet `T::Struct` Generation from Schema Components","articleBody":"## Problem\n\nSchema components defined with `OpenapiRuby::Components::Base` are documentation-only at runtime. Projects using [Sorbet](https://sorbet.org/) for type checking face a duplication problem: every request/response schema that needs typed access in application code must be redefined as a separate `T::Struct`, keeping two sources of truth in sync manually.\n\nThe gem already bridges this gap for strong params — `permitted_params` reads the `schema()` DSL and derives a permit list. The same approach could eliminate the parallel `T::Struct` boilerplate.\n\n## Proposed Solution\n\nAn opt-in mixin (e.g. `OpenapiRuby::Components::TypedParams`) that reads the parsed `schema(...)` definition and auto-generates `T::Struct` `const` declarations on the including class. Schema components that include this mixin serve double duty: OpenAPI docs **and** a typed runtime struct.\n\n### Example usage\n\n```ruby\nclass Schemas::UserInput\n include OpenapiRuby::Components::Base\n include OpenapiRuby::Components::TypedParams # opt-in\n\n schema(\n type: :object,\n required: %w[name email],\n properties: {\n name: { type: :string },\n email: { type: :string },\n bio: { type: :string, nullable: true }\n }\n )\nend\n\n# After including TypedParams, the class behaves as a T::Struct:\nuser = Schemas::UserInput.new(name: \"Jane\", email: \"jane@example.com\")\nuser.name # => \"Jane\" (typed as String)\nuser.bio # => nil (typed as T.nilable(String))\n```\n\n## Implementation Sketch\n\n### 1. Type mapping\n\nOpenAPI type → Sorbet type:\n\n| OpenAPI | Sorbet |\n| --- | --- |\n| `string` | `String` |\n| `integer` | `Integer` |\n| `number` | `Float` |\n| `boolean` | `T::Boolean` |\n| `array` with `items` | `T::Array[\u003citem type>]` |\n| `object` (nested) | resolved Ruby class if `$ref`, or `T::Hash[String, T.untyped]` |\n| `$ref` to another component | the referenced Ruby class |\n| `nullable: true` or not in `required` | `T.nilable(...)` |\n\n### 2. `$ref` resolution\n\nRefs like `\"#/components/schemas/UserInput\"` would resolve to the corresponding Ruby class (e.g. `Schemas::UserInput`) by stripping the path prefix and calling `Object.const_get`. Referenced schemas would also need to include `TypedParams` to be instantiable as structs.\n\n### 3. Struct generation\n\nThe mixin uses `const` (immutable) declarations, matching the read-only nature of request params:\n\n```ruby\n# auto-generated equivalent of the schema above:\nconst :name, String\nconst :email, String\nconst :bio, T.nilable(String)\n```\n\n### 4. Tapioca DSL compiler\n\nSince Sorbet cannot see metaprogrammed `const` declarations, a companion [Tapioca](https://github.com/Shopify/tapioca) DSL compiler would emit RBI files for all schema classes that include `TypedParams`:\n\n```bash\nbin/tapioca dsl Schemas::UserInput\n```\n\n## Packaging\n\nSorbet must **not** become a dependency of `openapi-ruby` itself — this feature is strictly opt-in for teams that already use Sorbet. Two packaging options:\n\n- **Optional require path** — ship the mixin inside the gem behind `require \"openapi_ruby/sorbet\"`, which raises a clear error if `sorbet-runtime` is not installed. Zero impact on projects that never require it.\n- **Companion gem** — a separate `openapi-ruby-sorbet` gem that declares `sorbet-runtime` as its own dependency. Cleaner dependency boundary, but one more gem to manage.\n\n## Design Questions\n\n1. **Inheritance model** — Should `TypedParams` make the class inherit from `T::Struct` automatically, or require the user to set up inheritance explicitly? Auto-inheriting is more ergonomic but changes the class hierarchy.\n2. **Enum constraints** — Should enum values be validated on struct construction, or is that left to the runtime validation middleware?\n3. **Nested arrays of `$ref`** — e.g. `type: :array, items: { \"$ref\" => \"...\" }` — should element types resolve through the same ref-resolution path?\n4. **Optional require vs. companion gem** — Which packaging approach is preferred? (Either way, Sorbet remains a user-side opt-in, never a transitive dependency of `openapi-ruby`.)\n\n## Prior Art\n\n- `permitted_params` already reads `schema()` and generates runtime artifacts (strong params permit lists), establishing this pattern within the gem\n- [Sorbet's `T::Struct`](https://sorbet.org/docs/tstruct) for typed value objects\n- [Tapioca DSL compilers](https://github.com/Shopify/tapioca#writing-custom-dsl-compilers) for making metaprogrammed methods visible to Sorbet","author":{"url":"https://github.com/marshallshen","@type":"Person","name":"marshallshen"},"datePublished":"2026-10-29T20:41:24Z","url":"https://github.com/openapi-ruby/openapi-ruby/issues/61"}
| react-profiling | 0 |
| react-import-map | react,react-dom,react-dom/client,react-dom/profiling,react-is,react/compiler-runtime,react/jsx-dev-runtime,react/jsx-runtime,scheduler@b8488ee2c322 |
| route-pattern | /_view_fragments/issues/show/:user_id/:repository/:id/issue_layout(.:format) |
| route-controller | voltron_issues_fragments |
| route-action | issue_layout |
| fetch-nonce | v2:a877ae24-c41a-4ee2-56a5-7d71de99c04e |
| current-catalog-service-hash | 81bb79d38c15960b92d99bca9288a9108c7a47b18f2423d0f6438c5b7bcd2114 |
| request-id | 9D8A:2DBB21:170B418:1EAE823:6B0142E6 |
| html-safe-nonce | 1a82e1ffb2c0f0b79c9eab2e6d49cdd5bf9f4f1a4095338a603545f11a640e57 |
| visitor-payload | eyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiI5RDhBOjJEQkIyMToxNzBCNDE4OjFFQUU4MjM6NkIwMTQyRTYiLCJ2aXNpdG9yX2lkIjoiNTc0MTkwMzkxNTM4NTk2MzIzOCIsInJlZ2lvbl9lZGdlIjoiaWFkIiwicmVnaW9uX3JlbmRlciI6ImlhZCJ9 |
| visitor-hmac | cee8cf8b89aaf51e4d8ce8628f3876c50396c5baf5122de4b315fd4d0af5bf26 |
| hovercard-subject-tag | issue:6108114535 |
| github-keyboard-shortcuts | repository,issues,copilot |
| google-site-verification | Apib7-x98H0j5cPqHWwSMm6dNU4GmODRoqxLiDzdx9I |
| octolytics-url | https://collector.github.com/github/collect |
| analytics-location | / |
| fb:app_id | 1401488693436528 |
| apple-itunes-app | app-id=1477376905, app-argument=https://github.com/_view_fragments/issues/show/openapi-ruby/openapi-ruby/61/issue_layout |
| twitter:image | https://opengraph.githubassets.com/15384d6b22483c5858af7ef31cdc4895296abbb0965916267e638c151f148566/openapi-ruby/openapi-ruby/issues/61 |
| twitter:card | summary_large_image |
| og:image | https://opengraph.githubassets.com/15384d6b22483c5858af7ef31cdc4895296abbb0965916267e638c151f148566/openapi-ruby/openapi-ruby/issues/61 |
| og:image:alt | Problem Schema components defined with OpenapiRuby::Components::Base are documentation-only at runtime. Projects using Sorbet for type checking face a duplication problem: every request/response sc... |
| og:image:width | 1200 |
| og:image:height | 600 |
| og:site_name | GitHub |
| og:type | object |
| og:author:username | marshallshen |
| hostname | github.com |
| expected-hostname | github.com |
| None | cc5dfdd32f62ebd3223cab3af3aa2b268d3605218237326a48a99d1efd89495c |
| turbo-cache-control | no-preview |
| go-import | github.com/openapi-ruby/openapi-ruby git https://github.com/openapi-ruby/openapi-ruby.git |
| octolytics-dimension-user_id | 276587259 |
| octolytics-dimension-user_login | openapi-ruby |
| octolytics-dimension-repository_id | 1211860664 |
| octolytics-dimension-repository_nwo | openapi-ruby/openapi-ruby |
| octolytics-dimension-repository_public | true |
| octolytics-dimension-repository_is_fork | false |
| octolytics-dimension-repository_network_root_id | 1211860664 |
| octolytics-dimension-repository_network_root_nwo | openapi-ruby/openapi-ruby |
| turbo-body-classes | logged-out env-production page-responsive |
| disable-turbo | false |
| browser-stats-url | https://api.github.com/_private/browser/stats |
| browser-errors-url | https://api.github.com/_private/browser/errors |
| release | 8c77c9e8439031ad54c75a250694842892f693e1 |
| ui-target | full |
| theme-color | #1e2327 |
| color-scheme | light dark |
| react-app-name | issues |
Links:
Viewport: width=device-width