Active JSON Model

A library for creating Active Models that can serialize/deserialize to JSON. This includes full support for validation and change detection through nested models.

Active JSON Model can optionally be combined with Active Record to create nested child models via JSON/JSONB columns.

Quick start
Gem on RubyGems
Support
License
Code of conduct
Contribution guide

Quick start

Install the gem:

$ gem install activejsonmodel

If not using in an auto-loading context (i.e. Rails), import it:

require "active_json_model"

define a model:

class Point
  include ActiveJsonModel::Model
  
  json_attribute :x, Integer
  json_attribute :y, Integer
end

create an instance of a model:

origin = Point.new(x: 0, y:0)
# => #<Point:0x00007f9f0d0e6538 @mutations_before_last_save=nil, @mutations_from_database=nil, @x=0, @x_is_default=false, @y=0, @y_is_default=false>

export it to a JSON-like hash:

data = origin.dump_to_json
# => {:x=>0, :y=>0}

encode it as JSON:

JSON.dump(origin.dump_to_json)
# => "{\"x\":0,\"y\":0}"

load data from a hash object:

point2 = Point.load({x: 17, y:42})
# => #<Point:0x00007f9f0d10d5c0 @_active_json_model_loaded=true, @mutations_before_last_save=nil, @mutations_from_database=nil, @x=17, @x_is_default=false, @y=42, @y_is_default=false>

load from a raw JSON string:

point3 = Point.load("{\"x\":12,\"y\":19}")
# => #<Point:0x00007fe9c0113c88 @_active_json_model_loaded=true, @mutations_before_last_save=nil, @mutations_from_database=nil, @x=12, @x_is_default=false, @y=19, @y_is_default=false>

nest models:

class Rectangle
  include ActiveJsonModel::Model

  json_attribute :top_left, Point
  json_attribute :bottom_right, Point
  
  def contains(point)
    point.x >= top_left.x && 
      point.x <= bottom_right.x &&
      point.y <= top_left.y &&
      point.y >= bottom_right.y
  end
end

If you are using Active Record, use the model as an attribute:

# db/migrate/20220101000001_create_image_annotations.rb
class CreateImageAnnotations < ActiveRecord::Migration[7.0]
  def change
    create_table :image_annotations do |t|
      t.jsonb      :region_of_interest, null: false, default: {}
      t.string     :note, null: false, default: ''
    end
  end
end

# app/models/image_annotation.rb
class ImageAnnotation < ActiveRecord::Base 
  attribute :region_of_interest, Rectangle.attribute_type
end

# use...
rect = Rectangle.new(
  top_left: Point.new(x: 10, y: 100),
  bottom_right: Point.new(x: 110, y: 0)
)
ia = ImageAnnotation.new(region_of_interest: rect, note: "Check out this mistake")
ia.save

Support

If you want to report a bug, or have ideas, feedback or questions about the gem, let me know via GitHub issues and I will do my best to provide a helpful answer. Happy hacking!

License

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

Code of conduct

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

Contribution guide

Pull requests are welcome!

Development Setup

brew install rbenv

Add the following to ~/.zshrc:

RBENV=`which rbenv`
if [ $RBENV ] ; then
  export PATH=$HOME/.rbenv/bin:$PATH
  eval "$(rbenv init -)"
fi

Reload the ~/.zshrc.

Install development ruby version:

cat .ruby-version | xargs rbenv install

Exit and re-enter the directory to make sure the current version of ruby is used. Install dependencies:

bundle install

Running Tests

Active JSON Model uses minitest. To run tests, use rake:

rake test

Building Gem Locally

Build the gem to pkg/activejsonmodel-x.x.x.gem:

rake build

Install the gem locally and import it:

$ gem install ./pkg/activejsonmodel-x.x.x.gem
Successfully installed activejsonmodel-x.x.x
Parsing documentation for activejsonmodel-x.x.x
Installing ri documentation for activejsonmodel-x.x.x
Done installing documentation for activejsonmodel after 0 seconds
1 gem installed

$ irb
irb(main):001:0> require 'active_json_model'
=> true

Releasing a new version

Update lib/activejsonmodel/version.rb

module ActiveJsonModel
  VERSION = "x.x.x".freeze
end

Commit all changes
Release the changes using rake:

$ rake release
active_json_model x.x.x built to pkg/active_json_model-x.x.x.gem.
Tagged vx.x.x.
Pushed git commits and release tag.
Pushing gem to https://rubygems.org...
Successfully registered gem: active_json_model (x.x.x)
Pushed active_json_model x.x.x to rubygems.org
Don't forget to publish the release on GitHub!

Note that this pushes changes to github and creates a draft release on github.