docs/general/configuration_options

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