Category guides

JSON serializers for Rails APIs: Jbuilder, Alba, Blueprinter and ActiveModelSerializers

Category guides · By the Gemfile Review editorial team · Published 2026-10-26

Every Rails API has to turn records into JSON. Rails can do it on its own, Jbuilder ships in the default Gemfile, and a handful of serializer gems promise cleaner code or more speed. The right choice depends mostly on whether you think of your JSON as a view or as a class.

Release figures are from RubyGems.org, October 2026.

What Rails already does

render json: @article calls as_json on the object, which Active Model provides for every Active Record model. You can shape the output with options:

render json: @article.as_json(only: [:id, :title], include: { author: { only: :name } })

That is enough for a small internal endpoint. It breaks down when the same model needs different shapes in different places, when you add computed fields, or when someone overrides as_json in the model and every endpoint changes at once. The main risk is leaking columns: without only:, every attribute goes out, including ones added to the table later. The Rails guide to API-only applications covers the rest of the API setup.

Jbuilder: JSON as a view

Jbuilder (2.15.1, May 2026) is maintained in the Rails organisation and treats JSON as a template, in app/views/articles/show.json.jbuilder:

json.extract! @article, :id, :title, :published_at
json.author do
  json.name @article.author.name
end
json.url article_url(@article, format: :json)

Partials, caching with json.cache! and all the view helpers are available, and the scaffold generator writes Jbuilder views for you. In Rails 8.1 the app generator adds jbuilder to the Gemfile of a normal application and leaves it commented out in an --api application.

The cost is speed: templates are evaluated per request, and large collections with partials render slowly compared with plain Ruby serializers. Choose it when your app already renders HTML views, the JSON mirrors those pages, and payloads are modest.

Alba: plain Ruby classes, no dependencies

Alba (4.0.1, released on 17 October 2026) describes itself as a JSON serializer for Ruby, JRuby and TruffleRuby. It lists no runtime dependencies on RubyGems, so it works outside Rails too.

class ArticleResource
  include Alba::Resource
  root_key :article
  attributes :id, :title
  attribute :author_name do |article|
    article.author.name
  end
end

ArticleResource.new(@article).serialize

It supports associations, conditional attributes, key transformation (to camelCase, for example) and several JSON back ends. Major versions have changed behaviour, so read the changelog before upgrading, and pin the major version. Choose it when you are starting a new API and want explicit serializer classes with good performance.

Blueprinter: one class, several views

Blueprinter (1.3.0, April 2026) is published from the procore-oss organisation on GitHub and, like Alba, has no runtime dependencies. Its distinctive idea is views: one blueprint declares a base set of fields plus named variants, so a list endpoint and a detail endpoint share a single class.

class ArticleBlueprint < Blueprinter::Base
  identifier :id
  fields :title
  view :extended do
    fields :body, :published_at
    association :author, blueprint: AuthorBlueprint
  end
end

ArticleBlueprint.render(@article, view: :extended)

Choose it when many endpoints show the same resource at different levels of detail.

ActiveModelSerializers

ActiveModelSerializers, or AMS (0.10.16, December 2025), was the default answer for years and is still in a very large number of Gemfiles. Version 0.10 splits the work into serializers (which fields and relationships) and adapters (the output format: plain attributes, a root key, or JSON:API). Its README warns that 0.10.x is not backward compatible with 0.9.x or 0.8.x, so old tutorials can mislead.

Releases have been spaced about a year apart recently (0.10.14 in October 2023, 0.10.15 in December 2024, 0.10.16 in December 2025). It works, but few teams pick it for a new project now. Alba's README links a third-party tool that converts AMS serializer classes to Alba resources, which tells you where many migrations are heading.

jsonapi-serializer, for JSON:API responses

If your clients expect the JSON:API specification, with data, attributes, relationships and included, jsonapi-serializer generates that format directly. It began as a fork of Netflix's fast_jsonapi, whose last release was 1.5 in November 2018. Check its status before adopting it: the latest release is 2.2.0 from March 2021, and the README says the v2 branch is in maintenance mode, accepting only bug and security fixes while work happens on v3. AMS's JSON:API adapter and Alba are the alternatives.

Serializer or encoder?

The gems above decide which fields go out. Turning the resulting hash into a string is a separate step, done by Rails' own JSON encoder unless you swap it. Oj (3.17.7, September 2026) is a C extension that parses and generates JSON and offers a Rails compatibility mode, Oj.optimize_rails; Alba can also be pointed at it as a back end. Measure before adding it: on most endpoints, database queries cost far more than encoding, and a C extension is one more native dependency to compile on every Ruby upgrade. Weigh it like any other addition to the Gemfile: maintenance, compatibility and exit cost.

Choices that matter more than the gem

• Allow-list fields. Declare every attribute you send. Never serialize a whole model by default.
• Watch for N+1 queries. Serializers walk associations; use includes or preload in the controller. Pagination keeps payloads bounded: see pagination gems and keyset pagination.
• Different fields for different users. Decide in the policy layer what a user may see, then pass that context to the serializer. The authorization gems guide covers Pundit and Action Policy.
• Test the shape. A request spec that checks the JSON keys catches accidental changes; testing Rails applications covers the tools.
• Version deliberately. Renaming a field breaks mobile apps that cannot update instantly. Add new fields, deprecate old ones, and remove them later.

Summary

Read next

More in Category guides

Category guides

Pagination

Comparing Rails pagination gems — Pagy, Kaminari and will_paginate — and when to use offset or keyset pagination for large tables and infinite scrolling.

Category guides

Authorization

How Pundit, CanCanCan and Action Policy model permissions in a Rails application, how each handles scopes and testing, and when a hand-written approach is enough.

Guides

Evaluating a Rails gem

A practical checklist for judging a Ruby gem: maintenance signals, compatibility with Rails 7 and 8, dependencies, licence, and security advisories with bundler-audit.