Iglu Ruby Client 0.1.0 released

We are pleased to announce the initial release of the Iglu Ruby Client, our third library in the family of Iglu clients.

In the rest of this post we will cover:

1. Introducing Iglu Ruby Client
2. Use cases
3. Setup guide
4. Usage
5. Roadmap and upcoming features
6. Getting help

1. Introducing Iglu Ruby Client

Iglu clients are simple SDKs which let users fetch schemas for self-describing data and validate that data against its schema.

As part of broadening the utility of the Iglu platform, we are pleased to introduce the Iglu Ruby Client. You can embed this client inside web applications written in Ruby on Rails or Sinatra, or inside Ruby- or JRuby-based CLI applications; we created this SDK originally for use inside Snowplow’s own JRuby-based CLI apps.

This is our third Iglu client. Our Iglu Scala Client is the reference implementation and works at the core of the Snowplow pipeline, validating all data flowing through the platform; our Iglu Objective-C Client lets you test and validate all of your Snowplow self-describing JSONs directly in your OS X and iOS applications.

2. Use cases

This library lets you add a layer of JSON validation to your Ruby-based web applications, servers and CLI tools.

If you are sending events to Snowplow from Ruby, it is important to check that the self-describing JSONs you are sending to Snowplow will not cause validation issues downstream. If they do not validate, then Snowplow events will fail validation until you can get the problem fixed.

You can now run the following assertions directly in your application:

• That your resolver config is valid as per the Iglu technical documentation
• That your self-describing JSONs can be resolved correctly against your Iglu repositories
• That your self-describing JSONs pass validation against their respective JSON Schemas

This removes the need of manually and painstakingly validating that your events and corresponding JSON Schemata are correct.

As well as these Snowplow-oriented use cases, nothing prevents you from using Iglu technology more broadly, for example in conjunction with REST APIs to document and evolve API endpoints, and to eagerly validate data that clients and servers passing to each other.

Please share any novel use cases for this client on our Discourse!

3. Setup guide

Iglu Ruby Client has been tested with Ruby versions from 2.0 up to 2.4, including JRuby and can be used as a dependency for other gems as well as included into jars.

It is published on RubyGems.org and can be installed with via gem utility:

gem install iglu-ruby-client

To add it as a dependency to your own Ruby gem, please edit your gemfile and add:

$ gem 'iglu-ruby-client'

4. Usage

Here is a basic usage of Ruby Iglu resolver:

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)

The above snippet initializes the client from a resolver configuration (versions up to 1-0-2 are supported in initial release) which contains Iglu Central.

As in the Iglu Scala Client, the Ruby Resolver gives full information about what exactly went wrong on invalid JSON, but unlike Scala it throws an exception, rather than returning a plain value:

invalid_json = { :schema => "iglu:com.snowplowanalytics.snowplow/geolocation_context/jsonschema/1-1-0", :data => {:latitude => 30.8, :longitude => "invalid"} } resolver.validate(invalid_json) JSON::Schema::ValidationError: The property '#/longitude' of type String did not match the following type: number from /Library/Ruby/Gems/2.0.0/gems/json-schema-2.7.0/lib/json-schema/attribute.rb:18:in `validation_error'

For valid JSON it will return a true value:

valid_json = { :schema => "iglu:com.snowplowanalytics.snowplow/geolocation_context/jsonschema/1-1-0", :data => {:latitude => 30.8, :longitude => 62.1} } resolver.validate(valid_json) # Evaluates to true

For more advanced usage, please see the Ruby client page on the Iglu wiki.

5. Roadmap and upcomming features

Iglu Ruby Client is still a young project, and does not yet have feature parity with our Iglu Scala Client, the reference implementation.

In particular:

• Although you must set the cacheSize for each registry in the resolver configuration, it is not actually used. While Iglu Scala Client uses this for eviction from its LRU cache, by contrast the Ruby client currently grows its cache indefinitely (#3)
• Iglu Ruby Client doesn’t yet support recently introduced cacheTtl configuration property (#6)

6. Getting help

If you have any questions or run into any problems, please raise an issue or get in touch with us through the usual channels.