Blueprinter

NOTE This is a WIP for API V2!

Blueprinter is a JSON serializer for your business objects. It is designed to be simple, flexible, and performant.

Upgrading from 1.x? Read the upgrade guide!

Installation

bundle add blueprinter

See rubydoc.info/gems/blueprinter for generated API documentation.

Blueprinter DSL

Define your base class

Define an ApplicationBlueprint for your blueprints to inherit from. Any global configuration goes here: common fields, views, partials, formatters, extensions, and options.

class ApplicationBlueprint < Blueprinter::Blueprint
  extensions << MyExtension.new
  options[:exclude_if_nil] = true
  field :id
end

Define blueprints for your models

This blueprint inherits everything from ApplicationBlueprint, then adds a name field and two associations that will render using other blueprints.

class WidgetBlueprint < ApplicationBlueprint
  field :name
  object :category, CategoryBlueprint
  collection :parts, PartBlueprint
end

There's a lot more you can do with the Blueprinter DSL. Fields are a good place to start!

Fields

# Use field for scalar values, arrays of scalar values, or even a Hash
field :name
field :tags

# Add multiple fields at once
fields :description, :price

# Use object to render an object or Hash using another blueprint
object :category, CategoryBlueprint

# Use collection to render an array-like collection of objects
collection :parts, PartBlueprint

Options

Fields accept a wide array of built-in options, and extensions can define even more. Find all built-in options here.

field :description, default: "No description"
collection :parts, PartBlueprint, exclude_if_empty: true

Extracting field values

Blueprinter is pretty smart about extracting field values from objects, but there are ways to customize the behavior if needed.

Default behavior

For Hashes, Blueprinter will look for a key matching the field name - first with a Symbol, then a String.
For anything else, Blueprinter will look for a public method matching the field name.
The from field option can be used to specify a different method or Hash key name.

Field blocks

Return whatever you want from a block. It will be passed a Field context argument containing the object being rendered, among other things.

field :description do |ctx|
  ctx.object.description.upcase
end

# Blocks can call instance methods defined on your Blueprint
collection :parts, PartBlueprint do |ctx|
  active_parts ctx.object
end

def active_parts(object)
  object.parts.select(&:active?)
end

Custom extractors

Define your own extraction behavior with a custom extractor.

# For an entire Blueprint or view
extensions << MyCustomExtractor.new

# For a single field
object :bar, extractor: MyCustomExtractor

Views

Blueprints can define views to provide different representations of the data. A view inherits everything from its parent but is free to override as needed. In addition to fields, views can define options, partials, formatters, extensions, and nested views.

class WidgetBlueprint < ApplicationBlueprint
  field :name
  object :category, CategoryBlueprint

  # The "with_parts" view inherits from "default" and adds a collection of parts
  view :with_parts do
    collection :parts, PartBlueprint
  end

  # Views can include other views
  view :full do
    use :with_parts
    field :description
  end
end

At the top level of every Blueprint is an implicit view called default. The default view is used when no other is specified. All other views in the Blueprint inherit from it.

Nesting views

You can nest views within views, allowing for a hierarchy of inheritance.

class WidgetBlueprint < ApplicationBlueprint
  field :name
  object :category, CategoryBlueprint

  view :extended do
    field :description
    collection :parts, PartBlueprint

    # The "extended.with_price" view adds a price field
    view :with_price do
      field :price
    end
  end

Excluding fields

Views can exclude select fields from parents, views they've included, or from partials.

class WidgetBlueprint < ApplicationBlueprint
  fields :name, :description, :price

  view :minimal do
    exclude :description, :price
  end
end

You can exclude and and all parent fields by creating an empty view:

class WidgetBlueprint < ApplicationBlueprint
  fields :name, :description, :price

  view :minimal, empty: true do
    field :the_only_field
  end
end

Referencing views

When defining an association, you can choose a view from its blueprint:

object :widget, WidgetBlueprint[:extended]

Nested views can be accessed with a dot syntax or a nested Hash syntax.

collection :widgets, WidgetBlueprint["extended.with_price"]
collection :widgets, WidgetBlueprint[:extended][:with_price]

Inheriting from views

You can inherit from another blueprint, or from one of its views:

