StructuredParams

StructuredParams is a Ruby gem that provides type-safe parameter validation and casting for Rails applications. It extends ActiveModel's type system to handle nested objects and arrays with automatic Strong Parameters integration.

English | 日本語

Features

• Type-safe parameter validation using ActiveModel::Type
• Nested object support with automatic casting
• Array handling for both primitive types and nested objects
• Strong Parameters integration with automatic permit lists
• ActiveModel compatibility with validations and serialization
• Enhanced error handling with flat and structured formats
• RBS type definitions for better development experience

Quick Start

# 1. Install the gem
gem 'structured_params'

# 2. Register types in initializer
StructuredParams.register_types

# 3. Define parameter classes
class UserParams < StructuredParams::Params
  attribute :name, :string
  attribute :age, :integer
  attribute :address, :object, value_class: AddressParams
  attribute :hobbies, :array, value_class: HobbyParams
  
  validates :name, presence: true
  validates :age, numericality: { greater_than: 0 }
end

# 4. Use in controllers
def create
  user_params = UserParams.new(params[:user])
  if user_params.valid?
    User.create!(user_params.attributes)
  else
    render json: { errors: user_params.errors.to_hash(false, structured: true) }
  end
end

Documentation

• Installation and Setup - Getting started with StructuredParams
• Basic Usage - Parameter classes, nested objects, and arrays
• Validation - Using ActiveModel validations with nested structures
• Strong Parameters - Automatic permit list generation
• Error Handling - Flat and structured error formats
• Serialization - Converting parameters to hashes and JSON
• Gem Comparison - Comparison with typed_params, dry-validation, and reform

Example

class AddressParams < StructuredParams::Params
  attribute :street, :string
  attribute :city, :string
  attribute :postal_code, :string
  
  validates :street, :city, :postal_code, presence: true
end

class UserParams < StructuredParams::Params
  attribute :name, :string
  attribute :email, :string
  attribute :address, :object, value_class: AddressParams
  
  validates :name, presence: true
  validates :email, format: { with: URI::MailTo::EMAIL_REGEXP }
end

# Usage
params = {
  name: "John Doe",
  email: "john@example.com",
  address: { street: "123 Main St", city: "New York", postal_code: "10001" }
}

user_params = UserParams.new(params)
user_params.valid? # => true
user_params.address.city # => "New York"
user_params.attributes # => Hash ready for ActiveRecord

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/Syati/structured_params.

License

The gem is available as open source under the terms of the MIT License.