{"id":13880472,"url":"https://github.com/trailblazer/representable","last_synced_at":"2025-12-17T17:25:57.023Z","repository":{"id":1391464,"uuid":"1379015","full_name":"trailblazer/representable","owner":"trailblazer","description":"Maps representation documents from and to Ruby objects. Includes JSON, XML and YAML support, plain properties and compositions.","archived":false,"fork":true,"pushed_at":"2023-07-05T20:30:40.000Z","size":3281,"stargazers_count":688,"open_issues_count":53,"forks_count":107,"subscribers_count":17,"default_branch":"master","last_synced_at":"2024-05-17T15:25:09.008Z","etag":null,"topics":["json-parser","json-serialization","xml-parser","xml-serialization","yaml"],"latest_commit_sha":null,"homepage":"http://trailblazer.to/2.1/docs/representable.html","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"Empact/roxml","license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/trailblazer.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2011-02-17T17:08:01.000Z","updated_at":"2024-04-19T12:40:32.000Z","dependencies_parsed_at":"2023-07-06T08:48:22.244Z","dependency_job_id":null,"html_url":"https://github.com/trailblazer/representable","commit_stats":{"total_commits":2012,"total_committers":57,"mean_commits":35.29824561403509,"dds":0.3464214711729622,"last_synced_commit":"1c1709125e1774e874b955c825cd07001810ee1a"},"previous_names":[],"tags_count":100,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trailblazer%2Frepresentable","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trailblazer%2Frepresentable/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trailblazer%2Frepresentable/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trailblazer%2Frepresentable/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/trailblazer","download_url":"https://codeload.github.com/trailblazer/representable/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":218996042,"owners_count":16421573,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["json-parser","json-serialization","xml-parser","xml-serialization","yaml"],"created_at":"2024-08-06T08:03:03.947Z","updated_at":"2025-10-05T22:30:20.853Z","avatar_url":"https://github.com/trailblazer.png","language":"Ruby","readme":"# Representable\n\nRepresentable maps Ruby objects to documents and back.\n![Build\nStatus](https://github.com/trailblazer/representable/actions/workflows/ci.yml/badge.svg?branch=master)\n[![Gem Version](https://badge.fury.io/rb/representable.svg)](http://badge.fury.io/rb/representable)\n\n\nIn 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.\n\nRepresentable 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](https://github.com/trailblazer/roar) gem first, save work and time and make the world a better place instead.\n\n\n## Full Documentation\n\nRepresentable comes with a rich set of options and semantics for parsing and rendering documents. Its [full documentation](https://trailblazer.to/2.1/docs/representable.html) can be found on the Trailblazer site.\n\n## Example\n\nWhat if we're writing an API for music - songs, albums, bands.\n\n```ruby\nclass Song \u003c OpenStruct\nend\n\nsong = Song.new(title: \"Fallout\", track: 1)\n```\n\n## Defining Representations\n\nRepresentations are defined using representer classes, called _decorator, or modules.\n\nIn these examples, let's use decorators\n\n```ruby\nclass SongRepresenter \u003c Representable::Decorator\n  include Representable::JSON\n\n  property :title\n  property :track\nend\n```\n\nIn 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=`.\n\n\n## Rendering\n\nMixing in the representer into the object adds a rendering method.\n\n```ruby\nSongRepresenter.new(song).to_json\n#=\u003e {\"title\":\"Fallout\",\"track\":1}\n```\n\n## Parsing\n\nIt also adds support for parsing.\n\n```ruby\nsong = SongRepresenter.new(song).from_json(%{ {\"title\":\"Roxanne\"} })\n#=\u003e #\u003cSong title=\"Roxanne\", track=nil\u003e\n```\n\nNote that parsing hashes per default does [require string keys](https://trailblazer.to/2.1/docs/representable.html#representable-api-symbol-keys) and does _not_ pick up symbol keys.\n\n\n## Collections\n\nLet's add a list of composers to the song representation.\n\n```ruby\nclass SongRepresenter \u003c Representable::Decorator\n  include Representable::JSON\n\n  property :title\n  property :track\n  collection :composers\nend\n```\n\nSurprisingly, `#collection` lets us define lists of objects to represent.\n\n```ruby\nSong.new(title: \"Fallout\", composers: [\"Stewart Copeland\", \"Sting\"]).\n  extend(SongRepresenter).to_json\n\n#=\u003e {\"title\":\"Fallout\",\"composers\":[\"Stewart Copeland\",\"Sting\"]}\n```\n\nAnd again, this works both ways - in addition to the title it extracts the composers from the document, too.\n\n\n## Nesting\n\nRepresenters can also manage compositions. Why not use an album that contains a list of songs?\n\n```ruby\nclass Album \u003c OpenStruct\nend\n\nalbum = Album.new(name: \"The Police\", songs: [song, Song.new(title: \"Synchronicity\")])\n```\n\nHere comes the representer that defines the composition.\n\n```ruby\nclass AlbumRepresenter \u003c Representable::Decorator\n  include Representable::JSON\n\n  property :name\n  collection :songs, decorator: SongRepresenter, class: Song\nend\n```\n\n## Inline Representers\n\nIf you don't want to maintain two separate modules when nesting representations you can define the `SongRepresenter` inline.\n\n```ruby\nclass AlbumRepresenter \u003c Representable::Decorator\n  include Representable::JSON\n\n  property :name\n\n  collection :songs, class: Song do\n    property :title\n    property :track\n    collection :composers\n  end\nend\n```\n\n## More\n\nRepresentable has many more features and can literally parse and render any kind of document to an arbitrary Ruby object graph.\n\nPlease check the [official documentation for more](https://trailblazer.to/2.1/docs/representable.html#representable-api).\n\n\n## Installation\n\nThe representable gem runs with all Ruby versions \u003e= 2.4.0.\nt\n```ruby\ngem 'representable'\n```\n\n### Dependencies\n\nRepresentable does a great job with JSON, it also features support for XML, YAML and pure ruby\nhashes. But Representable did not bundle dependencies for JSON and XML.\n\nIf you want to use JSON, add the following to your Gemfile:\n\n```ruby\ngem 'multi_json'\n```\n\nIf you want to use XML, add the following to your Gemfile:\n\n```ruby\ngem 'nokogiri'\n```\n\n## Copyright\n\nRepresentable started as a heavily simplified fork of the ROXML gem. Big thanks to Ben Woosley for his extremely inspiring work.\n\n* Copyright (c) 2011-2020 Nick Sutterer \u003capotonick@gmail.com\u003e\n* ROXML is Copyright (c) 2004-2009 Ben Woosley, Zak Mandhro and Anders Engstrom.\n\nRepresentable is released under the [MIT License](https://www.opensource.org/licenses/MIT).\n","funding_links":[],"categories":["Ruby"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrailblazer%2Frepresentable","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftrailblazer%2Frepresentable","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrailblazer%2Frepresentable/lists"}