active_model_serializers 0.9.9 → 0.10.14

data/README.md

@@ -1,956 +1,304 @@
-[![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://github.com/rails-api/active_model_serializers/actions"><img src="https://github.com/rails-api/active_model_serializers/actions/workflows/ci.yml/badge.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>
+    </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 `@serialization_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
-```
-
-### Use serialization outside of ActionController::Base
-
-When controller does not inherit from ActionController::Base,
-include Serialization module manually:
-
-```ruby
-class ApplicationController < ActionController::API
-  include ActionController::Serialization
-end
-```
-
-## 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)
-```
-
-## Changing the default association key type
-
-You can specify that serializers use unsuffixed names as association keys by default.
-
-```ruby
-ActiveModel::Serializer.setup do |config|
-  config.default_key_type = :name
-end
-```
-
-This will build association keys like `comments` or `author` instead of `comment_ids` or `author_id`.
-
-## 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
-
-Once you have a serializer, you can specify which attributes and associations
-you would like to include in the serialized form.
-
-```ruby
-class PostSerializer < ActiveModel::Serializer
-  attributes :id, :title, :body
-  has_many :comments
-end
-```
+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.
 
-## Attributes
+`0.10.x` is **not** backward compatible with `0.9.x` nor `0.8.x`.
 
-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.
+`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)
 
-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:
+## Installation
 
-```ruby
-class PersonSerializer < ActiveModel::Serializer
-  attributes :first_name, :last_name, :full_name
+Add this line to your application's Gemfile:
 
-  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
-  attributes :version_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).
+And then execute:
 
-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:
-
-```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.
-
-### Alias Attribute
-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_object: { 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
-```
+- [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)
 
-## 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.
+## High-level behavior
 
-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).
+Choose an adapter from [adapters](lib/active_model_serializers/adapter):
 
-```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
+``` ruby
+ActiveModelSerializers.config.adapter = :json_api # Default: `:attributes`
 ```
 
-As with attributes, you can change the JSON key that the serializer should
-use for a particular association.
+Given a [serializable model](lib/active_model/serializer/lint.rb):
 
 ```ruby
-class PostSerializer < ActiveModel::Serializer
-  attributes :id, :title, :body
-
-  # look up comments, but use +my_comments+ as the key in JSON
-  has_many :comments, root: :my_comments
+# either
+class SomeResource < ActiveRecord::Base
+  # columns: title, body
 end
-```
-
-Also, as with attributes, serializers will execute a filter method to
-determine which associations should be included in the output. For
-example:
-
-```ruby
-class PostSerializer < ActiveModel::Serializer
-  attributes :id, :title, :body
-  has_many :comments
-
-  def filter(keys)
-    keys.delete :comments if object.comments_disabled?
-    keys
-  end
-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
-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.:
-
-```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.
-
-## 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" }
-    ]
-  }
-}
-```
-
-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:
-
-```ruby
-class PostSerializer < ActiveModel::Serializer
-  embed :ids
-
-  attributes :id, :title, :body
-  has_many :comments
-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 a
-`key` for the resource. For example, say we want to change `comment_ids`
-to `comments` underneath a `links` key:
-
-```ruby
-class PostSerializer < ActiveModel::Serializer
-  attributes :id, :title, :body
-
-  has_many :comments, embed: :ids, key: :comments, embed_namespace: :links
+# or
+class SomeResource < ActiveModelSerializers::Model
+  attributes :title, :body
 end
 ```
 
-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:
+And initialized as:
 
 ```ruby
-class PostSerializer < ActiveModel::Serializer
-  attributes :id, :title, :body
-
-  has_many :comments, embed: :objects
-  has_many :tags, embed: :ids
-end
-```
-
-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 ]
-  }
-}
+resource = SomeResource.new(title: 'ActiveModelSerializers', body: 'Convention over configuration')
 ```
 
-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:
+Given a serializer for the serializable model:
 
 ```ruby
-class PostSerializer < ActiveModel::Serializer
-  embed :ids, include: true
-
-  attributes :id, :title, :body
-  has_many :comments
+class SomeSerializer < ActiveModel::Serializer
+  attribute :title, key: :name
+  attributes :body
 end
 ```
 
-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" }
-  ]
-}
-```
-
-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`:
+The model can be serialized as:
 
 ```ruby
-class PostSerializer < ActiveModel::Serializer
-  embed :ids, include: true, embed_in_root_key: :linked
-
-  attributes: :id, :title, :body
-  has_many :comments, :tags
-end
-```
-
-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" }
-    ]
-  }
-}
+options = {}
+serialization = ActiveModelSerializers::SerializableResource.new(resource, options)
+serialization.to_json
+serialization.as_json
 ```
 
-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
-
-You can also specify a different root for the embedded objects than the key
-used to reference them:
+SerializableResource delegates to the adapter, which it builds as:
 
 ```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" }
-  ]
-}
+adapter_options = {}
+adapter = ActiveModelSerializers::Adapter.create(serializer, adapter_options)
+adapter.to_json
+adapter.as_json
+adapter.serializable_hash
 ```
 
-You can also specify a different attribute to use rather than the ID of the
-objects:
+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, key: :external_id
-end
+serializer_options = {}
+serializer = SomeSerializer.new(resource, serializer_options)
+serializer.attributes
+serializer.associations
 ```
 
-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" }
-  ]
-}
-```
+## Architecture
 
-**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.
+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).
 
-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 original design is also available [here](https://github.com/rails-api/active_model_serializers/blob/d72b66d4c5355b0ff0a75a04895fcc4ea5b0c65e/README.textile).
 
+### ActiveModel::Serializer
 
-## Embedding Polymorphic Associations
+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).
 
-Because we need both the id and the type to be able to identify a polymorphic associated model, these are serialized in a slightly different format than common ones.
+#### ActiveModel::CollectionSerializer
 
-When embedding entire objects:
+The **`ActiveModel::CollectionSerializer`** represents a collection of resources as serializers
+and, if there is no serializer, primitives.
 
-```ruby
-class PostSerializer < ActiveModel::Serializer
-  attributes :id, :title
-  has_many :attachments, polymorphic: true
-end
-```
-
-```json
-{
-  "post": {
-    "id": 1,
-    "title": "New post",
-    "attachments": [
-      {
-        "type": "image",
-        "image": {
-          "id": 3,
-          "name": "logo",
-          "url": "http://images.com/logo.jpg"
-        }
-      },
-      {
-        "type": "video",
-        "video": {
-          "id": 12,
-          "uid": "XCSSMDFWW",
-          "source": "youtube"
-        }
-      }
-    ]
-  }
-}
-```
-
-When embedding ids:
-
-```ruby
-class PostSerializer < ActiveModel::Serializer
-  embed :ids
+### ActiveModelSerializers::Adapter::Base
 
-  attributes :id, :title
-  has_many :attachments, polymorphic: true
-end
-```
+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.
 
-```json
-{
-  "post": {
-    "id": 1,
-    "title": "New post",
-    "attachment_ids": [
-      {
-        "type": "image",
-        "id": 12
-      },
-      {
-        "type": "video",
-        "id": 3
-      }
-    ]
-  }
-}
-```
+### ActiveModelSerializers::SerializableResource
 
+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:
-
-```ruby
-class CitiesController < ApplicationController
-  serialization_scope nil
+(which is called by the adapter as `serializer.associations(*)`.)
 
-  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)