No longer maintained, please check out jbuilder

Rails provides an excellent XML Builder by default to build RSS and ATOM feeds, but nothing to help you build complex and custom JSON data structures. The standard to_json works just fine, but can get very verbose when you need full control of what is generated and performance is a factor. JSON Builder hopes to solve that problem.

require'json_builder'json=JSONBuilder::Compiler.generatedoname'Garrett Bjerkhoel'email'[email protected]'urluser_url(user)addressdostreet'1234 1st Ave'city'New York'state'NY'zip10065endkey:nil,'testing a custom key name'skillsdorubytrueaspfalseendlongstringdo# Could be a highly intensive process that only returns a string'12345' * 25endend

Which will generate:

{"name": "Garrett Bjerkhoel", "email": "[email protected]", "url": "http://examplesite.com/dewski", "address":{"street": "1234 1st Ave", "city": "New York", "state": "NY", "zip": 10065 }, "nil": "testing a custom key name", "skills":{"ruby": true, "asp": false }, "longstring": "1234512345123451234512345..." }

If you'd like to just generate an array:

array['Garrett Bjerkhoel','John Doe']do |name| first,last=name.split(' ')firstfirstlastlastend

Which will output the following:

[{"first": "Garrett", "last": "Bjerkhoel" },{"first": "John", "last": "Doe" } ]

Just a note, if you use an array block, all other builder methods will be ignored.

First, make sure to add the gem to your Gemfile.

gem'json_builder'

Second, make sure your controller responds to json:

classUsersController < ApplicationControllerrespond_to:jsondefindex@users=User.order('id DESC').page(params[:page]).per(2)respond_with@usersendend

Lastly, create app/views/users/index.json.json_builder which could look something like:

count@users.countpage@users.current_pageper_page@users.per_pagepages_count@users.num_pagesresults@usersdo |user| iduser.idnameuser.namebodyuser.bodyurluser_url(user)linksuser.linksdo |link| urllink.urlvisitslink.visitslast_visitedlink.last_visitedendend

You will get something like:

{"count": 10, "page": 1, "per_page": 2, "pages_count": 5, "results": [{"id": 1, "name": "Garrett Bjerkhoel", "body": "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod.", "url": "http://example.com/users/garrett-bjerkhoel", "links": [{"url": "http://github.com/", "visits": 500, "last_visited": "2011-11-271T00:00:01Z" },{"url": "http://garrettbjerkhoel.com/", "visits": 1500, "last_visited": "2011-11-261T00:00:01Z" } ] },{"id": 2, "name": "John Doe", "body": "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod.", "url": "http://example.com/users/john-doe", "links": [{"url": "http://google.com/", "visits": 11000, "last_visited": "2010-05-221T00:00:01Z" },{"url": "http://twitter.com/", "visits": 155012857, "last_visited": "2011-11-261T00:00:01Z" } ] } ] }

Out of the box JSON Builder supports JSONP callbacks when used within a Rails project just by using the callback parameter. For instance, if you requested /users.json?callback=myjscallback, you'll get a callback wrapping the response:

myjscallback([{"name": "Garrett Bjerkhoel" },{"name": "John Doe" } ])

To turn off JSONP callbacks globally or just per-environment:

ActionView::Base.json_callback=false

Sample::Application.configuredoconfig.action_view.json_callback=falseend

Out of the box JSON Builder supports pretty printing only during development, it's disabled by default in other environments for performance. If you'd like to enable or disable pretty printing you can do it within your environment file or you can do it globally.

With pretty print on:

{"name": "Garrett Bjerkhoel", "email": "[email protected]" }

Without:

{"name": "Garrett Bjerkhoel", "email": "[email protected]"}

Sample::Application.configuredoconfig.action_view.pretty_print_json=falseend

ActionView::Base.pretty_print_json=false

JSON Builder is very fast, it's roughly 3.6 times faster than the core XML Builder based on the speed benchmark.

 user system total real JSONBuilder 2.950000 0.010000 2.960000 (2.968790) Builder 10.820000 0.040000 10.860000 (10.930497) 

There are alternatives to JSON Builder, each good in their own way with different API's and design approaches that are worth checking out. Although, I would love to hear why JSON Builder didn't fit your needs, by [message or issue.

• jbuilder
• RABL
• Tequila
• Argonaut
• Jsonify
• RepresentationView

• Fork the project.
• Make your feature addition or bug fix.
• Add tests for it. This is important so I don't break it in a future version unintentionally.
• Commit, do not mess with Rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself in another branch so I can ignore when I pull)
• Send me a pull request. Bonus points for topic branches.

Copyright © 2012 Garrett Bjerkhoel. See MIT-LICENSE for details.