validate-params

Use this skill when validating and coercing request parameters in Hanami 2.x Actions.

Core principle: Params are validated at the boundary. Invalid input never reaches business logic.

Validation Workflow

1. Define params block inside the Action class with required/optional fields and types
2. Hanami validates automatically — no manual trigger needed; invalid input halts with 422
3. Check request.params.errors — inspect or return errors if you need custom responses
4. Proceed only if valid — call business logic after confirming no errors

def handle(request, response)
  # Step 3: check errors (optional — Hanami already halted if invalid)
  if request.params.errors.any?
    response.status = 422
    response.body = { errors: request.params.errors.to_h }.to_json
    return
  end

  # Step 4: proceed with validated, coerced params
  result = user_repo.create(request.params[:user])
  response.status = 201
  response.body = result.to_json
end

Quick Reference (Syntax Cheat Sheet)

Core Rules

1. Define params inside the Action class:

   # app/actions/users/create.rb
   # frozen_string_literal: true
   
   module MyApp
     module Actions
       module Users
         class Create < MyApp::Action
           include Deps["repos.user_repo"]
   
           params do
             required(:user).hash do
               required(:email).value(:string, format?: /\A.+@.+\z/)
               required(:first_name).value(:string, min_size?: 1)
               required(:last_name).value(:string, min_size?: 1)
               optional(:bio).value(:string)
               optional(:role).value(:string, included_in?: %w[admin member guest])
             end
           end
   
           def handle(request, response)
             result = user_repo.create(request.params[:user])
             response.status = 201
             response.body = result.to_json
           end
         end
       end
     end
   end

2. Custom rules for cross-field validation:

   params do
     required(:password).value(:string, min_size?: 8)
     required(:password_confirmation).value(:string)
   
     rule(:password_confirmation) do
       key.failure("must match password") unless value == values[:password]
     end
   end

Common Mistakes

Integration