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.
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 valueproperties— maps field names to their own sub-schemas (for objects)items— describes the expected elements inside an arrayrequired— 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