basic-usage.md

Basic Usage

Define a parameter class by inheriting from StructuredParams::Params. Declare typed attributes with attribute and use standard ActiveModel validations.

Table of Contents

• Basic Parameter Class
• Nested Objects
• Arrays
  • Array of Primitive Types
  • Array of Nested Objects

Basic Parameter Class

class UserParams < StructuredParams::Params
  attribute :name, :string
  attribute :age, :integer
  attribute :email, :string
  
  validates :name, presence: true
  validates :email, format: { with: URI::MailTo::EMAIL_REGEXP }
end

# Usage in controller
def create
  user_params = UserParams.new(params[:user])
  if user_params.valid?
    User.create!(user_params.attributes)
  else
    render json: { errors: user_params.errors }
  end
end

Nested Objects

Use attribute :name, :object, value_class: SomeParams to define a nested object.

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

class UserParams < StructuredParams::Params
  attribute :name, :string
  attribute :address, :object, value_class: AddressParams
end

# Usage
params = {
  name: "John Doe",
  address: {
    street: "123 Main St",
    city: "New York",
    postal_code: "10001"
  }
}

user_params = UserParams.new(params)
user_params.address        # => AddressParams instance
user_params.address.city   # => "New York"

Arrays

Use attribute :name, :array, ... to define an array attribute. Specify value_type for scalar elements or value_class for object elements.

Array of Primitive Types

Use value_type for arrays of scalar values.

class UserParams < StructuredParams::Params
  attribute :tags,   :array, value_type: :string
  attribute :scores, :array, value_type: :integer
end

# Usage
params = {
  tags:   ["ruby", "rails", "programming"],
  scores: [85, 92, 78]
}

user_params = UserParams.new(params)
user_params.tags   # => ["ruby", "rails", "programming"]
user_params.scores # => [85, 92, 78]

Array of Nested Objects

Use value_class for arrays of objects.

class HobbyParams < StructuredParams::Params
  attribute :name,  :string
  attribute :level, :string
end

class UserParams < StructuredParams::Params
  attribute :name,    :string
  attribute :hobbies, :array, value_class: HobbyParams
end

# Usage
params = {
  name: "Alice",
  hobbies: [
    { name: "Photography", level: "beginner" },
    { name: "Cooking",     level: "intermediate" }
  ]
}

user_params = UserParams.new(params)
user_params.hobbies              # => [HobbyParams, HobbyParams]
user_params.hobbies.first.name   # => "Photography"