active_model_serializers/docs/general/configuration_options.md

Back to Guides

Configuration Options

The following configuration options can be set on ActiveModelSerializers.config, preferably inside an initializer.

General

adapter

The adapter to use.

Possible values:

• :attributes (default)
• :json
• :json_api

serializer_lookup_enabled

Enable automatic serializer lookup.

Possible values:

• true (default)
• false

When false, serializers must be explicitly specified.

key_transform

The key transform to use.

Option	Result
:camel	ExampleKey
:camel_lower	exampleKey
:dash	example-key
:unaltered	the original, unaltered key
:underscore	example_key
nil	use the adapter default

Each adapter has a default key transform configured:

Adapter	Default Key Transform
Attributes	:unaltered
Json	:unaltered
JsonApi	:dash

config.key_transform is a global override of the adapter default. Adapters still prefer the render option :key_transform over this setting.

NOTE: Key transforms can be expensive operations. If key transforms are unnecessary for the application, setting config.key_transform to :unaltered will provide a performance boost.

default_includes

What relationships to serialize by default. Default: '*', which includes one level of related objects. See includes for more info.

serializer_lookup_chain

Configures how serializers are searched for. By default, the lookup chain is

ActiveModelSerializers::LookupChain::DEFAULT

which is shorthand for

[
  ActiveModelSerializers::LookupChain::BY_PARENT_SERIALIZER,
  ActiveModelSerializers::LookupChain::BY_NAMESPACE,
  ActiveModelSerializers::LookupChain::BY_RESOURCE_NAMESPACE,
  ActiveModelSerializers::LookupChain::BY_RESOURCE
]

Each of the array entries represent a proc. A serializer lookup proc will be yielded 3 arguments. resource_class, serializer_class, and namespace.

Note that:

• resource_class is the class of the resource being rendered
• by default serializer_class is ActiveModel::Serializer
  • for association lookup it's the "parent" serializer
• namespace correspond to either the controller namespace or the [optionally] specified namespace render option

An example config could be:

ActiveModelSerializers.config.serializer_lookup_chain = [
  lambda do |resource_class, serializer_class, namespace|
    "API::#{namespace}::#{resource_class}"
  end
]

If you simply want to add to the existing lookup_chain. Use unshift.

ActiveModelSerializers.config.serializer_lookup_chain.unshift(
  lambda do |resource_class, serializer_class, namespace|
    # ...
  end
)

See lookup_chain.rb for further explanations and examples.

use_sha1_digests

Determines which hashing algorithm to use internally when caching serializers.

Possible values:

• true
• false (default)

When true, ActiveModelSerializers will use SHA1. Otherwise, it will default to using MD5. Be warned that changing this value may result in serializer caches being invalidated.

JSON API

jsonapi_resource_type

Sets whether the type of the resource should be singularized or pluralized when it is not explicitly specified by the serializer

Possible values:

• :singular
• :plural (default)

jsonapi_namespace_separator

Sets separator string for namespaced models to render type attribute.

Separator	Example: Admin::User
'-' (default)	'admin-users'
'--' (recommended)	'admin--users'

See Recommendation for dasherizing (kebab-case-ing) namespaced object, such as Admin::User for more discussion.

jsonapi_include_toplevel_object

Include a top level jsonapi member in the response document.

Possible values:

• true
• false (default)

jsonapi_version

The latest version of the spec to which the API conforms.

Default: '1.0'.

Used when jsonapi_include_toplevel_object is true

jsonapi_toplevel_meta

Optional top-level metadata. Not included if empty.

Default: {}.

Used when jsonapi_include_toplevel_object is true

jsonapi_use_foreign_key_on_belongs_to_relationship

When true, the relationship will determine its resource object identifier without calling the association or its serializer. This can be useful when calling the association object is triggering unnecessary queries.

For example, if a comment belongs to a post, and the comment uses the foreign key post_id, we can determine the resource object identifier id as comment.post_id and the type from the association options. Or quite simply, it behaves as belongs_to :post, type: :posts, foreign_key: :post_id.

Note: This option has no effect on polymorphic associations as we cannot reliably determine the associated object's type without instantiating it.

Default: false.

Hooks

To run a hook when ActiveModelSerializers is loaded, use ActiveSupport.on_load(:action_controller) do end