Schemacop

Schemacop validates ruby structures consisting of nested hashes and arrays against schema definitions described by a simple DSL. It is also able to generate JSON Schema compliant JSON output, i.e. for use in conjunction with OpenAPI.

Compatibility

Schemacop is tested with the following ruby versions:

2.6.2
2.7.1
3.0.1
3.1.0
3.2.0
3.3.0

Other ruby versions might work but are not covered by our automated tests.

Basic example

schema = Schemacop::Schema3.new :hash do
  scm :group do
    str! :name
  end
  str! :name
  int? :age, minimum: 21
  ary! :groups do
    list :reference, path: :group
  end
end

schema.validate!(
  name: 'John Doe',
  age: 42,
  groups: [
    { name: 'Group 1' },
    { name: 'Group 2' }
  ]
)

Installation

To install the Schemacop gem:

$ gem install schemacop

To install it using bundler (recommended for any application), add it to your Gemfile:

gem 'schemacop', '>= 3.0.0'

Schema specification

The actual schema definition depends on the schema version you're using. Schemacop 3 supports version 3 and also the legacy version 2 for backwards compatibility. For version 1, you need to use the 1.x versions of schemacop.

Schema version 3
Schema version 2 (legacy)

JSON generation

Using the method as_json on any V3 schema will produce a JSON schema compliant to the JSON Schema standard.

Schemacop::Schema3.new :hash do
  str! :name
end.as_json

# Will result in
{
  type: :object,
  properties: {
    name: { type: :string }
  },
  additionalProperties: false,
  required: [:name]
}

On the resulting data structure, you can use to_json to convert it into an actual JSON string.

Exceptions

Schemacop will throw one of the following checked exceptions:

Schemacop::Exceptions::InvalidSchemaError

This exception is thrown when the given schema definition format is invalid.

Schemacop::Exceptions::ValidationError

This exception is thrown when the given data does not comply with the given schema definition.

Development

To run tests:

Check out the source
Run bundle install
Run bundle exec rake test to run all tests
Run bundle exec rake test TEST=test/unit/some/file.rb to run a single test file