active_model_serializers 0.9.0 → 0.10.12

data/MIT-LICENSE

@@ -1,4 +1,6 @@
-Copyright (c) 2011-2012 José Valim & Yehuda Katz
+Copyright (c) 2014 Steve Klabnik
+
+MIT License
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the
@@ -18,4 +20,3 @@ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
 LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
 OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
 WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-

data/README.md

@@ -1,863 +1,305 @@
-[![Build Status](https://api.travis-ci.org/rails-api/active_model_serializers.png?branch=0-9-stable)](https://travis-ci.org/rails-api/active_model_serializers) 
-[![Code Climate](https://codeclimate.com/github/rails-api/active_model_serializers.png)](https://codeclimate.com/github/rails-api/active_model_serializers) 
+# ActiveModelSerializers
 
-# ActiveModel::Serializers
+<table>
+  <tr>
+    <td>Build Status</td>
+    <td>
+      <a href="https://travis-ci.org/rails-api/active_model_serializers"><img src="https://api.travis-ci.org/rails-api/active_model_serializers.svg?branch=0-10-stable" alt="Build Status" ></a>
+      <a href="https://ci.appveyor.com/project/bf4/active-model-serializers/branch/0-10-stable"><img src="https://ci.appveyor.com/api/projects/status/x6xdjydutm54gvyt/branch/master?svg=true" alt="Build status"></a>
+    </td>
+  </tr>
+  <tr>
+    <td>Code Quality</td>
+    <td>
+      <a href="https://codeclimate.com/github/rails-api/active_model_serializers"><img src="https://codeclimate.com/github/rails-api/active_model_serializers/badges/gpa.svg" alt="Code Quality"></a>
+      <a href="https://codebeat.co/projects/github-com-rails-api-active_model_serializers"><img src="https://codebeat.co/badges/a9ab35fa-8b5a-4680-9d4e-a81f9a55ebcd" alt="codebeat" ></a>
+      <a href="https://codeclimate.com/github/rails-api/active_model_serializers/coverage"><img src="https://codeclimate.com/github/rails-api/active_model_serializers/badges/coverage.svg" alt="Test Coverage"></a>
+    </td>
+  </tr>
+  <tr>
+    <td>Issue Stats</td>
+    <td>
+      <a href="https://github.com/rails-api/active_model_serializers/pulse/monthly">Pulse</a>
+    </td>
+  </tr>
+</table>
 
-## Purpose
+## About
 
-`ActiveModel::Serializers` encapsulates the JSON serialization of objects. 
-Objects that respond to read\_attribute\_for\_serialization 
-(including `ActiveModel` and `ActiveRecord` objects) are supported.
+ActiveModelSerializers brings convention over configuration to your JSON generation.
 
-Serializers know about both a model and the `current_user`, so you can
-customize serialization based upon whether a user is authorized to see the
-content.
+ActiveModelSerializers works through two components: **serializers** and **adapters**.
 
-In short, **serializers replace hash-driven development with object-oriented
-development.**
+Serializers describe _which_ attributes and relationships should be serialized.
 
-# Installing
+Adapters describe _how_ attributes and relationships should be serialized.
 
-The easiest way to install `ActiveModel::Serializers` is to add it to your
-`Gemfile`:
+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.)
 
-```ruby
-gem "active_model_serializers"
-```
-
-Then, install it on the command line:
-
-```
-$ bundle install
-```
-
-#### Ruby 1.8 is no longer supported!
-
-If you must use a ruby 1.8 version (MRI 1.8.7, REE, Rubinius 1.8, or JRuby 1.8), you need to use version 0.8.x.
-Versions after 0.9.0 do not support ruby 1.8. To specify version 0.8, include this in your Gemfile:
-
-```ruby
-gem "active_model_serializers", "~> 0.8.0"
-```
-
-
-# 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
-```
-
-### Support for POROs
-
-The PORO should include ActiveModel::SerializerSupport. That's all you need to
-do to have your POROs supported.
-
-For Rails versions before Rails 4  ActiveModel::Serializers expects objects to
-implement `read_attribute_for_serialization`.
-
-# render :json
-
-In your controllers, when you use `render :json`, Rails will now first search
-for a serializer for the object and use it if available.
-
-```ruby
-class PostsController < ApplicationController
-  def show
-    @post = Post.find(params[:id])
-    render json: @post
-  end
-end
-```
-
-In this case, Rails will look for a serializer named `PostSerializer`, and if
-it exists, use it to serialize the `Post`.
-
-This also works with `respond_with`, which uses `to_json` under the hood. Also
-note that any options passed to `render :json` will be passed to your
-serializer and available as `@options` inside.
-
-To specify a custom serializer for an object, you can specify the
-serializer when you render the object:
-
-```ruby
-render json: @post, serializer: FancyPostSerializer
-```
-
-## Arrays
-
-In your controllers, when you use `render :json` for an array of objects, AMS will
-use `ActiveModel::ArraySerializer` (included in this project) as the base serializer,
-and the individual `Serializer` for the objects contained in that array.
-
-```ruby
-class PostSerializer < ActiveModel::Serializer
-  attributes :title, :body
-end
-
-class PostsController < ApplicationController
-  def index
-    @posts = Post.all
-    render json: @posts
-  end
-end
-```
-
-Given the example above, the index action will return
-
-```json
-{
-  "posts":
-    [
-      { "title": "Post 1", "body": "Hello!" },
-      { "title": "Post 2", "body": "Goodbye!" }
-    ]
-}
-```
-
-By default, the root element is the name of the controller. For example, `PostsController`
-generates a root element "posts". To change it:
-
-```ruby
-render json: @posts, root: "some_posts"
-```
-
-You may disable the root element for arrays at the top level, which will result in
-more concise json. See the next section for ways on how to do this. Disabling the
-root element of the array with any of those methods will produce
-
-```json
-[
-  { "title": "Post 1", "body": "Hello!" },
-  { "title": "Post 2", "body": "Goodbye!" }
-]
-```
-
-To specify a custom serializer for the items within an array:
-
-```ruby
-render json: @posts, each_serializer: FancyPostSerializer
-```
-
-## Render independently
-
-By default the setting of serializer is in controller as described above which is the
-recommended way. However, there may be cases you need to render the json object elsewhere
-say in a helper or a view when controller is only for main object.
-
-Then you can render the serialized JSON independently.
-
-```ruby
-def current_user_as_json_helper
-  CurrentUserSerializer.new(current_user).to_json
-end
-```
-
-You can also render an array of objects using ArraySerializer.
-
-```ruby
-def users_array_as_json_helper(users)
-  ActiveModel::ArraySerializer.new(users, each_serializer: UserSerializer).to_json
-end
-```
-
-
-## Disabling the root element
-
-You have 4 options to disable the root element, each with a slightly different scope:
-
-#### 1. Disable root globally for all, or per class
-
-In an initializer:
-
-```ruby
-# Disable for all serializers (except ArraySerializer)
-ActiveModel::Serializer.root = false
-
-# Disable for ArraySerializer
-ActiveModel::ArraySerializer.root = false
-```
-
-#### 2. Disable root per render call in your controller
-
-```ruby
-render json: @posts, root: false
-```
-
-#### 3. Subclass the serializer, and specify using it
-
-```ruby
-class CustomArraySerializer < ActiveModel::ArraySerializer
-  self.root = false
-end
-
-# controller:
-render json: @posts, serializer: CustomArraySerializer
-```
-
-#### 4. Define default_serializer_options in your controller
-
-If you define `default_serializer_options` method in your controller,
-all serializers in actions of this controller and it's children will use them.
-One of the options may be `root: false`
-
-```ruby
-def default_serializer_options
-  {
-    root: false
-  }
-end
-```
-
-## Changing the Key Format
-
-You can specify that serializers use the lower-camel key format at the config, class or instance level.
-
-```ruby
-
-ActiveModel::Serializer.setup do |config|
-  config.key_format = :lower_camel
-end
-
-class BlogLowerCamelSerializer < ActiveModel::Serializer 
-  format_keys :lower_camel
-end
-
-BlogSerializer.new(object, key_format: :lower_camel)
-```
-
-## Getting the old version
-
-If you find that your project is already relying on the old rails to_json
-change `render :json` to `render json: @your_object.to_json`.
-
-# Attributes and Associations
+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 [jsonapi.org/format](https://jsonapi.org/format).
+Check how to change the adapter in the sections below.
 
-Once you have a serializer, you can specify which attributes and associations
-you would like to include in the serialized form.
+`0.10.x` is **not** backward compatible with `0.9.x` nor `0.8.x`.
 
-```ruby
-class PostSerializer < ActiveModel::Serializer
-  attributes :id, :title, :body
-  has_many :comments
-end
-```
-
-## Attributes
+`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.](CONTRIBUTING.md)
 
-For specified attributes, a serializer will look up the attribute on the
-object you passed to `render :json`. It uses
-`read_attribute_for_serialization`, which `ActiveRecord` objects implement as a
-regular attribute lookup.
+## Installation
 
-Before looking up the attribute on the object, a serializer will check for the
-presence of a method with the name of the attribute. This allows serializers to
-include properties beyond the simple attributes of the model. For example:
+Add this line to your application's Gemfile:
 
-```ruby
-class PersonSerializer < ActiveModel::Serializer
-  attributes :first_name, :last_name, :full_name
-
-  def full_name
-    "#{object.first_name} #{object.last_name}"
-  end
-end
 ```
-
-Within a serializer's methods, you can access the object being
-serialized as `object`.
-
-Since this shadows any attribute named `object`, you can include them through `object.object`. For example:
-
-```ruby
-class VersionSerializer < ActiveModel::Serializer
-  attribute :version_object, key: :object
-
-  def version_object
-    object.object
-  end
-end
+gem 'active_model_serializers', '~> 0.10.0'
 ```
 
-You can also access the `scope` method, which provides an
-authorization context to your serializer. By default, the context
-is the current user of your application, but this
-[can be customized](#customizing-scope).
-
-Serializers provide a method named `filter`, which should return an array
-used to determine what attributes and associations should be included in the output.
-This is typically used to customize output based on `current_user`. For example:
+And then execute:
 
-```ruby
-class PostSerializer < ActiveModel::Serializer
-  attributes :id, :title, :body, :author
-
-  def filter(keys)
-    if scope.admin?
-      keys
-    else
-      keys - [:author]
-    end
-  end
-end
 ```
-
-And it's also safe to mutate keys argument by doing keys.delete(:author)
-in case you want to avoid creating two extra arrays. Note that if you do an
-in-place modification, you still need to return the modified array.
-
-If you would like the key in the outputted JSON to be different from its name
-in ActiveRecord, you can declare the attribute with the different name
-and redefine that method:
-
-```ruby
-class PostSerializer < ActiveModel::Serializer
-  # look up subject on the model, but use title in the JSON
-  def title
-    object.subject
-  end
-
-  attributes :id, :body, :title
-  has_many :comments
-end
+$ bundle
 ```
 
-If you would like to add meta information to the outputted JSON, use the `:meta`
-option:
+## Getting Started
 
-```ruby
-render json: @posts, serializer: CustomArraySerializer, meta: {total: 10}
-```
+See [Getting Started](docs/general/getting_started.md) for the nuts and bolts.
 
-The above usage of `:meta` will produce the following:
+More information is available in the [Guides](docs) and
+[High-level behavior](README.md#high-level-behavior).
 
-```json
-{
-  "meta": { "total": 10 },
-  "posts": [
-    { "title": "Post 1", "body": "Hello!" },
-    { "title": "Post 2", "body": "Goodbye!" }
-  ]
-}
-```
+## Getting Help
 
-If you would like to change the meta key name you can use the `:meta_key` option:
+If you find a bug, please report an [Issue](https://github.com/rails-api/active_model_serializers/issues/new)
+and see our [contributing guide](CONTRIBUTING.md).
 
-```ruby
-render json: @posts, serializer: CustomArraySerializer, meta: {total: 10}, meta_key: 'meta_object'
-```
+If you have a question, please [post to Stack Overflow](https://stackoverflow.com/questions/tagged/active-model-serializers).
 
-The above usage of `:meta_key` will produce the following:
+If you'd like to chat, we have a [community slack](https://amserializers.herokuapp.com).
 
-```json
-{
-  "meta_object": { "total": 10 },
-  "posts": [
-    { "title": "Post 1", "body": "Hello!" },
-    { "title": "Post 2", "body": "Goodbye!" }
-  ]
-}
-```
+Thanks!
 
-When using meta information, your serializer cannot have the `{ root: false }` option, as this would lead to
-invalid JSON. If you do not have a root key, the meta information will be ignored.
+## Documentation
 
-If you would like direct, low-level control of attribute serialization, you can
-completely override the `attributes` method to return the hash you need:
+If you're reading this at https://github.com/rails-api/active_model_serializers you are
+reading documentation for our `master`, which may include features that have not
+been released yet. Please see below for the documentation relevant to you.
 
-```ruby
-class PersonSerializer < ActiveModel::Serializer
-  attributes :first_name, :last_name
-
-  def attributes
-    hash = super
-    if scope.admin?
-      hash["ssn"] = object.ssn
-      hash["secret"] = object.mothers_maiden_name
-    end
-    hash
-  end
-end
-```
-
-## Associations
-
-For specified associations, the serializer will look up the association and
-then serialize each element of the association. For instance, a `has_many
-:comments` association will create a new `CommentSerializer` for each comment
-and use it to serialize the comment.
+- [0.10 (0-10-stable) Documentation](https://github.com/rails-api/active_model_serializers/tree/0-10-stable)
+- [0.10.10 (latest release) Documentation](https://github.com/rails-api/active_model_serializers/tree/v0.10.10)
+    - [![API Docs](https://img.shields.io/badge/yard-docs-blue.svg)](https://www.rubydoc.info/gems/active_model_serializers/0.10.10)
+    - [Guides](docs)
+- [0.9 (0-9-stable) Documentation](https://github.com/rails-api/active_model_serializers/tree/0-9-stable)
+    - [![API Docs](https://img.shields.io/badge/yard-docs-blue.svg)](https://www.rubydoc.info/gems/active_model_serializers/0.9.7)
+- [0.8 (0-8-stable) Documentation](https://github.com/rails-api/active_model_serializers/tree/0-8-stable)
+    - [![API Docs](https://img.shields.io/badge/yard-docs-blue.svg)](https://www.rubydoc.info/gems/active_model_serializers/0.8.4)
 
-By default, serializers simply look up the association on the original object.
-You can customize this behavior by implementing a method with the name of the
-association and returning a different Array. Often, you will do this to
-customize the objects returned based on the current user (scope).
-
-```ruby
-class PostSerializer < ActiveModel::Serializer
-  attributes :id, :title, :body
-  has_many :comments
-
-  # only let the user see comments he created.
-  def comments
-    object.comments.where(created_by: scope)
-  end
-end
-```
 
-As with attributes, you can change the JSON key that the serializer should
-use for a particular association.
+## High-level behavior
 
-```ruby
-class PostSerializer < ActiveModel::Serializer
-  attributes :id, :title, :body
+Choose an adapter from [adapters](lib/active_model_serializers/adapter):
 
-  # look up comments, but use +my_comments+ as the key in JSON
-  has_many :comments, root: :my_comments
-end
+``` ruby
+ActiveModelSerializers.config.adapter = :json_api # Default: `:attributes`
 ```
 
-Also, as with attributes, serializers will execute a filter method to
-determine which associations should be included in the output. For
-example:
+Given a [serializable model](lib/active_model/serializer/lint.rb):
 
 ```ruby
-class PostSerializer < ActiveModel::Serializer
-  attributes :id, :title, :body
-  has_many :comments
-
-  def filter(keys)
-    keys.delete :comments if object.comments_disabled?
-    keys
-  end
+# either
+class SomeResource < ActiveRecord::Base
+  # columns: title, body
 end
-```
-
-Or ...
-
-```ruby
-class PostSerializer < ActiveModel::Serializer
-  attributes :id, :title, :body
-  has_one :author
-  has_many :comments
-
-  def filter(keys)
-    keys.delete :author unless scope.admin?
-    keys.delete :comments if object.comments_disabled?
-    keys
-  end
+# or
+class SomeResource < ActiveModelSerializers::Model
+  attributes :title, :body
 end
 ```
 
-You may also use the `:serializer` option to specify a custom serializer class and the `:polymorphic` option to specify an association that is polymorphic (STI), e.g.:
+And initialized as:
 
 ```ruby
-  has_many :comments, serializer: CommentShortSerializer
-  has_one :reviewer, polymorphic: true
-```
-
-Serializers are only concerned with multiplicity, and not ownership. `belongs_to` ActiveRecord associations can be included using `has_one` in your serializer.
-
-NOTE: polymorphic was removed because was only supported for has\_one
-associations and is in the TODO list of the project.
-
-## Embedding Associations
-
-By default, associations will be embedded inside the serialized object. So if
-you have a post, the outputted JSON will look like:
-
-```json
-{
-  "post": {
-    "id": 1,
-    "title": "New post",
-    "body": "A body!",
-    "comments": [
-      { "id": 1, "body": "what a dumb post" }
-    ]
-  }
-}
+resource = SomeResource.new(title: 'ActiveModelSerializers', body: 'Convention over configuration')
 ```
 
-This is convenient for simple use-cases, but for more complex clients, it is
-better to supply an Array of IDs for the association. This makes your API more
-flexible from a performance standpoint and avoids wasteful duplication.
-
-To embed IDs instead of associations, simply use the `embed` class method:
+Given a serializer for the serializable model:
 
 ```ruby
-class PostSerializer < ActiveModel::Serializer
-  embed :ids
-
-  attributes :id, :title, :body
-  has_many :comments
+class SomeSerializer < ActiveModel::Serializer
+  attribute :title, key: :name
+  attributes :body
 end
 ```
 
-Now, any associations will be supplied as an Array of IDs:
-
-```json
-{
-  "post": {
-    "id": 1,
-    "title": "New post",
-    "body": "A body!",
-    "comment_ids": [ 1, 2, 3 ]
-  }
-}
-```
-
-You may also choose to embed the IDs by the association's name underneath an
-`embed_key` for the resource. For example, say we want to change `comment_ids`
-to `comments` underneath a `links` key:
+The model can be serialized as:
 
 ```ruby
-class PostSerializer < ActiveModel::Serializer
-  attributes :id, :title, :body
-
-  has_many :comments, embed: ids, embed_namespace: :links
-end
+options = {}
+serialization = ActiveModelSerializers::SerializableResource.new(resource, options)
+serialization.to_json
+serialization.as_json
 ```
 
-The JSON will look like this:
-
-```json
-{
-  "post": {
-    "id": 1,
-    "title": "New post",
-    "body": "A body!",
-    "links": {
-      "comments": [ 1, 2, 3 ]
-    }
-  }
-}
-```
-
-Alternatively, you can choose to embed only the ids or the associated objects per association:
+SerializableResource delegates to the adapter, which it builds as:
 
 ```ruby
-class PostSerializer < ActiveModel::Serializer
-  attributes :id, :title, :body
-
-  has_many :comments, embed: :objects
-  has_many :tags, embed: :ids
-end
+adapter_options = {}
+adapter = ActiveModelSerializers::Adapter.create(serializer, adapter_options)
+adapter.to_json
+adapter.as_json
+adapter.serializable_hash
 ```
 
-The JSON will look like this:
-
-```json
-{
-  "post": {
-    "id": 1,
-    "title": "New post",
-    "body": "A body!",
-    "comments": [
-      { "id": 1, "body": "what a dumb post" }
-    ],
-    "tag_ids": [ 1, 2, 3 ]
-  }
-}
-```
-
-In addition to supplying an Array of IDs, you may want to side-load the data
-alongside the main object. This makes it easier to process the entire package
-of data without having to recursively scan the tree looking for embedded
-information. It also ensures that associations that are shared between several
-objects (like tags), are only delivered once for the entire payload.
-
-You can specify that the data be included like this:
+The adapter formats the serializer's attributes and associations (a.k.a. includes):
 
 ```ruby
-class PostSerializer < ActiveModel::Serializer
-  embed :ids, include: true
-
-  attributes :id, :title, :body
-  has_many :comments
-end
+serializer_options = {}
+serializer = SomeSerializer.new(resource, serializer_options)
+serializer.attributes
+serializer.associations
 ```
 
-Assuming that the comments also `has_many :tags`, you will get a JSON like
-this:
-
-```json
-{
-  "post": {
-    "id": 1,
-    "title": "New post",
-    "body": "A body!",
-    "comment_ids": [ 1, 2 ]
-  },
-  "comments": [
-    { "id": 1, "body": "what a dumb post", "tag_ids": [ 1, 2 ] },
-    { "id": 2, "body": "i liked it", "tag_ids": [ 1, 3 ] },
-  ],
-  "tags": [
-    { "id": 1, "name": "short" },
-    { "id": 2, "name": "whiny" },
-    { "id": 3, "name": "happy" }
-  ]
-}
-```
+## Architecture
 
-If you would like to namespace association JSON underneath a certain key in
-the root document (say, `linked`), you can specify an `embed_in_root_key`:
+This section focuses on architecture the 0.10.x version of ActiveModelSerializers. If you are interested in the architecture of the 0.8 or 0.9 versions,
+please refer to the [0.8 README](https://github.com/rails-api/active_model_serializers/blob/0-8-stable/README.md) or
+[0.9 README](https://github.com/rails-api/active_model_serializers/blob/0-9-stable/README.md).
 
-```ruby
-class PostSerializer < ActiveModel::Serializer
-  embed: ids, include: true, embed_in_root_key: :linked
+The original design is also available [here](https://github.com/rails-api/active_model_serializers/blob/d72b66d4c5355b0ff0a75a04895fcc4ea5b0c65e/README.textile).
 
-  attributes: :id, :title, :body
-  has_many :comments, :tags
-end
-```
+### ActiveModel::Serializer
 
-The above would yield the following JSON document:
-
-```json
-{
-  "post": {
-    "id": 1,
-    "title": "New post",
-    "body": "A body!",
-    "comment_ids": [ 1, 2 ]
-  },
-  "linked": {
-    "comments": [
-      { "id": 1, "body": "what a dumb post", "tag_ids": [ 1, 2 ] },
-      { "id": 2, "body": "i liked it", "tag_ids": [ 1, 3 ] },
-    ],
-    "tags": [
-      { "id": 1, "name": "short" },
-      { "id": 2, "name": "whiny" },
-      { "id": 3, "name": "happy" }
-    ]
-  }
-}
-```
+An **`ActiveModel::Serializer`** wraps a [serializable resource](https://github.com/rails/rails/blob/master/activemodel/lib/active_model/serialization.rb)
+and exposes an `attributes` method, among a few others.
+It allows you to specify which attributes and associations should be represented in the serializatation of the resource.
+It requires an adapter to transform its attributes into a JSON document; it cannot be serialized itself.
+It may be useful to think of it as a
+[presenter](https://blog.steveklabnik.com/posts/2011-09-09-better-ruby-presenters).
 
-When side-loading data, your serializer cannot have the `{ root: false }` option, 
-as this would lead to invalid JSON. If you do not have a root key, the `include` 
-instruction will be ignored
+#### ActiveModel::CollectionSerializer
 
-You can also specify a different root for the embedded objects than the key
-used to reference them:
+The **`ActiveModel::CollectionSerializer`** represents a collection of resources as serializers
+and, if there is no serializer, primitives.
 
-```ruby
-class PostSerializer < ActiveModel::Serializer
-  embed :ids, include: true
-
-  attributes :id, :title, :body
-  has_many :comments, key: :comment_ids, root: :comment_objects
-end
-```
-
-This would generate JSON that would look like this:
-
-```json
-{
-  "post": {
-    "id": 1,
-    "title": "New post",
-    "body": "A body!",
-    "comment_ids": [ 1 ]
-  },
-  "comment_objects": [
-    { "id": 1, "body": "what a dumb post" }
-  ]
-}
-```
-
-You can also specify a different attribute to use rather than the ID of the
-objects:
+### ActiveModelSerializers::Adapter::Base
 
-```ruby
-class PostSerializer < ActiveModel::Serializer
-  embed :ids, include: true
-
-  attributes :id, :title, :body
-  has_many :comments, embed_key: :external_id
-end
-```
-
-This would generate JSON that would look like this:
-
-```json
-{
-  "post": {
-    "id": 1,
-    "title": "New post",
-    "body": "A body!",
-    "comment_ids": [ "COMM001" ]
-  },
-  "comments": [
-    { "id": 1, "external_id": "COMM001", "body": "what a dumb post" }
-  ]
-}
-```
+The **`ActiveModelSerializers::Adapter::Base`** describes the structure of the JSON document generated from a
+serializer. For example, the `Attributes` example represents each serializer as its
+unmodified attributes.  The `JsonApi` adapter represents the serializer as a [JSON
+API](https://jsonapi.org/) document.
 
-**NOTE**: The `embed :ids` mechanism is primary useful for clients that process
-data in bulk and load it into a local store. For these clients, the ability to
-easily see all of the data per type, rather than having to recursively scan the
-data looking for information, is extremely useful.
+### ActiveModelSerializers::SerializableResource
 
-If you are mostly working with the data in simple scenarios and manually making
-Ajax requests, you probably just want to use the default embedded behavior.
+The **`ActiveModelSerializers::SerializableResource`** acts to coordinate the serializer(s) and adapter
+to an object that responds to `to_json`, and `as_json`.  It is used in the controller to
+encapsulate the serialization resource when rendered. However, it can also be used on its own
+to serialize a resource outside of a controller, as well.
 
-## Customizing Scope
+### Primitive handling
 
-In a serializer, `current_user` is the current authorization scope which the controller
-provides to the serializer when you call `render :json`. By default, this is
-`current_user`, but can be customized in your controller by calling
-`serialization_scope`:
+Definitions: A primitive is usually a String or Array. There is no serializer
+defined for them; they will be serialized when the resource is converted to JSON (`as_json` or
+`to_json`).  (The below also applies for any object with no serializer.)
 
-```ruby
-class ApplicationController < ActionController::Base
-  serialization_scope :current_admin
-end
-```
+- ActiveModelSerializers doesn't handle primitives passed to `render json:` at all.
 
-The above example will also change the scope from `current_user` to
-`current_admin`.
+Internally, if no serializer can be found in the controller, the resource is not decorated by
+ActiveModelSerializers.
 
-Please note that, until now, `serialization_scope` doesn't accept a second
-object with options for specifying which actions should or should not take a
-given scope in consideration.
+- However, when a primitive value is an attribute or in a collection, it is not modified.
 
-To be clear, it's not possible, yet, to do something like this:
+When serializing a collection and the collection serializer (CollectionSerializer) cannot
+identify a serializer for a resource in its collection, it throws [`:no_serializer`](https://github.com/rails-api/active_model_serializers/issues/1191#issuecomment-142327128).
+For example, when caught by `Reflection#build_association`, and the association value is set directly:
 
 ```ruby
-class SomeController < ApplicationController
-  serialization_scope :current_admin, except: [:index, :show]
-end
+reflection_options[:virtual_value] = association_value.try(:as_json) || association_value
 ```
 
-So, in order to have a fine grained control of what each action should take in
-consideration for its scope, you may use something like this:
+(which is called by the adapter as `serializer.associations(*)`.)
 
-```ruby
-class CitiesController < ApplicationController
-  serialization_scope nil
-
-  def index
-    @cities = City.all
+### How options are parsed
 
-    render json: @cities, each_serializer: CitySerializer
-  end
+High-level overview:
 
-  def show
-    @city = City.find(params[:id])
+- For a **collection**
+  - `:serializer` specifies the collection serializer and
+  - `:each_serializer` specifies the serializer for each resource in the collection.
+- For a **single resource**, the `:serializer` option is the resource serializer.
+- Options are partitioned in serializer options and adapter options.  Keys for adapter options are specified by
+    [`ADAPTER_OPTION_KEYS`](lib/active_model_serializers/serializable_resource.rb#L5).
+    The remaining options are serializer options.
 
-    render json: @city, scope: current_admin
-  end
-end
-```
+Details:
 
-Assuming that the `current_admin` method needs to make a query in the database
-for the current user, the advantage of this approach is that, by setting
-`serialization_scope` to `nil`, the `index` action no longer will need to make
-that query, only the `show` action will.
+1. **ActionController::Serialization**
+  1. `serializable_resource = ActiveModelSerializers::SerializableResource.new(resource, options)`
+    1. `options` are partitioned into `adapter_opts` and everything else (`serializer_opts`).
+      The `adapter_opts` keys are defined in [`ActiveModelSerializers::SerializableResource::ADAPTER_OPTION_KEYS`](lib/active_model_serializers/serializable_resource.rb#L5).
+1. **ActiveModelSerializers::SerializableResource**
+  1. `if serializable_resource.serializer?` (there is a serializer for the resource, and an adapter is used.)
+    - Where `serializer?` is `use_adapter? && !!(serializer)`
+      - Where `use_adapter?`: 'True when no explicit adapter given, or explicit value is truthy (non-nil);
+        False when explicit adapter is falsy (nil or false)'
+      - Where `serializer`:
+        1. from explicit `:serializer` option, else
+        2. implicitly from resource `ActiveModel::Serializer.serializer_for(resource)`
+  1. A side-effect of checking `serializer` is:
+     - The `:serializer` option is removed from the serializer_opts hash
+     - If the `:each_serializer` option is present, it is removed from the serializer_opts hash and set as the `:serializer` option
+  1. The serializer and adapter are created as
+    1. `serializer_instance = serializer.new(resource, serializer_opts)`
+    2. `adapter_instance = ActiveModel::Serializer::Adapter.create(serializer_instance, adapter_opts)`
+1. **ActiveModel::Serializer::CollectionSerializer#new**
+  1. If the `serializer_instance` was a `CollectionSerializer` and the `:serializer` serializer_opts
+    is present, then [that serializer is passed into each resource](https://github.com/rails-api/active_model_serializers/blob/0-10-stable/lib/active_model/serializer/collection_serializer.rb#L77-L79).
+1. **ActiveModel::Serializer#attributes** is used by the adapter to get the attributes for
+  resource as defined by the serializer.
 
-## Testing
+(In Rails, the `options` are also passed to the `as_json(options)` or `to_json(options)`
+methods on the resource serialization by the Rails JSON renderer.  They are, therefore, important
+to know about, but not part of ActiveModelSerializers.)
 
-In order to test a Serializer, you can just call `.new` on it, passing the object to serialize:
+### What does a 'serializable resource' look like?
 
-### MiniTest
+- An `ActiveRecord::Base` object.
+- Any Ruby object that passes the
+  [Lint](https://www.rubydoc.info/gems/active_model_serializers/ActiveModel/Serializer/Lint/Tests)
+  [(code)](lib/active_model/serializer/lint.rb).
 
-```ruby
-class TestPostSerializer < Minitest::Test
-  def setup
-    @serializer = PostSerializer.new Post.new(id: 123, title: 'some title', body: 'some text')
-  end
-
-  def test_special_json_for_api
-    assert_equal '{"post":{"id":123,"title":"some title","body":"some text"}}', @serializer.to_json
-  end
-```
+ActiveModelSerializers provides a
+[`ActiveModelSerializers::Model`](lib/active_model_serializers/model.rb),
+which is a simple serializable PORO (Plain-Old Ruby Object).
 
-### RSpec
+`ActiveModelSerializers::Model` may be used either as a reference implementation, or in production code.
 
 ```ruby
-describe PostSerializer do
-  it "creates special JSON for the API" do
-    serializer = PostSerializer.new Post.new(id: 123, title: 'some title', body: 'some text')
-    expect(serializer.to_json).to eql('{"post":{"id":123,"title":"some title","body":"some text"}}')
-  end
+class MyModel < ActiveModelSerializers::Model
+  attributes :id, :name, :level
 end
 ```
 
-## Caching
-
-NOTE: This functionality was removed from AMS and it's in the TODO list.
-We need to re-think and re-design the caching strategy for the next
-version of AMS.
+The default serializer for `MyModel` would be `MyModelSerializer` whether MyModel is an
+ActiveRecord::Base object or not.
 
-To cache a serializer, call `cached` and define a `cache_key` method:
+Outside of the controller the rules are **exactly** the same as for records. For example:
 
 ```ruby
-class PostSerializer < ActiveModel::Serializer
-  cached  # enables caching for this serializer
-
-  attributes :title, :body
-
-  def cache_key
-    [object, scope]
-  end
-end
+render json: MyModel.new(level: 'awesome'), adapter: :json
 ```
 
-The caching interface uses `Rails.cache` under the hood.
-
-# ApplicationSerializer
-
-By default, new serializers descend from ActiveModel::Serializer. However, if you wish to share behaviour across your serializers you can create an ApplicationSerializer at ```app/serializers/application_serializer.rb```:
+would be serialized the same as
 
 ```ruby
-class ApplicationSerializer < ActiveModel::Serializer
-end
-```
-
-Any newly generated serializers will automatically descend from ApplicationSerializer.
-
+ActiveModelSerializers::SerializableResource.new(MyModel.new(level: 'awesome'), adapter: :json).as_json
 ```
-$ rails g serializer post
-```
-
-now generates:
-
-```ruby
-class PostSerializer < ApplicationSerializer
-  attributes :id
-end
-````
-
-# Design and Implementation Guidelines
 
-## Keep it Simple
+## Semantic Versioning
 
-`ActiveModel::Serializers` is capable of producing complex JSON views/large object
-trees, and it may be tempting to design in this way so that your client can make
-fewer requests to get data and so that related querying can be optimized.
-However, keeping things simple in your serializers and controllers may
-significantly reduce complexity and maintenance over the long-term development
-of your application. Please consider reducing the complexity of the JSON views
-you provide via the serializers as you build out your application, so that
-controllers/services can be more easily reused without a lot of complexity
-later.
+This project adheres to [semver](https://semver.org/)
 
-## Performance
+## Contributing
 
-As you develop your controllers or other code that utilizes serializers, try to
-avoid n+1 queries by ensuring that data loads in an optimal fashion, e.g. if you
-are using ActiveRecord, you might want to use query includes or joins as needed
-to make the data available that the serializer(s) need.
+See [CONTRIBUTING.md](CONTRIBUTING.md)