Jsonity

The most sexy language for building JSON in Ruby

I'd been writing JSON API with Jbuilder, RABL and ActiveModel::Serializer, but nothing of them meet my requirement and use case.

• Jbuilder is very verbose in syntax, and its functonalities of partial and mixin are actually weak
• RABL has simple syntax, but writing complex data structure with it is not very readable
• ActiveModel::Serializer is persuasive role in Rails architecture, but can get very useless when you need to fully control from controller what attributes of multi-nested (associated) object to be included

So I chose to create new one -- Jsonity, which is simple and powerful JSON builder especially for JSON API representations.

• Simple and readable syntax even if it gets complex
• Flexible and arbitrary nodes
• Includable mixin
• Declarative attributes inclusion

Installation

Make sure to add the gem to your Gemfile.

gem 'jsonity'

Overview

@meta_pagination_mixin = ->(t) {
  t.meta! { |meta|
    meta.total_pages
    meta.current_page
  }
}

Jsonity.build { |t|
  t[].users!(@users) { |user|
    user.id
    user.age
    user.full_name { |u| [u.first_name, u.last_name].join ' ' }

    user.avatar? { |avatar|
      avatar.image_url
    }
  }

  t.(@users, &@meta_pagination_mixin)
}
=begin
{
  "users": [
    {
      "id": 1,
      "age": 21,
      "full_name": "John Smith",
      "avatar": {
        "image_url": "http://example.com/john.png"
      }
    },
    {
      "id": 2,
      "age": 37,
      "full_name": "William Northington",
      "avatar": null
    }
  ],
  "meta": {
    "total_pages": 1,
    "current_page": 1
  }
}
=end

Usage

Data object assignment

To declare the data object for use:

Jsonity.build { |t|
  t <= @user
  # ...
}

Or passing as an argument:

Jsonity.build(@user) { |user|
  # ...
}

Attribute nodes

Basic usage of defining simple attributes:

Jsonity.build(@user) { |user|
  user.id   # @user.id
  user.age  # @user.age
}
=begin
{
  "id": 123,
  "age": 27
}
=end

Or you can use custom attributes in flexible ways:

Jsonity.build(@user) { |user|
  # create full_name from @user.first_name and @user.last_name
  user.full_name { |u| [u.first_name, u.last_name].join ' ' }

  # block parameter isn't required
  user.russian_roulette { rand(1..10) }

  # or with specified the data object
  user.hello('world') { |w| w.upcase }

  # block can be omitted if the value is constant
  user.seventeen 17
}
=begin
{
  "full_name": "John Smith",
  "russian_roulette": 4,
  "hello": "WORLD",
  "seventeen": 17
}
=end

Aliased attributes works well as you expected:

Jsonity.build(@user) { |user|
  user.my_id &:id
}
=begin
{
  "my_id": 123
}
=end

Hash nodes

With name suffixed with !, nested object can be included:

Jsonity.build(@user) { |user|
  user.name  # @user.name

  user.avatar! { |avatar|
    avatar.image_url  # @user.avatar.image_url
    avatar.width      # @user.avatar.width
    avatar.height     # @user.avatar.height
  }
}
=begin
{
  "name": "John Smith",
  "avatar": {
    "image_url": "http://www.example.com/avatar.png",
    "width": 512,
    "height": 512
  }
}
=end

Assume that @user.avatar is nil, the output will be:

=begin
{
  "name": "John Smith",
  "avatar": {
    "image_url": null,
    "width": null,
    "height": null
  }
}
=end

On the other hand, use ? as suffix, the whole object become null:

Jsonity.build(@user) { |user|
  user.name

  user.avatar? { |avatar|  # <-- look, prefix is `?`
    avatar.image_url
    avatar.width
    avatar.height
  }
}
=begin
Assume that `@user.avatar` is `nil`,

{
  "name": "John Smith",
  "avatar": null
}
=end

To specify the data object to use inside a block:

Jsonity.build { |t|
  t.home!(@user.hometown_address) { |home|
    home.street  # @user.hometown_address.street
    home.zip
    home.city
    home.state
  }
}
=begin
{
  "home": {
    "street": "4611 Armbrester Drive",
    "zip": "90017",
    "city": "Los Angeles",
    "state": "CA"
  }
}
=end

