End-to-end type system for Rails
Define types once in Ruby DSL. Generate TypeScript interfaces and Zod schemas for your frontend.
Documentation · Quick Start · GitHub
Zodra is a full API framework for Rails that bridges the gap between backend and frontend type safety. You define your types, contracts, and API structure in a Ruby DSL — Zodra handles validation, serialization, routing, and code generation.
One definition, both sides:
Ruby DSL → TypeScript interfaces + Zod schemas
→ Params validation + Response serialization
→ Resource routing + Controller helpers
- Type DSL — objects, enums, unions with full attribute support (optional, nullable, defaults, constraints)
- Type Composition — derive types with
from:, pick:, omit:, partial: (like TypeScript utility types)
- Contracts — define params and responses per action, decoupled from routing
- Resource Routing —
Zodra.api maps contracts to RESTful routes with nested resources and custom actions
- Params Validation — strict by default, coerces and validates incoming params against contract schemas
- Response Serialization — consistent
{ data: ... } / { data: [...], meta: ... } envelope
- TypeScript Export — generates
.ts interfaces from your type definitions
- Zod Export — generates
.ts schemas with constraints (z.string().min(1), z.number().int())
- Controller Mixin —
include Zodra::Controller for zodra_params, zodra_respond, error handling
- OpenAPI 3.1 — auto-generated specs from your contracts with
rake zodra:openapi
- Swagger UI — built-in interactive API docs at
/docs with mount Zodra::Swagger
- Rails Native — Railtie, rake tasks, works with Zeitwerk and standard Rails conventions
Add to your Gemfile:
# app/types/product.rb
Zodra.type :product do
uuid :id
string :name
string :sku
decimal :price
integer :stock
boolean :published
end
# app/contracts/products.rb
Zodra.contract :products do
action :index do
response :product, collection: true
end
action :show do
params do
uuid :id
end
response :product
end
action :create do
params do
string :name, min: 1
string :sku, min: 1
decimal :price, min: 0
integer :stock, min: 0
boolean :published, default: false
end
response :product
end
action :update do
params do
uuid :id
string? :name, min: 1
string? :sku, min: 1
decimal? :price, min: 0
integer? :stock, min: 0
boolean? :published
end
response :product
end
action :destroy do
params do
uuid :id
end
end
end# config/apis/v1.rb
Zodra.api "/api/v1" do
resources :products
end
# config/routes.rb
Rails.application.routes.draw do
mount Zodra::Swagger => '/docs' # Swagger UI at /docs
zodra_routes
end
# app/controllers/api/v1/products_controller.rb
module Api
module V1
class ProductsController < ApplicationController
include Zodra::Controller
zodra_contract :products
def index
products = Product.all
zodra_respond_collection(products)
end
def show
product = Product.find(zodra_params[:id])
zodra_respond(product)
end
def create
product = Product.create!(zodra_params)
zodra_respond(product, status: :created)
end
def update
product = Product.find(zodra_params[:id])
product.update!(zodra_params.except(:id))
zodra_respond(product)
end
def destroy
product = Product.find(zodra_params[:id])
product.destroy!
head :no_content
end
end
end
end6. Export to TypeScript + Zod
bin/rails zodra:export
# Generated app/javascript/types/schemas.ts
# Generated app/javascript/types/types.ts
Generated TypeScript:
export interface Product {
id: string;
name: string;
sku: string;
price: number;
stock: number;
published: boolean;
}Generated Zod:
import { z } from 'zod';
export const ProductSchema = z.object({
id: z.uuid(),
name: z.string(),
sku: z.string(),
price: z.number(),
stock: z.number().int(),
published: z.boolean(),
});
| DSL |
TypeScript |
Zod |
string |
string |
z.string() |
integer |
number |
z.number().int() |
decimal |
number |
z.number() |
boolean |
boolean |
z.boolean() |
uuid |
string |
z.uuid() |
date |
string |
z.iso.date() |
datetime |
string |
z.iso.datetime() |
string? :nickname # optional
string :name, nullable: true # nullable
string :role, default: "user"
string :name, min: 1, max: 100
Zodra.enum :status, values: %w[draft published archived]
Zodra.union :payment, discriminator: :type do
variant :card do
string :last_four
end
variant :bank_transfer do
string :iban
end
endZodra.type :order do
uuid :id
reference :customer # references Zodra.type :customer
array :items, of: :line_item # array of Zodra.type :line_item
end
Derive new types from existing ones — like TypeScript's Pick, Omit, and Partial:
Zodra.type :create_product_params, from: :product, omit: [:id]
Zodra.type :update_product_params, from: :product, omit: [:id], partial: true
Zodra.type :product_summary, from: :product, pick: [:id, :name, :price]
Blocks replace the default value extraction in ResponseSerializer. Use them when
the attribute value comes from a different source than the object's method:
Zodra.type :clock_in_day do
integer :id
string :date do |day|
UiDate.format(day.date)
end
boolean :can_edit do |day, context|
context[:ability].can?(:edit, day)
end
reference :staff_member, to: :staff do |day|
StaffPresenter.new(day.staff_member)
end
endPass context through ResponseSerializer.call(object, definition, context: { ability: current_ability }).
# config/initializers/zodra.rb
Zodra.configure do |config|
config.output_path = "app/javascript/types" # where to write generated files
config.key_format = :camel # :camel, :pascal, or :keep
config.zod_import = "zod" # import path for Zod
config.strict_params = true # reject unknown params
config.strict_serialization = true # raise on missing required attributes
# OpenAPI / Swagger UI
config.openapi_title = "My API"
config.openapi_version = "1.0.0"
config.openapi_description = "API documentation"
end
bin/rails zodra:export # generate both TypeScript + Zod
bin/rails zodra:export:typescript # generate only TypeScript interfaces
bin/rails zodra:export:zod # generate only Zod schemas
bin/rails zodra:openapi # generate OpenAPI 3.1 JSON specs
zodra/
├── gem/ # Ruby gem (zodra)
│ ├── lib/zodra/ # Core library
│ └── spec/ # RSpec tests
├── js/ # JavaScript packages (pnpm workspace)
│ └── packages/
│ ├── client/ # @zodra/client
│ └── vscode/ # VS Code extension
├── website/ # Next.js documentation (zodra.dev)
├── example/ # Full Rails API app (smoke test)
└── .github/workflows/ # CI (Ruby 3.2/3.3/3.4 + Node 22)
- Ruby >= 3.2
- Node.js >= 22
- pnpm >= 10
cd gem
bundle install
bundle exec rspec # run tests
bundle exec rubocop # lint
cd js
pnpm install
pnpm test # run tests
pnpm typecheck # type check
cd example
bundle install
bin/rails db:create db:migrate db:seed
bin/rails server
# CRUD: curl http://localhost:3000/api/v1/products
MIT
