Build Status Dependency Status Code Climate Gem Version Inline docs

Psst, full documentation can be found at

Serial is a light-weight and simple serialization library. Its primary purpose is to generate primitive datastructures from object graphs, in other words to help you serialize your data.

Serial is sponsored by Elabs.

elabs logo


Add this line to your application's Gemfile:

gem "serial"

And then execute:

$ bundle


Full reference: Serial::HashBuilder, Serial::ArrayBuilder.

  • All keys are turned into strings.
  • There is no automatic camel-casing. You name your keys the way you want them.
  • Using the same key twice will raise an error by default.
  • To override the value for an existing key, use the respective !-method DSL, i.e. #attribute!, #collection!, #map!, or #merge!.

Simple attributes

#attribute creates a simple attribute with a value.

ProjectSerializer = do |h, project|
  h.attribute(:displayName, project.display_name)
end # => { "id" => …, "displayName" => … }

Nested attributes

#attribute supports nesting by giving it a block.

ProjectSerializer = do |h, project|
  h.attribute(:owner, project.owner) do |h, owner|
end # => { "owner" => { "name" => … } }


#map is a convenient method for serializing lists of items.

ProjectSerializer = do |h, project|, project.assignments) do |h, assignment|
    h.attribute(:duration, assignment.duration)
end # => { "assignments" => [{ "id" => …, "duration" => … }, …] }

The low-level interface powering #map is #collection.

ProjectSerializer = do |h, project|
  h.collection(:indices) do |l|
    l.element { |h| h.attribute()  }
    l.element { |h| h.attribute()  }

    l.collection do |l|
      l.element {  }
      l.element {  }
end # => { "indices" => [{…}, {…}, [{…}, {…}]] }


#merge will let you merge another serializer without introducing a new nesting level.

ProjectSerializer = do |h, project|
end # => { "name" => … }

FullProjectSerializer = do |h, project|
  h.merge(project, &ProjectSerializer)
  h.attribute(:description, project.description)
end # { "name" => …, "description" => … }


You can compose serializers by passing them as blocks to the DSL methods.

PersonSerializer = do |h, person|
end # => { "name" => … }

ProjectSerializer = do |h, project|
  h.attribute(:owner, project.owner, &PersonSerializer), project.people, &PersonSerializer)
end # { "owner" => { "name" => … }, "people" => [{ "name" => … }, …] }

Using your serializers

Full reference: Serial::Serializer.

  • The context parameter in the below examples (when using #call and #map) is optional, if not provided regular block scoping rules apply.
  • Tip: include Serial::RailsHelpers in ApplicationController for a convenient #serialize method.

Serializing a single object

project = Project.find()
context = self, project) # => { … }

Serializing a list of objects

projects = Project.all
context = self, projects) # => [{ … }, …]

Using with Rails

# app/serializers/project_serializer.rb
ProjectSerializer = do |h, project|
# app/controllers/project_controller.rb
class ProjectController < ApplicationController
  include Serial::RailsHelpers

  def show
    project = Project.find()

    # 1. Using helper from RailsHelpers.
    render json: serialize(project)

    # 2. Explicitly mentioning serializer using helper method.
    render json: serialize(project, &ProjectSerializer)

    # 3. Explicitly mentioning serializer.
    render json:, project)


After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to


Bug reports and pull requests are welcome on GitHub at This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.


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