class WidgetBlueprint < ApplicationBlueprint[:with_timestamps]
  # ...
end

Partials

Partials allow you to compose views from reusable components. Just like views, partials can define fields, options, views, other partials, formatters, and extensions.

class WidgetBlueprint < ApplicationBlueprint
  field :name

  view :foo do
    use :associations
    field :foo
  end

  view :bar do
    use :associations, :description
    field :bar
  end

  partial :associations do
    object :category, CategoryBlueprint
    collection :parts, PartBlueprint
  end

  partial :description do
    field :description
  end
end

There are two ways of including partials: appending with 'use' and inserting with 'use!' (see examples).

Append with 'use'

Partials are appended to your view, giving them the opportunity to override your view's fields, options, etc. Precedence (highest to lowest) is:

Definitions in the partial
Definitions in the view
Definitions inherited from the blueprint/parent views

Insert with 'use!'

Partials are embedded immediately, on that line, allowing subsequent lines to override the partial. Precedence (highest to lowest) is:

Definitions in the view after use!
Definitions in the partial
Definitions in the view before use!
Definitions inherited from the blueprint/parent views

Examples of 'use' and 'use!'

partial :no_empty_fields do
  options[:field_if] = :og_field_logic
  # other stuff
end

# :foo appends the partial, so it overrides the view's field_if
view :foo do
  use :no_empty_fields
  options[:field_if] = :other_field_logic
end

# :bar inserts the partial, but the next line overrides the partial's field_if
view :bar do
  use! :no_empty_fields
  options[:field_if] = :other_field_logic
end

Formatters

Declaratively format field values by class. You can define formatters anywhere in your blueprints: top level, views, and partials.

class WidgetBlueprint < ApplicationBlueprint
  # Strip whitespace from all strings
  format(String) { |val| val.strip }

  # Format all dates and times using ISO-8601
  format Date, :iso8601
  format Time, :iso8601

  def iso8601(val)
    val.iso8601
  end
end

Options

Numerous options can be defined on Blueprints, views, partials, or individual fields. Some can also be passed to render.

class WidgetBlueprint < ApplicationBlueprint
  # Blueprint options apply to all fields, associations, views, and partials in
  # the Blueprint. They are inherited from the parent class but can be overridden.
  options[:exclude_if_empty] = true

  # Field options apply to individual fields or associations. They can override
  # Blueprint options.
  field :name, exclude_if_empty: false

  # Options in views apply to all fields, associations, partials and nested views
  # in the view. They inherit options from the Blueprint, or from parent views,
  # and can override them.
  view :foo do
    options[:exclude_if_empty] = false
  end

  # Options in partials apply to all fields, associations, views, and partials in
  # the partial. All of these are applied to the views that use the partial.
  partial :bar do
    options[:exclude_if_empty] = false
  end

  # Some options accept Procs/labmdas. These can call instance methods defined on
  # your Blueprint. Or you can pass a method name as a symbol.
  field :foo, if: ->(ctx) { long_complex_check? ctx }
  field :bar, if: :long_complex_check?

  def long_complex_check?(ctx)
    # ...
  end
end

# Passing a supported option to render will override what's in the blueprint
WidgetBlueprint.render(widget, exclude_if_empty: false).to_json

For easier reference, options are grouped into the following categories:

Default values: Provide defaults for empty fields
Conditional fields: Exclude fields based on conditions
Field mapping: Change how field values are extracted from objects
Metadata: Wrap or add metadata to the output

A note about context objects

Options that accept Procs, lambdas, or method names are usually passed a Field context argument. It contains the object being rendered as well as other useful information.

Default Values

These options allow you to set default values for fields and associations, and customize when they're used.

default

A default value used when the field or assocation is nil.

Available in field, object, collection
@param Field context

field :foo, default: "Foo"
field :foo, default: ->(ctx) { "Foo" }
field :foo, default: :foo

def foo(ctx) = "Foo"

field_default

Default value for any nil non-association field in its scope.

Available in blueprint, view, partial, render
@param Field context

options[:field_default] = "Foo"
options[:field_default] = ->(ctx) { "Foo" }
options[:field_default] = :foo

def foo(ctx) = "Foo"

WidgetBluerpint.render(widget, field_default: "Foo").to_json

