Show HN: Shale – a Ruby object mapper and serializer for JSON, YAML and XML 

Shale is a Ruby object mapper and serializer for JSON, YAML and XML.

It allows you to parse JSON, YAML and XML data and convert it into Ruby data structures,
as well as serialize data structures into JSON, YAML or XML.

Working with data serialization formats directly can be painfull.
This is especially true for XML. Let’s consider this simple example of adding an
address to a person using Nokogiri:

That’s a lot of code for very simple use case.
Anything more complex and code complexity increases exponentially
leading to a maintanace problems and errors.

With Shale you can use Ruby objects to work with data
converting it to/from JSON, YAML or XML.

Let’s convert the same example to Shale:

That’s much simpler and it stays simple when the code complexity increases.

Prerequisites

Shale doesn’t have external dependencies. It uses standard library’s
JSON, YAML and REXML parsers by default.

If you need more performant solutions you can use custom libraries.
Out of the box, Shale provides adapters for Nokogiri and Ox
– see how to use them.

Features

• Convert JSON, YAML and XML to Ruby data model
• Convert Ruby data model to JSON, YAML and XML
• Generate JSON and XML Schema from Ruby models
• Compile JSON Schema into Ruby models
• Out of the box support for JSON, YAML, Nokogiri, REXML and Ox parsers
• Support for custom adapters

Installation

Add this line to your application’s Gemfile:

And then execute:

Or install it yourself as:

Convert data to Ruby

Converting data to Ruby is as simple as defining model classes and calling
from_&ltformat&gt method on this class.
e.g. Person.from_json(json_doc)

Convert Ruby to data

To convert Ruby to data just define model class, initialize object and call
to_&ltformat&gt method on it.
e.g. Person.new(name: 'John Doe').to_json

Custom mappings

When you define a class and add attributes, underneath Shale creates an implicit mapping
of keys (for JSON/YAML) and elements (for XML) to attributes.
That is nice for setting up your data model quickly, but usually your data format doesn’t
match your data model so cleanly.

That’s why you can explicitly map keys, element, attributes from your
data format to attributes on you Ruby model.

XML is more complicated format.

• To map XML element use map_element
• To map XML attribute use map_attribute
• To map XML text node use map_content
  (it will map first text node of an element)
• To change the name of the root element use root

Using XML namespaces

To map namespaced elements and attributes use
namespace and prefix properties on
map_element and map_attribute

To define default namespace for all elements use namespace declaration
(this will define namespace only on elements, if you want to define
namespace on an attribute, explicitly declare it on map_attribute).

Using methods to extract and generate data

If you need full controll over extracting and generating data you can use methods to do so.

Pretty printing and XML declaration

By default generated JSON and XML are compacted. If you need human readable format use
:pretty parameter on #to_json and #to_xml

You can also add an XML declaration by passing
:declaration to #to_xml

Generating JSON and XML Schema

To generate JSON or XML Schema from you Shale data model use:

You can also use a command line tool to do it:

or XML Schema:

If you want to convert your own types to Schema types use:

Compiling JSON Schema

To compile JSON Schema and generate Ruby data model use:

You can also use a command line tool to do it:

Supported types

Shale supports these types out of the box:

• Shale::Type::String
• Shale::Type::Integer
• Shale::Type::Float
• Shale::Type::Boolean
• Shale::Type::Date
• Shale::Type::Time

To add your own type extend defina a class and extend it from
Shale::Type::Value and implement .cast class method.

Adapters

Shale uses adapters for parsing and generating documents.
By default Ruby’s standard JSON parser is used for handling JSON documents,
YAML for YAML and REXML for XML.

You can change it by providing your own adapter. For JSON and YAML, adapter must implement
.load and .dump class methods.

For XML, Shale provides adapters for most popular Ruby XML parsers: