or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/maven-io-rest-assured--json-schema-validator

A Hamcrest matcher library for validating JSON documents against JSON schemas, designed for use with REST Assured testing framework.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/io.rest-assured/json-schema-validator@5.5.x

To install, run

npx @tessl/cli install tessl/maven-io-rest-assured--json-schema-validator@5.5.0

index.mddocs/

JSON Schema Validator

JSON Schema Validator is a Hamcrest matcher library for validating JSON documents against JSON schemas, designed for use with REST Assured testing framework. It provides comprehensive JSON schema validation capabilities with configurable settings and factory support for Java-based testing environments.

Package Information

  • Package Name: json-schema-validator
  • Package Type: maven
  • Language: Java
  • Group ID: io.rest-assured
  • Artifact ID: json-schema-validator
  • Installation: Add to your Maven dependencies: 
    <dependency>
  <groupId>io.rest-assured</groupId>
  <artifactId>json-schema-validator</artifactId>
  <version>5.5.2</version>
</dependency>

Core Imports

import static io.restassured.module.jsv.JsonSchemaValidator.*;
import io.restassured.module.jsv.JsonSchemaValidator;
import io.restassured.module.jsv.JsonSchemaValidatorSettings;
import io.restassured.module.jsv.JsonSchemaValidationException;

Basic Usage

import static io.restassured.module.jsv.JsonSchemaValidator.*;
import static io.restassured.module.jsv.JsonSchemaValidatorSettings.*;
import static org.hamcrest.MatcherAssert.assertThat;

// Validate JSON against schema in classpath
String jsonResponse = "{ \"name\": \"John\", \"age\": 30 }";
assertThat(jsonResponse, matchesJsonSchemaInClasspath("user-schema.json"));

// Validate with custom settings
assertThat(jsonResponse, 
    matchesJsonSchemaInClasspath("user-schema.json")
        .using(settings().with().checkedValidation(false)));

// Configure static settings for all validations
JsonSchemaValidator.settings = settings().with().checkedValidation(false);
assertThat(jsonResponse, matchesJsonSchemaInClasspath("user-schema.json"));

Architecture

JSON Schema Validator is built around several key components:

  • JsonSchemaValidator: Main Hamcrest matcher class extending TypeSafeMatcher<String>
  • JsonSchemaValidatorSettings: Configuration class for customizing validation behavior
  • Static Configuration: Global settings that apply to all validator instances
  • Multiple Schema Sources: Support for classpath, file, URL, URI, String, and Stream schema sources
  • Hamcrest Integration: Full compatibility with Hamcrest matcher ecosystem

Capabilities

Schema Validation from Multiple Sources

Core JSON schema validation functionality supporting various schema source types. Perfect for REST API testing and JSON document validation.

/**
 * Creates a Hamcrest matcher that validates JSON documents against schemas from various sources
 */
public static JsonSchemaValidator matchesJsonSchema(String schema);
public static JsonSchemaValidator matchesJsonSchemaInClasspath(String pathToSchemaInClasspath);
public static JsonSchemaValidator matchesJsonSchema(InputStream schema);
public static JsonSchemaValidator matchesJsonSchema(Reader schema);
public static JsonSchemaValidator matchesJsonSchema(File file);
public static JsonSchemaValidator matchesJsonSchema(URL url);
public static JsonSchemaValidator matchesJsonSchema(URI uri);

Usage Examples:

// String schema
String schemaString = "{ \"type\": \"object\", \"properties\": { \"name\": { \"type\": \"string\" } } }";
assertThat(jsonData, matchesJsonSchema(schemaString));

// Classpath resource
assertThat(jsonData, matchesJsonSchemaInClasspath("schemas/user.json"));

// File
File schemaFile = new File("path/to/schema.json");
assertThat(jsonData, matchesJsonSchema(schemaFile));

// URL
URL schemaUrl = new URL("https://example.com/schema.json");
assertThat(jsonData, matchesJsonSchema(schemaUrl));

// URI
URI schemaUri = URI.create("file:///path/to/schema.json");
assertThat(jsonData, matchesJsonSchema(schemaUri));

Custom Validation Configuration

Configure validation behavior using JsonSchemaFactory or JsonSchemaValidatorSettings for advanced validation scenarios.

/**
 * Configure the validator with custom factory or settings
 */
public Matcher<?> using(JsonSchemaFactory jsonSchemaFactory);
public Matcher<?> using(JsonSchemaValidatorSettings jsonSchemaValidatorSettings);

Usage Examples:

import com.github.fge.jsonschema.main.JsonSchemaFactory;
import com.github.fge.jsonschema.cfg.ValidationConfiguration;
import static com.github.fge.jsonschema.SchemaVersion.DRAFTV4;