object_default

Default value for any nil object field in its scope.

Available in blueprint, view, partial, render
@param Field context

options[:object_default] = { name: "Foo" }
options[:object_default] = ->(ctx) { { name: "Foo" } }
options[:object_default] = :foo

def foo(ctx) = { name: "Foo" }

WidgetBluerpint.render(widget, object_default: { name: "Foo" }).to_json

collection_default

Default value for any nil collection field.

Available in blueprint, view, partial, render
@param Field context

options[:collection_default] = [{ name: "Foo" }]
options[:collection_default] = ->(ctx) { [{ name: "Foo" }] }
options[:collection_default] = :foo

def foo(ctx) = [{ name: "Foo" }]

WidgetBluerpint.render(widget, collection_default: [{ name: "Foo" }]).to_json

default_if

Use the default value if the given Proc or method name returns truthy.

Available in field, object, collection
@param Field context

field :foo, default: "Foo", default_if: ->(ctx) { ctx.object.disabled? }
field :foo, default: "Foo", default_if: :disabled?

def disabled?(ctx) = ctx.object.disabled?

field_default_if

Same as default_if, but applies to any non-association field in scope.

Available in blueprint, view, partial, render
@param Field context

options[:field_default_if] = ->(ctx) { ctx.object.disabled? }
options[:field_default_if] = :disabled?

def disabled?(ctx) = ctx.object.disabled?

WidgetBluerpint.render(widget, field_default_if: :disabled?).to_json

object_default_if

Same as default_if, but applies to any object field in scope.

Available in blueprint, view, partial, render
@param Field context

options[:object_default_if] = ->(ctx) { ctx.object.disabled? }
options[:object_default_if] = :disabled?

def disabled?(ctx) = ctx.object.disabled?

WidgetBluerpint.render(widget, object_default_if: :disabled?).to_json

collection_default_if

Same as default_if, but applies to any collection field in scope.

Available in blueprint, view, partial, render
@param Field context

options[:collection_default_if] = ->(ctx) { ctx.object.disabled? }
options[:collection_default_if] = :disabled?

def disabled?(ctx) = ctx.object.disabled?

WidgetBluerpint.render(widget, collection_default_if: :disabled?).to_json

Conditional Fields

These options allow you to exclude fields from the output.

exclude_if_nil

Exclude fields if they're nil.

Available in blueprint, view, partial, field, object, collection, render

options[:exclude_if_nil] = true

field :description, exclude_if_nil: true

WidgetBluerpint.render(widget, exclude_if_nil: true).to_json

exclude_if_empty

Exclude fields if they're nil, or if they respond to empty? and it returns true.

Available in blueprint, view, partial, field, object, collection, render

options[:exclude_if_empty] = true

field :description, exclude_if_empty: true

WidgetBluerpint.render(widget, exclude_if_empty: true).to_json

if

Only include the field if the given Proc or method name returns truthy.

Available in field, object, collection
@param Field context

field :foo, if: ->(ctx) { ctx.object.enabled? }
field :foo, if: :enabled?

def enabled?(ctx) = ctx.object.enabled?

field_if

Only include non-association fields if the given Proc or method name returns truthy.

Available in blueprint, view, partial, render
@param Field context

options[:field_if] = ->(ctx) { ctx.object.enabled? }
options[:field_if] = :enabled?

def enabled?(ctx) = ctx.object.enabled?

WidgetBluerpint.render(widget, field_if: :enabled?).to_json

object_if

Only include object fields if the given Proc or method name returns truthy.

Available in blueprint, view, partial, render
@param Field context

options[:object_if] = ->(ctx) { ctx.object.enabled? }
options[:object_if] = :enabled?

def enabled?(ctx) = ctx.object.enabled?

WidgetBluerpint.render(widget, object_if: :enabled?).to_json

collection_if

Only include collection fields if the given Proc or method name returns truthy.

Available in blueprint, view, partial, render
@param Field context

options[:collection_if] = ->(ctx) { ctx.object.enabled? }
options[:collection_if] = :enabled?

def enabled?(ctx) = ctx.object.enabled?

WidgetBluerpint.render(widget, collection_if: :enabled?).to_json

unless

Inverse of if.

field_unless

Inverse of field_if.

