Skip to content
Owais Khan Software Reviews
How-To Guides

What Is JSON Schema in REST Assured: A Precise Reference Guide

Learn what JSON Schema is in REST Assured, how it validates API responses, and see a complete worked example with configuration options.

By Owais Khan

JSON Schema in REST Assured is a mechanism that lets you verify whether an API’s JSON response body conforms to a predefined structural contract — checking data types, required fields, and allowed values — without manually inspecting every field in the response.

The Purpose of JSON Schema Validation in REST Assured

When you test a REST API, you often want to confirm the shape of the response before diving into individual field values. JSON Schema is a specification that defines the structure, format, and constraints of JSON documents. It provides a way to describe the expected structure of JSON data, making it a valuable tool for ensuring the integrity of data exchanged between API clients and servers. JSON Schema uses a JSON object to define rules and constraints that JSON data must adhere to — these rules can include data types, required fields, allowed values, and more.

REST Assured’s json-schema-validator module bridges that specification and your test suite. Instead of writing a chain of .body("field", equalTo(...)) assertions for every property, you point REST Assured at a schema file and it confirms the entire response structure in one assertion. This is especially useful when a contract changes: the schema file is the single source of truth, and every test that references it automatically picks up the new rules.

The Exact Rules That Govern JSON Schema Validation in REST Assured

Three layers of rules control how validation works:

1. The Maven dependency The feature lives in a separate module. You must add io.rest-assured:json-schema-validator (version 5.5.0 as of the latest release) to your pom.xml with <scope>test</scope>. Without this module the matchesJsonSchemaInClasspath matcher is not available.

