Json::SchemaTemplates

Built on top of JSON::SchemaBuilder, JSON::SchemaTemplates contains some quality of life improvements when writing JSON schemas for Rails applications.

It is based purely on Ruby classes, but handles them as templates and partials, similar to ActionView in a lot of cases. This makes it easy to re-use parts of schemas and even pass in locals to change partial behaviour.

It also allows setting default values for certain schema properties, e.g. additional_properties when defining objects. This way, you don't have to include the argument in your schema every time, but instead only if you'd like to override the default value.

Last but not least it defines a few new types, e.g. datetime as a shortcut for string format: 'date-time'.

Installation

Add this line to your application's Gemfile:

gem 'json-schema_templates'

And then execute:

$ bundle

Or install it yourself as:

$ gem install json-schema_templates

Usage

Schemas are defined as Ruby classes inside a module structure resembling a template path. This means that all of your schemas reside in one root module, e.g. Schemas.

Let's take a look at the following example (found in spec/support/examples/basic_types):

module Examples
  module BasicTypes
    class Schema < ::JSON::SchemaTemplates::Base
      schema do
        string :title, min_length: 5, required: true
        string :body, null: true
      end
    end
  end
end

The topmost module here is Examples which makes it our root module for schemas.
To allow the Gem to actually search for schemas within this module, we have to set the corresponding value in the configuration:

JSON::SchemaTemplates.configure do |config|
  config.base_path = 'examples'
end

Notice that we didn't specify a module here, but rather a path, similar to rendering templates in ActionView. The reason is that we are now able to handle everything within Examples as an actual path:

The above template's path is - based on its module hierarchy - basic_types/schema and we can render it using the helper method

JSON::SchemaTemplates.json_schema_for('basic_types/schema')

This README will be extended over time.
Until then, please take a look at the examples for more information, e.g. on how to use partials in your schemas.

Known Problems

It is currently not possible to use null: true on objects due to a bug in json-schema_builder which causes an endless loop. There is a PR which aims to solve the problem, so until it's fixed, you could reference the corresponding repo + branch in your Gemfile alongside json-schema_templates.

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/lokalportal/json-schema_templates. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the Json::SchemaTemplates project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.