object_unless

Inverse of object_if.

collection_unless

Inverse of collection_if.

Field mapping

These options let you change how fields values are extracted from your objects.

from

Populate the field using a method/Hash key other than the field name.

Available in field, object, collection

field :desc, from: :description

extractor

Pass a custom extractor class or instance.

Available in field, object, collection

# Pass as a class
object :category, CategoryBlueprint, extractor: MyCategoryExtractor
# or an instance
object :category, CategoryBlueprint, extractor: MyCategoryExtractor.new(args)

Note that when you pass a class, it will be initialized once per render.

Metadata

These options allow you to add metadata to the rendered output.

root

Pass a root key to wrap the output.

Available in blueprint, view, partial, render

options[:root] = :data

WidgetBlueprint.render(widget, root: :data).to_json

Extensions

Blueprinter has a powerful extension system with hooks for every step of the serialization lifecycle. Some are included with Blueprinter, others are available as gems, and you can easily write your own using the Extension API.

Using extensions

Extensions can be added to your ApplicationBlueprint or any other blueprint, view, or partial. They're inherited from parent classes and views, but can be overridden.

class MyBlueprint < ApplicationBlueprint
  # This extension instance will exist for the duration of your program
  extensions << FooExtension.new

  # These extensions will be initialized once during each render
  extensions << BarExtension
  extensions << -> { ZorpExtension.new(some_args) }

  # Inline extensions are also initialized once per render
  extension do
    def blueprint_output(ctx) = ctx.result.merge({ foo: "Foo" })
  end

  view :minimal do
    # extensions is a simple Array, so you can add or remove elements
    extensions.select! { |ext| ext.is_a? FooExtension }

    # or simply replace the whole Array
    self.extensions = [FooExtension.new]
  end
end

Included extensions

These extensions are distributed with Blueprinter. Simply add them to your configuration.

Field Order

Control the order of fields in your output. See Fields API for more information about the block parameters.

extensions << Blueprinter::Extensions::FieldOrder.new { |a, b| a.name <=> b.name }

MultiJson

The MultiJson extension switches Blueprinter from Ruby's built-in JSON library to the multi_json gem. Just install the multi_json gem, your serialization library of choice, and enable the extension.

extensions << Blueprinter::Extensions::MultiJson.new

# Any options you pass will be forwarded to MultiJson.dump
extensions << Blueprinter::Extensions::MultiJson.new(pretty: true)

# You can also pass MultiJson.dump options during render
WidgetBlueprint.render(widget, multi_json: { pretty: true }).to_json

If multi_json doesn't support your preferred JSON library, you can use Blueprinter's json extension hook to render JSON however you like.

OpenTelemetry

Enable the OpenTelemetry extension to see what's happening while you render your blueprints. One outer blueprinter.render span will nest various blueprinter.object and blueprinter.collection spans. Each span will include the blueprint/view name that triggered it.

Extension hooks will be wrapped in blueprinter.extension spans and annotated with the current extension and hook name.

extensions << Blueprinter::Extensions::OpenTelemetry.new("my-tracer-name")

ViewOption

The ViewOption extension uses the blueprint extension hook to add a view option to render, render_object, and render_collection. It allows V1-compatible rendering of views.

extensions << Blueprinter::Extensions::ViewOption.new

Now you can render a view either way:

# V2 style
MyBlueprint[:foo].render(obj)
# or V1 style
MyBlueprint.render(obj, view: :foo)

Gem extensions

Have an extension you'd like to share? Let us know and we may add it to the list!

blueprinter-activerecord

blueprinter-activerecord is an official extension from the Blueprinter team providing ActiveRecord integration, including automatic preloading of associations based on your Blueprint definitions.

Rendering

Rendering to JSON

WidgetBlueprint.render(widget).to_json

If you're using Rails, you may omit .to_json when calling render json:

render json: WidgetBlueprint.render(widget)

Ruby's built-in JSON library is used by default. Alternatively, you can use the built-in MultiJson extension. Or for total control, implement the json extension hook and call any serializer you like.

Rendering to a Hash

WidgetBlueprint.render(widget).to_hash

Rendering a view

# Render a view
WidgetBlueprint[:extended].render(widget).to_json

