# voxpupuli/json-schema for Ruby JSON validation

> voxpupuli/json-schema is a Ruby library for validating JSON data against JSON Schema documents, with Draft 6 as the default and legacy drafts available through explicit configuration. It offers boolean, exception, and structured error-reporting interfaces.

**voxpupuli/json-schema** — Ruby JSON Schema Validator

- Repository: https://github.com/voxpupuli/json-schema
- Stars: 1,646 · Forks: 253
- Language: Ruby
- License: MIT
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/voxpupuli-json-schema

## What the Ruby gem validates

voxpupuli/json-schema solves the problem of checking whether a JSON-compatible value conforms to a JSON Schema. The intended users are Ruby developers who receive JSON strings, read JSON files, or already have Ruby hashes and arrays that need validation before the application accepts them. The library is not limited to a single representation. The README states that both the schema and the data may be a JSON string, a file containing JSON, or a Ruby object representing JSON data.

The library defaults to JSON Schema Draft 6. It also includes support for Draft 4, Draft 3, Draft 2, and Draft 1. This matters when an application uses older schemas, because the default version is not necessarily the version declared by an existing schema. The README specifically documents the Draft 4 selection mechanism: callers can pass `:version => :draft4`, or the schema can contain a Draft 4 `$schema` URI. The declared `$schema` takes precedence during parsing and validation, so an explicit method option does not override that declaration.

The gem is a validation library rather than a JSON parser or schema language implementation. The schema still has to be written according to JSON Schema rules. The README points readers to the JSON Schema documentation for details about the schema format itself.

## The three Ruby validation interfaces

The primary API is the `JSON::Validator` module. It provides three validation methods with deliberately different result contracts. `validate` returns a boolean indicating whether validation passed. `fully_validate` returns an array of validation errors after validation completes. `validate!` raises `JSON::Schema::ValidationError` with a message and trace identifying where validation failed.

That distinction determines which interface fits a particular call site. A request gate that needs only a yes-or-no decision can call `validate`. Code that wants to present several problems to a user or log all detected failures can call `fully_validate`. A caller that treats invalid input as an exceptional condition can use `validate!` and handle the specific exception.

The README's object example defines an object schema with a required `a` property, where `a` must be an integer. A matching Ruby hash returns `true`, while an empty hash returns `false`. The same schema can be written to `schema.json`, after which `JSON::Validator.validate('schema.json', '{ "a": 5 }')` validates a JSON string against that file. This shows the intended data flow: the schema is supplied first, the data second, and the library returns a result for the pair.

## Draft selection and precedence in practice

Draft selection is explicit and has two documented routes. For an application that keeps its version outside the schema, pass the `:version` option. For a portable schema document, declare `$schema` inside the schema itself. The latter is usually the more direct representation of the schema's expected dialect because the document travels with the schema.

The precedence rule is a genuine implementation constraint. If a schema declares `"$schema" => "http://json-schema.org/draft-04/schema#"`, parsing and validation follow that declaration. The README does not provide a conflict example showing what happens when `:version` names a different draft, but it clearly states that `$schema` wins. Code should therefore avoid configuring both routes unless the mismatch is intentional and understood.

The README also records a major-version behavior change: version 2.0.0 made Draft 4 the default for schemas without a `$schema` declaration. That historical note is relevant to old application code because schemas that previously depended on Draft 3 behavior may need an explicit declaration or option. Current documentation says Draft 6 is the default, which makes schema-version review a necessary part of migration work.

## Install the gem and validate a first payload

The README documents installation from RubyGems and from the repository. For a normal Ruby application, the RubyGems command is the shortest documented path:

```bash
gem install json-schema
```

After that command succeeds, the application can require the library and define a small schema. The following example validates a Ruby object rather than requiring a separate JSON parsing step:

```ruby
require "json-schema"

schema = {
  "type" => "object",
  "required" => ["a"],
  "properties" => {
    "a" => {"type" => "integer"}
  }
}

JSON::Validator.validate(schema, { "a" => 5 })
```

The call returns `true` when the required property exists with an integer value. The README shows that the same schema returns `false` for an empty object. Developers working from a checked-out repository are also given a local build path:

```bash
gem build json-schema.gemspec
gem install json-schema-*.gem
```

Those commands build the gem from the gemspec and install the generated package. The README does not document a separate dependency-installation command, so applications should use the dependency setup appropriate for their own Gemfile.

