ExJsonschema (ExJsonschema v0.1.0)

View Source

High-performance JSON Schema validation for Elixir using Rust.

This library provides a fast and spec-compliant JSON Schema validator powered by the Rust jsonschema crate. It supports multiple JSON Schema draft versions and provides detailed validation error information.

Quick Start

# Compile a schema
schema = ~s({"type": "object", "properties": {"name": {"type": "string"}}})
{:ok, compiled} = ExJsonschema.compile(schema)

# Validate JSON
valid_json = ~s({"name": "John"})
:ok = ExJsonschema.validate(compiled, valid_json)

invalid_json = ~s({"name": 123})
{:error, errors} = ExJsonschema.validate(compiled, invalid_json)

Features

  • Fast validation using Rust
  • Support for JSON Schema draft-07, draft 2019-09, and draft 2020-12
  • Detailed error messages with path information
  • Precompiled binaries for easy installation
  • Zero Rust toolchain required for end users

Summary

Functions

Compiles a JSON Schema string into an optimized validator.

Compiles a JSON Schema, raising an exception on failure.

Checks if JSON is valid against a compiled schema without returning error details.

Validates JSON against a compiled schema.

Validates JSON against a compiled schema, raising an exception on validation failure.

One-shot validation: compiles schema and validates instance in a single call.

Types

compiled_schema()

@type compiled_schema() :: reference()

json_string()

@type json_string() :: String.t()

validation_result()

@type validation_result() :: :ok | {:error, [ExJsonschema.ValidationError.t()]}

Functions

compile(schema_json)

@spec compile(json_string()) ::
  {:ok, compiled_schema()} | {:error, ExJsonschema.CompilationError.t()}

Compiles a JSON Schema string into an optimized validator.

Examples

iex> schema = ~s({"type": "string"})
iex> {:ok, compiled} = ExJsonschema.compile(schema)
iex> is_reference(compiled)
true

iex> invalid_schema = ~s({"type": "invalid_type"})
iex> {:error, %ExJsonschema.CompilationError{type: :compilation_error}} = ExJsonschema.compile(invalid_schema)

compile!(schema_json)

@spec compile!(json_string()) :: compiled_schema()

Compiles a JSON Schema, raising an exception on failure.

Examples

iex> schema = ~s({"type": "string"})
iex> compiled = ExJsonschema.compile!(schema)
iex> is_reference(compiled)
true

valid?(compiled_schema, instance_json)

@spec valid?(compiled_schema(), json_string()) :: boolean()

Checks if JSON is valid against a compiled schema without returning error details.

This is faster than validate/2 when you only need to know if the JSON is valid.

Examples

iex> schema = ~s({"type": "string"})
iex> {:ok, compiled} = ExJsonschema.compile(schema)
iex> ExJsonschema.valid?(compiled, ~s("hello"))
true
iex> ExJsonschema.valid?(compiled, ~s(123))
false

validate(compiled_schema, instance_json)

@spec validate(compiled_schema(), json_string()) :: validation_result()

Validates JSON against a compiled schema.

Returns :ok if valid, or {:error, errors} with detailed error information.

Examples

iex> schema = ~s({"type": "string"})
iex> {:ok, compiled} = ExJsonschema.compile(schema)
iex> ExJsonschema.validate(compiled, ~s("hello"))
:ok
iex> match?({:error, [%ExJsonschema.ValidationError{} | _]}, ExJsonschema.validate(compiled, ~s(123)))
true

validate!(compiled_schema, instance_json)

@spec validate!(compiled_schema(), json_string()) :: :ok

Validates JSON against a compiled schema, raising an exception on validation failure.

Examples

iex> schema = ~s({"type": "string"})
iex> {:ok, compiled} = ExJsonschema.compile(schema)
iex> ExJsonschema.validate!(compiled, ~s("hello"))
:ok

validate_once(schema_json, instance_json)

@spec validate_once(json_string(), json_string()) ::
  validation_result() | {:error, ExJsonschema.CompilationError.t()}

One-shot validation: compiles schema and validates instance in a single call.

This is convenient for one-time validations but less efficient for repeated validations of the same schema.

Examples

iex> schema = ~s({"type": "string"})
iex> ExJsonschema.validate_once(schema, ~s("hello"))
:ok
iex> match?({:error, [%ExJsonschema.ValidationError{} | _]}, ExJsonschema.validate_once(schema, ~s(123)))
true