Skip to content


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Convention-driven JSON generation for Rails.
branch: master

This branch is 9 commits ahead, 204 commits behind rails-api:master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.


Build Status

ActiveModel::Serializers brings convention over configuration to your JSON generation.

AMS does this through two components: serializers and adapters. Serializers describe which attributes and relationships should be serialized. Adapters describe how attributes and relationships should be serialized.


Given two models, a Post(title: string, body: text) and a Comment(name:string, body:text, post_id:integer), you will have two serializers:

class PostSerializer < ActiveModel::Serializer
  attribute :title, :body

  has_many :comments

  url :post


class CommentSerializer < ActiveModel::Serializer
  attribute :name, :body

  belongs_to :post

  url [:post, :comment]

Generally speaking, you as a user of AMS will write (or generate) these serializer classes. By default, they will use the JsonApiAdapter, implemented by AMS. If you want to use a different adapter, such as a HalAdapter, you can change this in an initializer:

ActiveModel::Serializer.default_adapter = ActiveModel::Serializer::Adapter::HalAdapter

You won't need to implement an adapter unless you wish to use a new format or media type with AMS.

In your controllers, when you use render :json, Rails will now first search for a serializer for the object and use it if available.

class PostsController < ApplicationController
  def show
    @post = Post.find(params[:id])

    render json: @post

In this case, Rails will look for a serializer named PostSerializer, and if it exists, use it to serialize the Post.


Add this line to your application's Gemfile:

gem 'active_model_serializers' 

And then execute:

$ bundle 

Creating a Serializer

The easiest way to create a new serializer is to generate a new resource, which will generate a serializer at the same time:

$ rails g resource post title:string body:string

This will generate a serializer in app/serializers/post_serializer.rb for your new model. You can also generate a serializer for an existing model with the serializer generator:

$ rails g serializer post

The generated seralizer will contain basic attributes and has_many/belongs_to declarations, based on the model. For example:

class PostSerializer < ActiveModel::Serializer
  attribute :title, :body

  has_many :comments

  url :post


class CommentSerializer < ActiveModel::Serializer
  attribute :name, :body

  belongs_to :post_id

  url [:post, :comment]

The attribute names are a whitelist of attributes to be serialized.

The has_many and belongs_to declarations describe relationships between resources. By default, when you serialize a Post, you will get its Comments as well.

The url declaration describes which named routes to use while generating URLs for your JSON. Not every adapter will require URLs.


  1. Fork it ( )
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request
Something went wrong with that request. Please try again.