Alba, a fast JSON serializer for Ruby

A resource class, and one method to serialize

Alba is a JSON serializer for Ruby, JRuby and TruffleRuby, and the whole idea fits in the example the README opens with. You include Alba::Resource in a class of your own, name the attributes you want to expose, and optionally define computed attributes as blocks.

class UserResource
  include Alba::Resource

  root_key :user

  attributes :id, :name

  attribute :name_with_email do |resource|
    "#{resource.name}: #{resource.email}"
  end
end

user = User.new(1, 'Masafumi OKURA', '[email protected]')
UserResource.new(user).serialize

The output is a single JSON string with the object nested under the root key you declared, and the computed attribute evaluated at serialization time. The design goal is stated as being easy because there are only a few methods to remember, easy to understand because the codebase is clean and small, and easy to extend because Alba provides methods to override so you can change the default behaviour. The audience is a Ruby developer who wants precise control over an API response without a framework's conventions, and the gem is published on RubyGems as alba under the MIT licence.

Fast, small, and honest about what it does not do

The project states three reasons to choose it, and they are worth reading because they also describe the boundaries. It is faster than most of the alternatives, and the repository carries a benchmark directory so the claim is checkable rather than rhetorical. It is easy, for the reasons above. It is feature rich, with the core kept simple and the extras available when needed, and the named examples are a way to control circular associations, root key and association resource name inference, and layouts. Then come the other reasons, and they are the ones a dependency conscious team cares about. Alba is dependency free, so there is no need to install oj or activesupport, although it works well with them. It is well tested, with a stated test coverage of 99 percent. And it is well maintained, with frequent updates and new releases tracked on the RubyGems version history. The discussion happens on GitHub Discussions, with a Feedback category for users and an Ideas category for proposals.

The comparison table tells you where Alba is not the answer

The README compares Alba against ActiveModelSerializers, Blueprinter, JSONAPI::Serializer and JBuilder, and the table is more useful than the marketing copy because the gaps are visible. On dependencies Alba has none, where AMS needs ActiveSupport, JBuilder needs Rails and the other two are minimal. On JSON:API compliance Alba is manual, JSONAPI::Serializer has full support and AMS has it planned. On caching Alba has nothing built in, AMS has it, JBuilder has fragment caching and Blueprinter offers it through an extension. On the features Alba is ahead, with type validation and coercion, a custom type system, nested attributes and circular reference control all marked yes, where the others say no or partial. Error handling is listed as flexible for Alba against limited or basic elsewhere, and nil handling is marked yes for Alba and no for ActiveModelSerializers. The honest reading is that Alba is the most capable of the small serializers, and the least convenient if your API is a JSON:API service or if caching is a requirement you expected to inherit.

Moving from ActiveModelSerializers

For teams arriving from ActiveModelSerializers, the project points at a purpose built converter rather than asking you to rewrite by hand. The alba_migration gem, written by ShoheiMitani, provides a command line tool to convert AMS serializer classes to Alba resource classes, with the stated aim of making the migration process easier and less error prone. That is a detail that tells you something about the audience, since Alba's competitor is not nothing but the incumbent framework serializer in a large Rails codebase. The other resource the README offers is a screencast by Sebastian from Hanami Mastery, which covers the basic features of Alba and how to use it in Hanami, so the library is being presented as usable outside Rails as well. Alba is a plain Ruby gem with no Rails dependency, and the examples directory in the repository contains separate runnable Ruby files for each feature, which is the best way to see what a given capability looks like in code.

The feature set, as the examples directory lists it

The examples directory is effectively the feature list, and it is long. There is circular_associations_control.rb, key_transformation.rb, conditional_attributes_and_associations.rb, nested_attributes.rb, custom_types.rb, types.rb, layout.rb, metadata.rb, metadata_and_pagination.rb, nil_handling.rb, error_handling.rb, traits.rb, polymorphic_associations.rb, custom_association_source.rb, helpers_for_inline_associations.rb, inline_definition.rb, collection_key.rb, root_key_and_association_inference.rb, method_conflicts.rb, selectable_backend.rb and no_runtime_dependencies.rb, along with a Steepfile and a sig/ directory showing the type signatures. The features these files cover map onto the table in the previous section, so a reader deciding between serializers can open the two or three files that match the requirements. The presence of a selectable_backend example and a method_conflicts example is worth noticing, because both point at the awkward parts of a serializer library, the choice of backend implementation and the behaviour when your resource class defines a method that Alba also uses.

Type signatures, a benchmark directory and the usual hygiene files

The repository layout shows a gem that takes its type story seriously. There is a sig/ directory with RBS signatures and a Steepfile at the root and another in the examples directory, so the library is type checked with Steep. The benchmark/ directory is the one referenced in the performance claim, and bin/, gemfiles/ for the appraisal style matrix of dependency sets, and docs/ hold the documentation. Around that sits the standard set of files a well kept Ruby project has, a Rakefile, a .rubocop.yml for the linter, a .yardopts file for the documentation generator, a .codeclimate.yml, a .editorconfig, and a Gemfile for development. Then there is the modern tooling, with AGENTS.md and CLAUDE.md describing conventions for automated agents, a .cursorrules file, HACKING.md, SECURITY.md, CONTRIBUTING.md, a CODE_OF_CONDUCT.md and a CHANGELOG.md. A library that ships type signatures and a benchmark suite is making a different claim from one that ships a README, and that is a reasonable signal about how the project is maintained.

Version 4 and a fast moving release line

The release history shows a project that has moved quickly in the last year. There is v3.10.0 from 2025-11-11, v3.11.0 from 2026-07-27 and v4.0.0 from 2026-08-28, so the 3.x line ran for a long time before a major version landed, and the 4.x line has been settling since. The repository is not archived, and the last push was on 2026-10-15, so the default branch moves faster than the tags. The licence is MIT, in LICENSE.txt, and the gem is distributed through RubyGems, where the version history is the reference for consumers. The practical advice for an adopter is to pin the version and read the changelog between the 3.x and 4.x boundary, because a major version in a serializer is where key names and structure rules tend to change, and Alba's own comparison table shows that key transformation and conditional attributes are configurable behaviours rather than fixed ones, which means a version change can alter the shape of a response without touching your resource class.

Editorial conclusion

Alba fits a Ruby team that wants to control exactly what a JSON response contains without adopting a framework's serializer or a gem with a dependency tree, and it fits a team that has already written the same resource classes by hand for a different serializer. It does not fit an application that needs a JSON:API compliant output, since that compliance is manual here, and it does not fit a team that expects caching to come with the serializer, because Alba does not provide it. Verify three things first: which of the comparison table rows matter for your API, since caching and JSON:API are the two places where the alternatives are stronger, whether the version you pin is one of the 4.x releases, since 4.0.0 is a recent major change after a long 3.x line, and how much of the gem's speed advantage you actually need, given the benchmark suite is in the repository for you to look at rather than a number you have to take on trust.

Frequently asked questions

Official sources

1. License: MIT
2. okuramasafumi/alba on GitHub
3. Project website
4. README
5. Releases