## Raising errors and collecting all failures

The exception interface is useful when invalid input should stop processing immediately. The README demonstrates a schema whose `a` property must be an integer, then calls `validate!` with the string `"taco"`. The example catches `JSON::Schema::ValidationError` and reads `e.message`, which identifies the property and expected type.

For reporting workflows, `fully_validate` avoids stopping at the first validation problem. The README says that it returns an array of errors when validation is complete. With `:errors_as_objects => true`, the returned values are hashes rather than strings. The documented hash includes a schema URI, fragment, message, and failed attribute. That structure gives application code fields it can map into an API response or log record instead of parsing the human-readable message.

This distinction is the real alternative to choosing only one error strategy in the codebase. `validate!` treats failure as an exception, while `fully_validate` treats failure as a collection to inspect. Choosing between them is not merely stylistic. The first fits fail-fast control flow, and the second fits user feedback or diagnostics that need more than a single failure message.

## Options that change the validation boundary

The README documents several optional arguments that alter how a schema is applied. With `:list => true`, a schema that represents one individual object can validate a list of those objects. The documented example accepts three hashes containing integer `a` values when `:list => true` is supplied, but rejects the same array without the option. This is useful when an endpoint receives an array but the schema is maintained for one item.

The `:strict` option changes object validation rules. Under strict mode, all properties are treated as required and all objects are treated as having `"additionalProperties": false`. The README shows a matching object passing, an object with an extra `c` property failing, and an object missing `a` failing. Strict mode therefore reduces the number of unspecified properties and omissions accepted by the validator.

The `:fragment` option narrows validation to a schema location. In the README example, selecting `#/properties/b` validates `{ "x" => 1 }` against the nested `b` schema, whereas validating it against the root object does not. The truncated README mentions `:validate_schema` but does not show its complete behavior, so an application should consult the repository documentation before relying on that option's details.

## Limits, releases, and MIT licensing

The library's most concrete constraint is version-sensitive behavior. It supports several JSON Schema drafts, but Draft 6 is the default and `$schema` declarations override the `:version` option. A schema can therefore validate successfully in one project and fail after a dependency or schema-dialect change if the document's declared version differs from what the caller expected. The README's upgrade notes make this a migration issue rather than merely a configuration preference.

The repository is not archived. Its last push was on 2026-10-11, and the recent release history includes v6.2.1 on 2026-10-03, v6.2.0 on 2026-03-06, and v6.1.0 on 2025-12-21. This supports checking the changelog during upgrades, although the README does not claim that every release contains behavior changes. It points to `CHANGELOG.md` for individual changes.

The project uses the MIT license. That permits use under the license's terms, but application owners still need to review the actual `LICENSE.md` and include required notices. The license does not by itself establish compatibility with a particular application architecture or remove the need to test schema behavior during an upgrade.

## Conclusion

Ruby applications that need direct JSON Schema validation should start by checking whether their schemas declare Draft 4 through `$schema`, because that declaration takes precedence over the `:version` option. Projects that need a complete error report should use `fully_validate`; projects that only need pass or fail should use `validate`. The first adoption check is whether the required draft, input format, and error-handling behavior match the documented interfaces.

## FAQ

### How do I install voxpupuli/json-schema in Ruby?

The README documents installation from RubyGems with `gem install json-schema`. It also documents building the gemspec with `gem build json-schema.gemspec` and installing the resulting file with `gem install json-schema-*.gem`.

### What is the default JSON Schema draft in voxpupuli/json-schema?

The README says the validator uses JSON Schema Draft 6 by default. Legacy support is available for Draft 4, Draft 3, Draft 2, and Draft 1 through the `:version` option or a schema `$schema` declaration.

### How can I get detailed validation errors from voxpupuli/json-schema?

Use `fully_validate` to receive an array of errors. With `:errors_as_objects => true`, the README says the errors are returned as hashes containing fields such as `:fragment`, `:message`, and `:failed_attribute`.

## Sources

- [Issues](https://github.com/voxpupuli/json-schema/issues)
- [License: MIT](https://github.com/voxpupuli/json-schema/blob/master/LICENSE)
- [README](https://github.com/voxpupuli/json-schema/blob/master/README.md)
- [Releases](https://github.com/voxpupuli/json-schema/releases)
- [voxpupuli/json-schema on GitHub](https://github.com/voxpupuli/json-schema)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/voxpupuli-json-schema