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

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