# Render a nested view
WidgetBlueprint["extended.price"].render(widget).to_json

# These two both render the default view
WidgetBlueprint.render(widget).to_json
WidgetBlueprint[:default].render(widget).to_json

Passing options

An options hash can be passed to render. Read more about options.

WidgetBlueprint.render(Widget.all, exclude_if_nil: true).to_json

Rendering collections

render will treat any Enumerable, except Hash, as an array of objects:

WidgetBlueprint.render(Widget.all).to_json

If you wish to be explicit you may use render_object and render_collection:

WidgetBlueprint.render_object(widget).to_json

WidgetBlueprint.render_collection(Widget.all).to_json

Whatever you pass to render_collection must respond to map, yielding zero or more serializable objects, and returning an Enumerable with the mapped results.

Blueprinter API

Blueprinter has a rich API for extending the serialization process and reflecting on your blueprints.

Extensions

The extensions API offers deep hooks into the serialization process. Read more.

Reflection

The reflection API allows your application, or Blueprinter extensions, to introspect on your blueprints' options, fields, and views. Read more.

Extractors

By creating and using custom extractors, you can change the way field values are extracted from objects. Read more.

Context Objects

Context objects are the arguments you'll receive in most of the above APIs. Read more.

Fields

Several APIs provide access to structs describing field definitions. Read more.

Extensions

Blueprinter has a powerful extension system with hooks for every step of the serialization lifecycle. In fact, many of Blueprinter's features are implemented as built-in extensions!

Simply extend the Blueprinter::Extension class, define the hooks you need, and add it to your configuration.

class MyExtension < Blueprinter::Extension
  # Use the exclude_field? hook to exclude certain fields on Tuesdays
  def exclude_field?(ctx) = ctx.field.options[:tues] == false && Date.today.tuesday?
end

class MyBlueprint < ApplicationBlueprint
  extensions << MyExtension.new
end

Alternatively, you can define an extension direclty in your blueprint:

class MyBlueprint < ApplicationBlueprint
  extension do
    def exclude_field?(ctx) = ctx.field.options[:tues] == false && Date.today.tuesday?
  end
end

Hooks

Hooks are called in the following order. They are passed a context object as an argument.

blueprint
blueprint_fields
blueprint_setup
around_serialize_object | around_serialize_collection
- object_input | collection_input
- blueprint_input
  - extract_value
  - field_value | object_field_value | collection_field_value
  - exclude_field? | exclude_object_field? | exclude_collection_field?
    - blueprint_fields …
  - field_result | object_field_result | collection_field_result
- blueprint_output
- object_output | collection_output
json

Additionally, the around_hook hook runs around all other hooks.

Chain vs override hooks

Most hooks are chained; if you have N of the same hook, they run one after the other, using the output of one as input for the next. However, a few hooks are override hooks: only the last one runs. Override hooks are used to replace built-in functionality, like the JSON serializer.

blueprint

Override hook
@param Render Context NOTE fields will be empty
@return Class The Blueprint class to use
@cost Low - run once during render

Return a different blueprint class to render with. If multiple extensions define this hook, only the last one will be used. The included, optional View Option extension uses this hook.

The following example looks for a view option passed in to render. If present, it attempts to return a child view.

def blueprint(ctx)
  view = ctx.options[:view]
  view ? ctx.blueprint.class[view] : ctx.blueprint.class
end

blueprint_fields

Override hook
@param Render Context
@return Array<Field> The fields to serialize
@cost Low - run once for every blueprint class during render

Customize the order fields are rendered in - or strip out certain fields entirely. If multiple extensions define this hook, only the last one will be used. The included, optional Field Order extension uses this hook.

In this hook, context.fields will contain all of the view's fields in the order in which they were defined. (Fields from used partials are appended.) The fields this hook returns are used as context.fields in all subsequent hooks:

The following example removes all collection fields and sorts the rest by name:

def blueprint_fields(ctx)
  ctx.fields.
    reject { |f| f.type == :collection }.
    sort_by(&:name)
end

It's run once per blueprint class during a render. So if you're rendering an array of widgets with WidgetBlueprint, which contains PartBlueprints and CategoryBlueprints, this hook will be called three times: one for each of those blueprints.

Keyboard shortcuts

Blueprinter