2. The schema file itself A JSON Schema document must begin with the $schema keyword, which declares the URI of the specification version being used (for example http://json-schema.org/draft-07/schema#). The core keywords you use inside the schema are:

  • type — declares the expected JSON type for a value
  • properties — maps field names to their own sub-schemas (for objects)
  • items — describes the expected elements inside an array
  • required — lists which property names must be present

3. The validator’s checked-validation default By default the json-schema-validator runs checked validations. This means that if the schema declares a field as an array, any response where that field is a string will fail — the validator enforces strict type conformance. You can relax this by setting checkedValidation(false) either per-test or globally.

Reference Table: JSON Schema Keywords and REST Assured Configuration Options

Concern Keyword / Method Effect
Schema version declaration $schema in the JSON file Tells the validator which draft to apply
Value type constraint type (object, array, string, number, boolean, null) Fails if the actual value is a different type
Object field definitions properties Defines sub-schemas for each named field
Array element definitions items Defines the sub-schema every array element must match
Mandatory fields required Lists field names that must exist in the response
Per-test schema version .using(jsonSchemaFactory) with SchemaVersion.DRAFTV4 Overrides the detected draft for one test
Per-test strict mode off .using(settings().with().checkedValidation(false)) Allows type mismatches for one test
Global strict mode off JsonSchemaValidator.settings = settings().with().checkedValidation(false) Applies to all tests until reset
Reset global config JsonSchemaValidator.reset() Clears any global settings

Supported draft versions include draft-03, draft-04, draft-06, draft-07, 2019-09, and 2020-12. The version is detected automatically from the $schema keyword; schemas without $schema are validated as draft-04 by default unless you specify another version explicitly.

Worked Example: Validating a Product Catalog API Response

Imagine your API returns a single product at GET /products/42:

{
 "productId": 42,
 "name": "Wireless Keyboard",
 "inStock": true,
 "tags": ["electronics", "peripherals"]
}

Step 1 — Write the JSON Schema file (product-schema.json, placed in src/test/resources/):

{
 "$schema": "http://json-schema.org/draft-07/schema#",
 "type": "object",
 "properties": {
 "productId": { "type": "integer" },
 "name": { "type": "string" },
 "inStock": { "type": "boolean" },
 "tags": {
 "type": "array",
 "items": { "type": "string" }
 }
 },
 "required": ["productId", "name", "inStock"]
}

This schema declares: the root must be an object; productId must be an integer; name must be a string; inStock must be a boolean; tags, when present, must be an array of strings; and productId, name, and inStock are all required.

Step 2 — Add the dependency to pom.xml:

<dependency>
 <groupId>io.rest-assured</groupId>
 <artifactId>json-schema-validator</artifactId>
 <version>5.5.0</version>
 <scope>test</scope>
</dependency>

Step 3 — Write the REST Assured test:

import static io.restassured.RestAssured.get;
import static io.restassured.module.jsv.JsonSchemaValidator.matchesJsonSchemaInClasspath;

@Test
public void givenProductEndpoint_whenResponseMatchesSchema_thenCorrect() {
 get("/products/42")
.then()
.assertThat()
.body(matchesJsonSchemaInClasspath("product-schema.json"));
}

REST Assured fetches the response, passes the body to the json-schema-validator module, and the module checks every rule in product-schema.json. If productId came back as a string instead of an integer, or if name were missing entirely, the test fails immediately with a descriptive message — no per-field assertion needed.

Step 4 — Add a per-test schema version override (optional, for teams that pin to draft-04):

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

@Test
public void givenProductEndpoint_whenValidatedWithDraftV4_thenCorrect() {
 JsonSchemaFactory factory = JsonSchemaFactory.newBuilder()
.setValidationConfiguration(
 ValidationConfiguration.newBuilder()
.setDefaultVersion(SchemaVersion.DRAFTV4)
.freeze())
.freeze();

 get("/products/42")
.then()
.assertThat()
.body(matchesJsonSchemaInClasspath("product-schema.json")
.using(factory));
}

Where the Rules Differ by Context or Version

Draft version detection vs. explicit override When your schema file includes $schema, the validator detects the draft automatically. When $schema is absent, the module defaults to draft-04. If you need a different default — say draft-03 for a legacy contract — you must set it explicitly via JsonSchemaFactory and SchemaVersion.DRAFTV3 in a global configuration block, then call JsonSchemaValidator.reset() in a teardown method to avoid polluting other tests.

Checked vs. unchecked validation The distinction between checked and unchecked validation is the most common source of confusion. Checked validation (the default) enforces strict type matching: a field declared as an array must always be an array. Unchecked validation relaxes this, which can be useful during early development when the API contract is still evolving. You can toggle this globally or per-test without changing the schema file itself.

Global vs. per-test configuration For small test suites, per-test configuration using .using(...) is clear and explicit. For large suites, repeating the same JsonSchemaFactory setup in every test is error-prone. The global JsonSchemaValidator.settings field lets you define the configuration once. Always pair a global setup with a JsonSchemaValidator.reset() call in an @AfterClass or @AfterAll method so the configuration does not leak between test classes.

Generating the schema file Writing a schema by hand for a complex response is tedious. If you already have a sample JSON response, you can use the free OpenAI Structured Outputs JSON Schema Converter to produce a starting schema, then refine the required array and add any additional constraints your contract demands before saving the file to src/test/resources/.

Open the OpenAI Structured Outputs JSON Schema Converter

Frequently asked questions

What is the purpose of JSON Schema in REST Assured?
JSON Schema in REST Assured lets you confirm that an entire API response body conforms to a predefined structural contract — covering data types, required fields, and value constraints — in a single assertion, without manually checking every field. This catches structural regressions early in the development process.
Which Maven dependency do I need to use JSON Schema validation in REST Assured?
You need the `io.rest-assured:json-schema-validator` module added to your `pom.xml` with `<scope>test</scope>`. The latest version is 5.5.0.
Which JSON Schema draft versions does REST Assured support?
REST Assured's json-schema-validator supports draft-03, draft-04, draft-06, draft-07, 2019-09, and 2020-12. The version is detected automatically from the `$schema` keyword in your schema file; schemas without `$schema` default to draft-04.
What does 'checked validation' mean in REST Assured's JSON Schema validator?
Checked validation (the default) means the validator strictly enforces the types declared in the schema — for example, a field declared as an array must always be an array in the response. You can disable this strictness by setting `checkedValidation(false)` either per-test or globally.
How do you apply a JSON Schema validation setting to all tests at once?
You set `JsonSchemaValidator.settings` once (for example, to disable checked validation or pin a schema version), and it applies to every subsequent test. Call `JsonSchemaValidator.reset()` in a teardown method to clear the global configuration and prevent it from affecting other test classes.
Where should the JSON Schema file be placed in a Java project?
The schema file should be placed in `src/test/resources/` so it is available on the test classpath. The `matchesJsonSchemaInClasspath` method then resolves it by filename alone, with no path prefix required.