Tools for building and handling a JSON Schema powered API's

JSON Schema Tools

Build Status

Toolbox to work with JSON Schema in Ruby:

  • blow up classes from schema
  • object.as_schema_json conversion
  • object.valid? validations with object.errors

Simply use full blown classes or customize the bits and pieces:

  • add schema properties to an existing class
  • add validations to an existing class
  • clean parameters e.g. in an api controller
  • customize json output, object namespaces, used schema


Hook the gem into your app

gem 'json_schema_tools'

Quickstart assuming you have schema definitions like those in place.

# add schema directory to the search path
SchemaTools.schema_path = '/path/to/json-schema-files'
# blow up classes for each schema file

# init with params (assumes a contact.json definition)
contact = first_name: 'Barry', last_name: 'Cade'
# use setters/getters
contact.first_name = 'Ahr'
# validations derived from property definitions

Schema handling

Before the fun begins, with any of the tools, one or multiple JSON schema(files) must be available. A schema is converted into a ruby hash and for convenience is cached into a registry (global or per reader object). Globals are initialized once e.g on program start. A reader object allows to handle schemata in dynamic ways.

When using the global SchemaTools::Reader simply provide a base path to the schema files and you are done.

SchemaTools.schema_path = '/path/to/schema-json-files'

Read a single schema:

schema = :client

Read a schema from an existing Ruby hash:

schema = :client, { ... }

Read multiple schemas, all *.json files in schema path

schemata = SchemaTools::Reader.read_all

Schemata are cached in registry


Read files from a custom path?

schema = :client, 'my/path/to/json-files'
schemata = SchemaTools::Reader.read_all 'my/path/to/json-files'

Don't like the global path and registry? Create an instance and your save with a local registry. Use if you have schema with same names but different markup!

reader = :client, 'from/path'

Get a schema as plain ruby hash with all $refs de-referenced

client_schema = SchemaTools::Reader.registry[:client]
schema_hash = client_schema.to_h

Object to JSON - from Schema

As you probably know such is done e.g in rails via object.as_json. While using this might be simple, it has a damn big drawback: There is no transparent contract about the data-structure, as rails simply uses all fields defined in the database(ActiveRecord model). One side-effect: With each migration you are f***ed

A schema provides a public contract about an object definition. Therefore an internal object is converted to it's public(schema) version on delivery(API access). First the object is converted to a hash containing only the properties(keys) from its schema definition. Afterwards it is a breeze to convert this hash into JSON, with your favorite generator.

Following uses client.json schema, detected from peter.class name.underscore => "client", inside the global schema_path and adds properties to the clients_hash by simply calling client.send('property-name'):

class Client < ActiveRecord::Base
  include SchemaTools::Modules::AsSchema

peter = name: 'Peter'
#=> "client":{"id":12, "name": "Peter", "email":"",..}

#=> "client"=>{"id"=>12, "name"=> "Peter", "email"=>"",..}

The AsSchema module is a tiny wrapper for following low level method:

paul = name: 'Paul'
contact_hash = SchemaTools::Hash.from_schema(paul)
#=> "contact"=>{"id"=>12, "name"=> "Paul",..}
# to_json is up to you .. or your rails controller

Customise Output JSON / Hash

Following examples show options to customize the resulting json or hash. Of course they can be combined.

Only use some fields e.g. to save bandwidth

peter.as_schema_json(fields:['id', 'name'])
#=> "client":{"id":12, "name": "Peter"}

Use a custom schema name e.g. to represent a client as contact. Assumes you also have a schema named contact.json

peter.as_schema_json(class_name: 'contact')

Set a custom schema path

peter.as_schema_json( path: 'path-to/json-files/')

Use your custom reader (preferred over path usage)

reader =
reader.read_all '/your/custom/path-to-schema-json/
peter.as_schema_json( reader: reader)

By default the object hash has the class name (client) and the link-section on root level. This divides the data from the available methods and makes a clear statement about the object type(it's class). If you don't want to traverse that one extra level you can exclude the root and move the data one level up. See how class name and links are available inline:

peter.as_schema_json( exclude_root: true )

#=> {"id":12, "name"=> "Peter",
#    "_class_name":"client",
#    "_links":[ .. ] }

Of course the low level hash method also supports all of these options:

client_hash = SchemaTools::Hash.from_schema(peter, fields:['id', 'name'])
#=> "client"=>{"id"=>12, "name"=> "Peter"}

Object from JSON

On any remote site you'll need to instantiate new objects from an incoming json string. Let's assume a contact class which you need for incoming contact json data. (Example taken from attributes_spec.rb)

SchemaTools.schema_path = '/path/to/schema-json-files-with-contact-def'
class Contact
  include SchemaTools::Modules::Attributes
  has_schema_attrs :contact

json_str = '{"id": "123456", "last_name": "Meier","first_name": "Peter"}'
c = Contact.from_json(json_str) #=> "123456"

# new object from hash (if your favorite http tool already parsed the json)
c = Contact.from_hash({"id"=>123456, "last_name"=>"Meier","first_name"=>"Peter"})

Parameter cleaning

Hate people spamming your api with wrong object fields? Use the Cleaner to check incoming params.

For example in a client controller

def create
  SchemaTools::Cleaner.clean_params!(:client, params[:client])
  # params[:client] now only has keys defined as writable in client.json schema
  #..create and save client

Object attributes from Schema

Add methods, defined in schema properties, to an existing class. Very useful if you are building a API client and don't want to manually add methods to you local classes .. like people NOT using JSON schema

class Contact
  include SchemaTools::Modules::Attributes
  has_schema_attrs :client

contact =
contact.last_name = 'Rambo'
# raw access
# to json

Classes from Schema - KlassFactory

Use the KlassFactory to directly create classes, with all attributes from a schema. Instead of adding attributes to an existing class like in above example. The classes are named after each schema's [name] (in global path). So lets assume you have a 'client.json' schema with a name attribute in it, for the following examples:
client = first_name: 'Heinz' = 'Schultz'

Rather like a namespace? Good idea, but don't forget the class or module must be defined.

module SalesKing; end namespace: SalesKing
contact =

Add a custom schema reader most likely useful in conjunction with a custom path

reader = reader: reader, path: HappyPdf::Schema.path


Provides some basic support for JSON Pointer. JSON Pointer expressions must reference local files and must contain a fragment identifier, i.e.


is a resolvable pointer, while

is not.

Real world examples


Only runs on Ruby 1.9+ and by default uses most recent ActiveModel version (>3).

bundle install
rake spec

Testing with different ActiveModel / ActiveSupport Versions:

RAILS_VERSION=3.1 bundle install
rake spec
# or if already installed
RAILS_VERSION=4 rake spec

The RAILS_VERSION switch sets the version of the gems in the Gemfile and is only useful in test env.


Copyright 2012-2016, Georg Leciejewski, MIT License