// Custom JsonSchemaFactory
JsonSchemaFactory factory = JsonSchemaFactory.newBuilder()
    .setValidationConfiguration(
        ValidationConfiguration.newBuilder()
            .setDefaultVersion(DRAFTV4)
            .freeze()
    )
    .freeze();
assertThat(jsonData, matchesJsonSchemaInClasspath("schema.json").using(factory));

// Custom settings
assertThat(jsonData, 
    matchesJsonSchemaInClasspath("schema.json")
        .using(settings().with().checkedValidation(false)));

Static Configuration Management

Global configuration that applies to all validator instances, with reset capability for testing isolation.

/**
 * Static configuration field and reset method
 */
public static JsonSchemaValidatorSettings settings;

/**
 * Reset the static settings to null
 */
public static void reset();

Usage Examples:

// Set global configuration
JsonSchemaValidator.settings = settings().with().checkedValidation(false);

// All subsequent validations use unchecked validation
assertThat(jsonData1, matchesJsonSchemaInClasspath("schema1.json"));
assertThat(jsonData2, matchesJsonSchemaInClasspath("schema2.json"));

// Reset to default state
JsonSchemaValidator.reset();
assertThat(jsonData3, matchesJsonSchemaInClasspath("schema3.json")); // Uses default settings

Validation Settings Configuration

Comprehensive configuration options for customizing validation behavior, JSON schema factory, and URI handling.

/**
 * Configuration class for JSON schema validation settings
 */
public class JsonSchemaValidatorSettings {
    public JsonSchemaValidatorSettings();
    public JsonSchemaValidatorSettings(JsonSchemaFactory jsonSchemaFactory);
    public JsonSchemaValidatorSettings(JsonSchemaFactory jsonSchemaFactory, boolean checkedValidation);
    
    /**
     * Static factory method for creating default settings
     */
    public static JsonSchemaValidatorSettings settings();
    
    /**
     * Configuration methods returning new instances (immutable pattern)
     */
    public JsonSchemaValidatorSettings checkedValidation(boolean shouldUseCheckedValidation);
    public JsonSchemaValidatorSettings parseUriAndUrlsAsJsonNode(boolean parseUriAndUrlsAsJsonNode);
    public JsonSchemaValidatorSettings jsonSchemaFactory(JsonSchemaFactory jsonSchemaFactory);
    
    /**
     * Fluent API methods for method chaining
     */
    public JsonSchemaValidatorSettings and();
    public JsonSchemaValidatorSettings with();
    
    /**
     * Query methods for current configuration
     */
    public JsonSchemaFactory jsonSchemaFactory();
    public boolean shouldParseUriAndUrlsAsJsonNode();
    public boolean shouldUseCheckedValidation();
}

Usage Examples:

// Create settings with different configurations
JsonSchemaValidatorSettings defaultSettings = settings();
JsonSchemaValidatorSettings uncheckedSettings = settings().with().checkedValidation(false);
JsonSchemaValidatorSettings customSettings = settings()
    .with()
    .checkedValidation(false)
    .and()
    .parseUriAndUrlsAsJsonNode(true);

// Custom factory settings
JsonSchemaFactory customFactory = JsonSchemaFactory.byDefault();
JsonSchemaValidatorSettings factorySettings = settings().with().jsonSchemaFactory(customFactory);

Exception Handling

Runtime exception thrown when JSON schema validation encounters errors during processing.

/**
 * Exception thrown when something goes wrong during JSON Schema validation
 */
public class JsonSchemaValidationException extends RuntimeException {
    public JsonSchemaValidationException(Throwable cause);
}

Usage Examples:

try {
    assertThat(invalidJsonData, matchesJsonSchemaInClasspath("schema.json"));
} catch (JsonSchemaValidationException e) {
    // Handle validation processing errors
    System.out.println("Schema validation failed: " + e.getCause().getMessage());
}

Types

/**
 * Main validator class extending Hamcrest TypeSafeMatcher
 */
public class JsonSchemaValidator extends TypeSafeMatcher<String> {
    /**
     * Static configuration field for global settings
     */
    public static JsonSchemaValidatorSettings settings;
}

/**
 * Settings configuration class
 */
public class JsonSchemaValidatorSettings {
    // Constructor and method definitions shown in capabilities above
}

/**
 * Runtime exception for validation errors
 */
public class JsonSchemaValidationException extends RuntimeException {
    public JsonSchemaValidationException(Throwable cause);
}

Error Handling

The library throws JsonSchemaValidationException when:

  • Schema loading fails (malformed schema, file not found, network issues)
  • JSON parsing fails (invalid JSON structure)
  • Internal validation engine errors occur

Validation failures (JSON doesn't match schema) are handled through the Hamcrest matcher framework and result in assertion failures rather than exceptions.

Dependencies

The library requires:

  • Hamcrest: For matcher framework integration
  • Jackson: For JSON parsing (JsonNode)
  • java-json-tools: For JSON schema validation engine
  • Guava: For internal collection utilities