APIs Unleashed 05:
Schema Validation

What is a JSON Schema?

JSON (JavaScript Object Notation) is a simple and lightweight text-based data format. JSON Schema is a specification for JSON based format for defining the structure of JSON data. It was written under IETF draft which expired in 2011.

In short, the main use of JSON schema is to describe the structure and validation constraints of your JSON documents. In contrast to XML, which allows you to create custom dialects, JSON is not as generalizable and flexible, however, it doesn’t want to be. JSON is meant to describe hierarchical data structures in a concise way, a task in which XML is generally considered to be less appropriate than JSON due to the verbose syntax.

We have different keywords that are used in the JSON schema. Let’s see few frequently used and important keywords and what are they about:

– $schema: States that this schema is written according to the draft v4 specification.
– $id: Defines the base URI to resolve other URI references within the schema.
– title: Describes the intent/title of the schema.
– description: Gives the small description of the schema.
– type: Defines the type of data. It defines the first constraint on our JSON data.
– properties: Defines various keys and their value types within a JSON document.
– minimum: Defines the minimum acceptable value for a numeric datatype.
– maximum: Defines the maximum acceptable value for a numeric datatype.
– items: Enumerates the definition for the items that can appear in an array.
– required: Lists the keys that are required and mandatory.

Some advantages of JSON schema are:

– It describes the existing data format.
– It is clear, human- and machine-readable.
– Completes the structural validation and useful in automated testing.
– Helpful in validating client-submitted data.

For more details about the JSON schema please visit https://json-schema.org/

To illustrate this, we will be using the API endpoint:

https://api.dictionaryapi.dev/api/v2/entries/en/hello

The response schema looks like:

KarateDSL: Schema Validation

Let's see how schema validation can be done using KarateDSL

Schema validation can be easily achieved in KarateDSL by using fuzzy matching markers.

Karate offers a wide range of markers for validating JSON schemas such as #string, #array, #notnull, #null, #present, #boolean, #object, and so on.

Sounds intriguing, right? 😃 🤩

Let us understand how we may validate a complex JSON payload’s schema?

Step 1: Create a feature file in the package present under “src/test/java”.

Copy paste below code in the feature file.

Let’s look more closely at the code now-

On looking at the API response, it is clear that the response is in the form of an array with the following keys:

1. word, phonetic, origin: re of the type string. Hence, “#string” marker is used for validation.

2. phonetics and meanings: are of array type. Hence, we have segregated them into 2 variables “phonetics_schema” and “meanings_schema”. These variables is created to store its respective internal schema.

Note:

– “##[] #string” is an ‘in-line’ short-cut for validating JSON arrays. It simply means that key should be null or an array of strings.
– In order to match response with the constructed response schema, w are using “match” keyword.

Step 2: Execute the Runner file.

Step 3: To access the detailed report, copy and paste the report url into your browser.

Failure Case:

Substitute the “#number” key for the “word” key to see whether the test case fails.

In above screenshot, match statement is highlighted in red colour which indicates that the test case is failed due to mismatch in actual and expected variable.

This is how we perform schema validation using KarateDSL.

POSTMAN: Schema Validation

Let's see how schema validation can be done using POSTMAN

We know JSON is a heavily used format nowadays for the REST API calls. Based on that we need to check if the response schema is valid or in-valid. Of course, this is one of the assertion in Postman.

Let’s see in detail how to handle the Schema validation in Postman. We will be using the in-build JavaScript library (AJV) that provides functions to validate JSON schema.

Step 1: Based on our sample response from the documentation/from developer we need to generate the schema. For simple responses you can create manually by understanding the response, in case of larger JSON responses, we have the option of using online JSON schema generator tools like below.

https://www.jsonschema.net/

https://www.liquid-technologies.com/online-json-to-schema-converter

Step 2: We will proceed with https://www.jsonschema.net/. Once you login and open the link, the sample JSON and the schema will be as displayed here:

Step 3: You can paste the sample response of your API in the left panel, received from the developer/API documentation. By clicking “Submit” you will see the JSON schema on the right panel.

Step 4: Create a collection and a request inside that with the Endpoint: https://api.dictionaryapi.dev/api/v2/entries/en/hello. We will be using this public API since the response is complex with nested arrays.

Step 5: Navigate to the “Tests” section and create a variable “schema” and assign with the value generated in the JSON schema generator tool.

Step 6: Now, the assertion to be added for JSON Schema check.

const response = pm.response.json();

pm.test('Schema is valid', () => {
pm.expect(response).to.have.jsonSchema(schema);
});

Step 7: It’ simple as that, now once you click send you can verify if the response schema is matching with the sample schema we defined under the variable “schema”

Now let’s make sure the Test case fails, let’s change our schema. “phonetic” is actually as string type.

Now we edit that as integer.

Click “Save” and “Send”. Now the Test is failing!!

Likewise the Test will fail if there’s a mismatch between the sample schema and the response schema.

In Postman ready-made snippets, you can notice “Use Tiny Validator for JSON Data”. This is almost deprecated and not recommended for use.

So we discussed about handling the schema validation for our APIs using Postman and KarateDSL. For your API Testing, JSON Schema validation for the API responses is most important , and it is mandatory to have checks over this. There are many online tools to verify the JSON schema, but it is always better to have this assertion as part of your Test suite.

Dear readers, thank you for your time. See you in the next few days with our next topic!!