ActiveModelSerializers sits between a released 0.10 line and an unreleased master

The newest tag is from 2015 and master has no release on it

Start with the timeline, because it decides what you are adopting. The most recent published tags are v0.10.0.rc1 on 2015-04-22, v0.10.0.rc2 on 2015-06-16, and v0.10.0.rc3 on 2015-09-16, while the last commit on the repository is dated 2025-12-08. That gap is the fact to plan around: code is landing on master, and none of it is in a gem you can install. The README says it plainly, master for the moment will not have any released version on it. It also says every open pull request against master will need to be closed and reopened against 0-10-stable if you still want it reviewed. So the branch you read is not the branch you install, and the version in your Gemfile does not describe the repository you are browsing.

The 1.0 plan deletes implicit serializer lookup

The redesign is stated as a removal rather than an addition. Models to serializers is a one to many relationship, and everything has to become explicit: if you want to serialize a User with a UserSerializer, you call it directly. Gone from the design are the implicit behaviours, specifically guessing the serializer, picking the association's serializer, and inferring the serialization type. A serializer in the new model defines a basic JSON:API resource object with id, type, attributes, and relationships, exposes an as_json method, and can be told which fields to emit. These changes arrived in PR 2121, and the README marks the whole shape as still somewhat in discussion. For a reader, that sentence is the important one: you would be building against a proposal, not against a specification.

Relations serialize to an id and a type, and nothing else

The stated limit on nesting is worth reading twice, because it is where the old behaviour and the new one differ most. Under the plan, a serializer knows nothing about a relation beyond its id and type, and serializing anything more requires code that called a serializer. That is a direct answer to the classic ActiveModelSerializers complaint that rendering an association drags in a second, unexpected serializer. It also means a client cannot rely on nested attributes arriving automatically. The cost is verbosity in your own code: every extra level of nesting is an explicit serializer call, and the person writing that call has to decide which fields the client is allowed to see. The README acknowledges the design is still open, so treat this as the direction rather than the contract.

0.10.x is a maintenance line with the 1.0 goal abandoned

The 0.10 line has its own status note, and it is not good news. It became a huge maintenance version, the maintainers had hoped to get it into shape for a 1.0 release, and the README states that this is not going to happen. It also says almost none of the maintainers from 0.8, 0.9, or earlier 0.10 are still working on the project. What remains is a promise to continue maintaining 0.10.x on the 0-10-stable branch, with no new feature work planned there. There is one more possibility mentioned: a 0.11.x on a 0-11-stable branch that only removes deprecations. If you adopt the gem today, you inherit whatever deprecation warnings 0.10 emits, and possibly a later upgrade that is purely subtractive.

Six alternatives are named, each taking a different bet

The README points new projects away from itself, and the list is specific about what each option trades. jsonapi-rb is presented as a highly performant, modular, JSON:API-only implementation with a community behind it. fast_jsonapi is a fast JSON:API serializer for Ruby objects. jsonapi-resources is a resource-focused framework for building JSON:API servers. blueprinter comes from Procore and is fast, declarative, and API spec agnostic, using composable views to reduce duplication. Alba adds global or per-resource error handling. Transmutation is fast and lightweight, with an intuitive serializer lookup inspired by AMS. The repository also carries a benchmarks directory, which is the only comparison in the README that is not a claim by one of the projects.

Which docs you land on depends on which branch you read

The README warns that if you are reading it on the repository page you are reading documentation for master, which is not yet released. Alongside it sit three older documentation sets, and the table below is the version map you actually navigate by:

0.10 (0-10-stable)   rubydoc.info/gems/active_model_serializers/0.10.6   tree/v0.10.6/docs
0.9 (0-9-stable)     rubydoc.info/github/rails-api/active_model_serializers/0-9-stable
0.8 (0-8-stable)     rubydoc.info/github/rails-api/active_model_serializers/0-8-stable

The consequence for a reader arriving from search is that tutorials and answers mix 0.8, 0.9, and 0.10 APIs freely, and the branch you clone decides which one you copy. There is no install command or code sample anywhere in the README, so the gemspec name, the branch, and the docs table are the whole on-ramp. Check all three before you trust a snippet.

Five changelog files record the shape changes since Rails 3.2

The repository layout tells you how long the history is. It starts back in Rails 3.2, and the root keeps a changelog per generation:

CHANGELOG-prehistory.md
CHANGELOG-0-08.md
CHANGELOG-0-09.md
CHANGELOG-0-10.md
CHANGELOG.md
active_model_serializers.gemspec

Alongside them sit MIT-LICENSE, Rakefile, docs/, CONTRIBUTING.md, CODE_OF_CONDUCT.md, appveyor.yml, and .travis.yml. Two CI configurations and a Rakefile are the fingerprint of the era this gem comes from, and the version history is split by minor release rather than kept in one stream. The practical cost is that moving between 0.8, 0.9, and 0.10 is a reading project, not a diff. The project states it adheres to semver, which is a promise about version numbers, not about how much of your serializer code survives an upgrade.

Editorial conclusion

Use ActiveModelSerializers when an existing Rails codebase already depends on it and the released 0.10 line is good enough, because that line is where the fixes land. Do not start a new API on it expecting the 1.0 design to arrive on a schedule: the README states the rewrite is still in discussion, that master will carry no release, and that the maintainers may or may not publish a 0.11 that only strips deprecations. For anything greenfield, read the alternatives section first, then use the benchmarks directory in the repository to compare rather than guessing. Before you pin a version, check which branch your code was written against, since 0.8, 0.9, and 0.10 each ship their own documentation.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. Release notes