Skip to content
A JSON Serializer for Ruby Objects
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


Build Status Code Climate

JSerializer is a JSON Serializer for Ruby objects. It is designed to be a drop-in replacement of Active Model Serializer (target version: 0.8) with better performance.

JSerializer does not rely on Rails or Active Model or Active Support, which makes it easier to be integrated into general Ruby projects.


Add this line to your application's Gemfile:

gem 'jserializer'

And then execute:

$ bundle

Or install it yourself as:

$ gem install jserializer


Define a Model

Person =, :first_name, :last_name, :age, :gender, :country)

Create a Serializer

class PersonSerializer < Jserializer::Base
  root :user
  attributes :full_name, :age, :gender
  attribute :country, key: :country_code

  def full_name
    "#{object.first_name} #{object.last_name}"

  def gender
    object.gender == 'm' ? 'Male' : 'Female'

  def include_age?
    object.age >= 18

Generate JSON

person =, 'John', 'Doe', 16, 'm', 'US')
serializer =

# generates a Hash without root key
# => {:full_name=>"John Doe", :gender=>"Male", :country_code=>"US"}

# generates a Hash with root key
# => {:user=>{:full_name=>"John Doe", :gender=>"Male", :country_code=>"US"}}

# generates JSON => {"user":{"full_name":"John Doe","gender":"Male","country_code":"US"}}

Generate JSON Collection

persons ={|i|, 'Person', "#{i}", 17 + i, 'm', 'US') }
serializer =, is_collection: true)

You will get:

      "full_name":"Person 0",
      "full_name":"Person 1",

Bring Your Own JSON Encoder

Our to_json method uses standard JSON module to generate JSON string. There are many JSON encode backend there, and they offer different customization options. Besides, you can use MultiJson to switch between different backends.

You are welcome to bring your own solution here. To do that, simply override the to_json method

class ApplicationSerializer < Jserializer::Base
  def to_json(*)
    # use ActiveSupport in Rails as a delegator
    # use oj:
    # Oj.dump(as_json, mode: :compat, use_to_json: true)

Then the rest of your serializers can inherit from ApplicationSerializer and start to use your preferred encoder.

Serializer Class Definition Options

Method Options Description
root N/A Set the root key of the generated JSON
attributes N/A Define a list of fields separated by , to be exposed from a Ruby object
attribute :key - The name in the JSON output Similar to attributes but for one field
has_many :serializer
Include a collection of objects with has many association
has_one Same as has_many Include a object with has one association
embed :ids
Determine if only include IDs of the associations


This example shows you where to apply the above methods

class PostSerializer < Jserializer::Base
  root :article
  embed :ids
  attributes :id, :title, :content
  attribute :writer, key: :written_by
  has_many :comments, serializer: CommentSerializer, embed: :objects
  has_one :author, serializer: AuthorSerializer, embed_key: :id

For associations, Jserializer uses the following ways to retrieve data:

Type Method Example
has_many collection_singular_ids posts => post_ids
has_one account =>

Initialization Options for Serializer Instance

Options Description
root Set the root key of the generated JSON, set it to false to disable
meta Meta information to be included in the JSON output
meta_key The key name of the meta information, the default is :meta
is_collection Whether the given object is a collection or single object
only An array of attributes to be included in the JSON output
except An array of attributes to be excluded in the JSON output
current_user Use for determine the authorization scope

                   root: :post,
                   meta: { page: 1, total: 100},
                   is_collection: true,
                   only: [:title, :content])

You can enable/disable root when initializing a serializer instance:, root: false)

Or when calling as_json method:

# here the root option only accept a boolean value
# you cannot rename root at this point false)

You can always get the Hash representation without root and meta information by calling serializable_hash


The active_serializer_model gem includes the ArraySerializer class to handle collections. There are a lot of magics happening underneath when you pass a collection object into render json: @xxx, to allow ArraySerializer gets triggered automatically.

Unlike active_serializer_model, there is no separate serializer class for array. To serialize a collection, you need to set is_collection: true when initializing a new serializer

serializer =, is_collection: true)
serializer.serializable_hash # or serializer.as_json to include root

You can also call serializable_collection method directly which will ignore the is_collection option

serializer =

Compatibility & Migration

Currently, this gem is not compatible with active_serializer_model if you:

  • have include_xxx? as private method
  • override the instance method attributes
  • override any internal method _xxx (e.g. _serializable_array)
  • expect serializer to automatically include a root for you
  • expect serializer figures out if the object is a collection automatically

Since we try to reuse serializer instances to avoid unnecessary object creations, make sure there is no things like ||= in the serializer class. Or you can override reset method to clean things out

class MySerializer < Jserializer::Base
  ... ...
  def reset(object)
    @my_cached_stuff = nil
    ... ...

active_model_serializer method

This gem will try to find and use the serializer class defined by active_model_serializer method in a model, if you don't specify serializer explicitly

class Post < ActiveRecord::Base
  def active_model_serializer

Use in Rails Action Controller

Active Model Serializer overrides render :json in ActionController::Serialization, which is convenient. But it touches Rails internal methods which could bring compatibility issues when upgrading Rails.

This gem does not provide such feature, but you can easily achieve it in application layer, for example, create a wrapper method for render:

class ApplicationController < ActionController::Base
  # ... ...
  def render_json(resource, options = {})
    if options.key?(:serializer)
      serializer = options.delete(:serializer)
    elsif options.key?(:each_serializer)
      serializer = options.delete(:each_serializer)
      options[:is_collection] = true

    if !serializer && resource.respond_to?(:active_model_serializer)
      serializer = resource.active_model_serializer

    if serializer
      options[:scope] = current_user
      options[:json] =, options)
      options[:json] = resource
    render options

Then you can use this render_json method whenever you need to call render json: resource ... in your controllers. And this is probably a good way to migrate gradually.


This gem does not plan to implement the cache feature.


See here


Bug reports and pull requests are welcome on GitHub at

You can’t perform that action at this time.