Maps representation documents from and to Ruby objects. Includes JSON, XML and YAML support, plain properties and compositions.
Clone or download
#198 Compare This branch is 1460 commits ahead, 85 commits behind Empact:master.
seuros Merge pull request #229 from trailblazer/noko
try latest version of nokogiri
Latest commit d5378ab Jun 23, 2018
Type Name Latest commit message Commit time
Failed to load latest commit information.
lib releasing 3.0.4. Apr 17, 2017
test better documented tests, and #assert_xml helper. Apr 17, 2017
.gitignore Ignoring unimportant stuff Jun 20, 2012
.travis.yml allow Jruby to break. Apr 17, 2017 add proper XML namespace support. Apr 16, 2017
Gemfile try latest version of nokogori Jun 23, 2018
LICENSE adding LICENSE. Apr 20, 2013 Update travis CI icon Feb 4, 2017
Rakefile add test-with-deprecations. Nov 22, 2015
TODO cleanup TODOs. Apr 17, 2017 cleanup TODOs. Apr 17, 2017
representable.gemspec update locks file Jun 23, 2018


Representable maps Ruby objects to documents and back.

Gitter Chat TRB Newsletter Build Status Gem Version

In other words: Take an object and decorate it with a representer module. This will allow you to render a JSON, XML or YAML document from that object. But that's only half of it! You can also use representers to parse a document and create or populate an object.

Representable is helpful for all kind of mappings, rendering and parsing workflows. However, it is mostly useful in API code. Are you planning to write a real REST API with representable? Then check out the Roar gem first, save work and time and make the world a better place instead.

Full Documentation

Representable comes with a rich set of options and semantics for parsing and rendering documents. Its full documentation can be found on the Trailblazer site.


What if we're writing an API for music - songs, albums, bands.

class Song < OpenStruct

song = "Fallout", track: 1)

Defining Representations

Representations are defined using representer classes, called _decorator, or modules.

In these examples, let's use decorators

class SongRepresenter < Representable::Decorator
  include Representable::JSON

  property :title
  property :track

In the representer the #property method allows declaring represented attributes of the object. All the representer requires for rendering are readers on the represented object, e.g. #title and #track. When parsing, it will call setters - in our example, that'd be #title= and #track=.


Mixing in the representer into the object adds a rendering method.
#=> {"title":"Fallout","track":1}


It also adds support for parsing.

song ={ {"title":"Roxanne"} })
#=> #<Song title="Roxanne", track=nil>

Note that parsing hashes per default does require string keys and does not pick up symbol keys.


Let's add a list of composers to the song representation.

class SongRepresenter < Representable::Decorator
  include Representable::JSON

  property :title
  property :track
  collection :composers

Surprisingly, #collection lets us define lists of objects to represent. "Fallout", composers: ["Stewart Copeland", "Sting"]).

#=> {"title":"Fallout","composers":["Stewart Copeland","Sting"]}

And again, this works both ways - in addition to the title it extracts the composers from the document, too.


Representers can also manage compositions. Why not use an album that contains a list of songs?

class Album < OpenStruct

album = "The Police", songs: [song, "Synchronicity")])

Here comes the representer that defines the composition.

class AlbumRepresenter < Representable::Decorator
  include Representable::JSON

  property :name
  collection :songs, decorator: SongRepresenter, class: Song

Inline Representers

If you don't want to maintain two separate modules when nesting representations you can define the SongRepresenter inline.

class AlbumRepresenter < Representable::Decorator
  include Representable::JSON

  property :name

  collection :songs, class: Song do
    property :title
    property :track
    collection :composers


Representable has many more features and can literally parse and render any kind of document to an arbitrary Ruby object graph.

Please check the official documentation for more.


The representable gem runs with all Ruby versions >= 1.9.3.

gem 'representable'


Representable does a great job with JSON, it also features support for XML, YAML and pure ruby hashes. But Representable did not bundle dependencies for JSON and XML.

If you want to use JSON, add the following to your Gemfile:

gem 'multi_json'

If you want to use XML, add the following to your Gemfile:

gem 'nokogiri'


Representable started as a heavily simplified fork of the ROXML gem. Big thanks to Ben Woosley for his extremely inspiring work.

  • Copyright (c) 2011-2016 Nick Sutterer
  • ROXML is Copyright (c) 2004-2009 Ben Woosley, Zak Mandhro and Anders Engstrom.

Representable is released under the MIT License.