Pipeline Components and Applications

  1. Home
  2. Docs
  3. Pipeline Components and Applications
  4. Iglu
  5. Iglu Clients
  6. Ruby client

Ruby client

This page refers to version 0.2.0 of the Iglu Ruby client.

Overview

The Iglu Ruby client allows you to resolve JSON Schemas from embedded and remote repositories.

This client library should be straightforward to use if you are comfortable with Ruby development.

Client compatibility

The Ruby client was tested with Ruby 2.12.22.4JRuby 9.0.5.0 and JRuby 9.1.6.0.

Dependencies

The library is dependant on Ruby JSON Schema Validator library for all JSON Schema validation and httparty for HTTP requests.

Setup

RubyGems

Ruby Iglu Client is published on RubyGems.org.

You can either install it in shell via gem:

$ gem install iglu-ruby-client

or add it to Gemfile:

gem 'iglu-ruby-client'

Manual Setup

You can also build and install gem locally in case you need to introduce some changes.

Clone the client

First, git clone the latest version of the client to your local machine:

$ git clone https://github.com/snowplow/iglu-ruby-client.git

If you don’t have git installed locally, install it first.

Build a gem

$ cd iglu-ruby-client
$ gem build iglu-ruby-client.gemspec
$ gem install iglu-ruby-client-0.1.0.gem

Initialization

Assuming you have completed the setup for your Ruby project, you are now ready to initialize the Ruby client.

Importing the library

All entities can be accessed by importing iglu-client package.
Client is placed in Iglu::Resolver module, while core entities are in root Iglu module.

You are now ready to instantiate a Ruby Client.

JSON-based initialization

require 'iglu-client' resolver_config = {:schema => "iglu:com.snowplowanalytics.iglu/resolver-config/jsonschema/1-0-2", :data => { :cacheSize => 500, :repositories => [{:name => "Iglu Central", :priority => 0, :vendorPrefixes => ["com.snowplowanalytics"], :connection => {:http => {:uri => "http://iglucentral.com"}}}] } } resolver = Iglu::Resolver.parse(resolver_config)
Code language: JavaScript (javascript)

Note that it is highly recommended to use JSONs as hashes with symbolized keys, you can use JSON.parse(json, {:symbolize_names => true}) to parse JSON with all keys as symbols instead of strings.

Usage

Validating JSON

Once you have successfully created a client you can start validating your self-describing JSON.

json = resolver_config # resolver config is plain self-describing JSON! resolver.validate(json) # this will return same `json` value in case of success or throw IgluError in case of any failure
Code language: PHP (php)

Unlike Iglu Scala Client which never throws exceptions and return errors as values, Ruby client uses more common for dynamic languages approach,
specifically it throws IgluError exception on any non-success case, like non-self-describing JSON, not found schema, connection error etc and returns plain value (same self-describing JSON) on success.

To just lookup schema without any self-describing JSON, you can use lookup_schema method, which accepts schema key as object or URI.

Core entities

iglu-ruby-client gem also provides entities specific to Iglu core’s.
Specifically, you can initialize and utilize entities such as schema key, self-describing data, SchemaVer etc.
Same classes will be included in Iglu Ruby Core library when it’ll be released.

schema_key = SchemaKey.new("com.acme", "event", "jsonschema", SchemaVer.new(1,0,2)) # or schema_key = SchemaKey.parse("iglu:com.acme/event/jsonschema/1-0-2")
Code language: PHP (php)

Embedded registry

Ruby Client supports somewhat similar to JVM embedded registry.
It also can be constructed from embedded connection using path inside gems and JRuby jars (created using warbler) but it has few important differences with JVM embedded registry:

  • It can accept absolute filesystem paths
  • Paths are relative from ruby file where registry is initialized
  • There’s no way to automatically merge all embedded registries, each should be created explicitly

Our own’s bootstrap resolver can be used as an example on how to use embedded registries in Ruby.