Cypress API Testing — Schema Validation with AJV

Reaching a higher level of automated API testing

Schema Validation

As we query the various endpoints as part of an API we are typically given a response. This response follows a specified schema set by the developers when they built the API and is traditionally returned as JSON. There are different schemas for different endpoints and even schemas based on the status of the API call. As QA, we could/should go the extra distance and verify that the schema returned is valid.

Another JSON Schema Validator (AJV)

Cypress has a marvelous post that you can read through on schema validation using JSON Schemas here


I have setup a very basic project to demonstrate schema validation, here is the link. This demo project queries the free-to-use and awesome cat-facts API.


In the demo project, you will find a few custom commands. For instance, the following snippet is an API helper custom command. It accepts two query parameters, one for the animal type and an optional param for the number of facts to get. This custom command fires off a GET request which populates the queryParams (url variables) using Cypress’ qs option.


For the sake of this demonstration, we will only be setting up a schema check on the body of the of the response. However, you can go further and also verify the response headers should you wish to do so.

  • properties are the keys in the response, such as deleted or status
  • properties can be nested and each property should have a type
  • assume that the types we specify is us telling AJV what datatype to expect with the corresponding property, for example, deleted should always be a boolean (true/false)
  • enums can be used to inform AJV that only the specified values should return with a particular property
  • enums should only be used when you know precisely which values should return
  • patterns are regex patterns and a great way to describe the pattern of the value, for example you may have an id that should only return x number of characters
  • required is an array that goes at the end of the schema and is a way of telling AJV that the listed members should always exist/return in the response schema
$ref: "customDefinitions#/definitions/dateTime"
  • validate combines the custom definitions schema along with the given local schema, enabling our references to the custom definitions called from the local schema to function correctly
  • valid is where the magic happens and compares the local schema to the response schema
  • if any errors occur, the whole error object is passed down to the getSchemaError function which returns a clear representation of what the issue is
  • an error must be thrown to fail the test if the schema has errors, otherwise Cypress will pass the test

Running the Tests

Import the local schema and supplement the validateSchema custom command with the correct parameters in your test, making sure to pass the response schema at the correct level using dot or bracket notation; remember, the custom command we setup is a like-for-like comparison, so your response schema should start from the same place as your defined local schema, in this case, we set it up to validate the contents of the response.body.


Other than gaining additional confidence in your API tests, Schema Validation is a great substitute for in-line response key assertions using Cypress & Chai; when properly configured, it saves you allot of bloat and reduces repetition.

Software Developer in Test