Builder-like JSON templating (for Rails)
Switch branches/tags
Nothing to show
Latest commit beb2f2a Oct 15, 2010
Uroš Jurglič
Uroš Jurglič Handler optimization
Failed to load latest commit information.
doc Small fix Oct 13, 2010
lib Handler optimization Oct 14, 2010
.gitignore Initial commit Oct 10, 2010
Manifest First documentation Oct 13, 2010
README.rdoc Small fix Oct 13, 2010
Rakefile Small fix Oct 13, 2010
jbuilder.gemspec Small fix Oct 13, 2010


JBuilder JSON Templating

JBuilder is a simple templating engine for generating JSON output. With Builder-like DSL it allows you to have your controllers and models clean of view logic. Primarily for Rails, but no reason not be used elsewhere. It was inspired by Builder gem and it uses JSON gem in the background.


A while ago I was implementing a REST API in Rails3 for my latest project and I choose JSON for primary content type. After an easy start with Rails and JSON based API, I found myself struggling to implement according to the MVC pattern. It gets even more annoying, when your API is growing beyond simplest example and when you want to have more control over the output format and logic.

Rails usually tackles this challenge in one of three ways:

  • generating a simple JSON object in controller

  • or keeping the controller clean, but putting the generating code into model's to_json method

  • or having the view done in default ERB template

First two approaches are strongly oppossing MVC pattern, having the view logic in either controller or model. Third is just too cumbersome, since ERB was meant for generating XML/HTML - and even there it doesn't exactly shine. (If you disagree, check HAML ;)

What I was really missing was a simple templating for generating JSON output, something like Builder is for XML. If you ask me, this should come with Rails out of the box along with ERB and Builder.

Here is the solution - a Builder-like JSON templating.

Examples and Usage

Let's say you want to produce output like this:

      "friends": [ 10, 20, 30 ],
      "followers": [ 20, 30 ]

Your code would then look like this:

json.user do
  json.value :id, 13
  json.nickname   "antiveb"      ""
  json.twitter_data do
    json.key     "7325872"
    json.token   "0"
    json.secret  "0"
    json.friends [10, 20, 30]
    json.followers :array do
      json.element 20
      json.element 30

Some rules, how to write directives:

  • every directive is prefixed with json.

  • there are three directive types (methods), that can be directly invoked: value, array, object

  • all three directive types take 2 parameters: name and value

  • if the directive is not one of those mentioned, there is a shorthand directive that tries to guess the directive type from arguments

  • shorthand directive takes the directive name as the first argument and value as the second argument


Just install the gem and require it in your Gemfile: gem “jbuilder”, :git => “git://”

Improving the docs

If you find something confusing or encounter a problem with this instructions please fork this project, make the changes, and send me a pull request.


Author:    Uros Jurglic
Company:   Antiveb ltd.
Home Page:
License:   MIT Licence (