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.

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

Hooks

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