Skip to content
ActiveModel::Serializer implementation and Rails hooks
Ruby Other
Latest commit f48fd2a May 28, 2016 @beauby beauby committed with NullVoxPopuli Extract IncludeTree. (#1685)


Build Status Build Status Build status
Code Quality Code Quality codebeat Test Coverage
Issue Stats Pulse


ActiveModelSerializers brings convention over configuration to your JSON generation.

ActiveModelSerializers works through two components: serializers and adapters.

Serializers describe which attributes and relationships should be serialized.

Adapters describe how attributes and relationships should be serialized.

SerializableResource co-ordinates the resource, Adapter and Serializer to produce the resource serialization. The serialization has the #as_json, #to_json and #serializable_hash methods used by the Rails JSON Renderer. (SerializableResource actually delegates these methods to the adapter.)

By default ActiveModelSerializers will use the Attributes Adapter (no JSON root). But we strongly advise you to use JsonApi Adapter, which follows 1.0 of the format specified in Check how to change the adapter in the sections below.

0.10.x is not backward compatible with 0.9.x nor 0.8.x.

0.10.x is based on the 0.8.0 code, but with a more flexible architecture. We'd love your help. Learn how you can help here.

It is generally safe and recommended to use the master branch.


Add this line to your application's Gemfile:

gem 'active_model_serializers', '~> 0.10.0'

And then execute:

$ bundle

Getting Started

See Getting Started for the nuts and bolts.

More information is available in the Guides and High-level behavior.

Getting Help

If you find a bug, please report an Issue and see our contributing guide.

If you have a question, please post to Stack Overflow.

If you'd like to chat, we have a community slack.



High-level behavior

Given a serializable model:

# either
class SomeResource < ActiveRecord::Base
  # columns: title, body
# or
class SomeResource < ActiveModelSerializers::Model
  attr_accessor :title, :body

And initialized as:

resource = 'ActiveModelSerializers', body: 'Convention over configuration')

Given a serializer for the serializable model:

class SomeSerializer < ActiveModel::Serializer
  attribute :title, key: :name
  attributes :body

The model can be serialized as:

options = {}
serialization =, options)

SerializableResource delegates to the adapter, which it builds as:

adapter_options = {}
adapter = ActiveModelSerializers::Adapter.create(serializer, adapter_options)

The adapter formats the serializer's attributes and associations (a.k.a. includes):

serializer_options = {}
serializer =, serializer_options)

See for more information.



Something went wrong with that request. Please try again.