Or a block can inherit the parent data object:

Jsonity.build { |t|
  t.user!(@user) { |user|
    user.profile!(inherit: true) { |profile|
      profile.name  # @user.name
    }
  }
}
=begin
{
  "user": {
    "profile": {
      "name": "John Smith"
    }
  }
}
=end

Array nodes

Including a collection of objects, just use [] and write the same syntax of hash node:

Jsonity.build(@user) { |user|
  user[].friends! { |friend|
    friend.name  # @user.friends[i].name
  }
}
=begin
{
  "friends": [
    { "name": "John Smith" },
    { "name": "William Northington" }
  ]
}
=end

Similar to hash nodes in naming convention,
if @user.friends = nil nodes suffix with ! will be an empty array [], in contrast, some with ? will be null.

Also passing the data object or inheritance can be done in the same way as hash nodes.

Automatic attributes inclusion

If you set attr_json in any class, the specified attributes will automatically be included:

class Sample < Struct.new(:id, :foo, :bar)
  attr_json :id, :foo

  attr_json { |sample|
    sample.hello_from 'attr_json!'
  }
end

@sample = Sample.new 123, 'foo!', 'bar!!'

and then,

Jsonity.build { |t|
  t.sample! @sample
}
=begin
{
  "sample": {
    "id": 123,
    "foo": "foo!",
    "hello_from": "attr_json!"
  }
}
=end

Still you can create any kinds of nodes with a block:

Jsonity.build { |t|
  t.sample!(@sample) { |sample|
    sample.bar { |s| "this is #{s.bar}" }
  }
}
=begin
{
  "sample": {
    "id": 123,
    "foo": "foo!",
    "hello_from": "attr_json!",
    "bar": "this is bar!!"
  }
}
=end

Mixin / Scope

Since Jsonity aim to be simple and light, use plain Proc to fullfill functonality of mixin.

@timestamps_mixin = ->(t) {
  t.created_at
  t.updated_at
}

and then,

Jsonity.build { |t|
  t.user!(@user) { |user|
    user.(&@timestamps_mixin)
  }
}
=begin
{
  "user": {
    "created_at": "2014-09-10 10:41:07 +0900",
    "updated_at": "2014-09-13 12:55:56 +0900"
  }
}
=end

To explicitly specify the data object to use in mixin, you can do by passing it in the first argument:

Jsonity.build { |t|
  t.(@user, &@timestamps_mixin)
}
=begin
{
  "created_at": "2014-09-10 10:41:07 +0900",
  "updated_at": "2014-09-13 12:55:56 +0900"
}
=end

So you can take this functonality for scope:

Jsonity.build { |t|
  t.(@user) { |user|
    user.name
  }
}
=begin
{
  "name": "John Smith"
}
=end

Mixining nested object and merging

@meta_pagination_mixin = ->(t) {
  t.meta! { |meta|
    meta.total_pages
    meta.current_page
  }
}

and use this mixin like:

Jsonity.build { |t|
  t.(@people, &@meta_pagination_mixin)

  t.meta! { |meta|
    meta.total_count @people.count
  }
}
=begin
Notice that two objects `meta!` got merged.

{
  "meta": {
    "total_pages": 5,
    "current_page": 1,
    "total_count": 123
  }
}
=end

Conditional

You can use if: and unless: options.

Jsonity.build { |t|
  t[].people!(@people) { |person|
    # if:
    person.cv!(if: &:looking_for_job?) { |cv|
      cv.title
      cv.download_link
    }

    # unless:
    person.name unless: &:anonymous?
  }
}

Getting data object

You can get the data object by calling get.

Jsonity.build { |t|
  t[].people!(@people) { |person|
    # debugging object
    p person.get
  }
}

With Rails

Helper method is available in controller for rendering with Jsonity:

render_json(status: :ok) { |t|
  # ...
}

License

This project is copyright by Creasty, released under the MIT lisence.
See LICENSE file for details.