JSON schema validation in Postman using external JSON files
Tags: testing, webdev, postman, api
Published: 2019-08-05 14:03:39

---
title: JSON schema validation in Postman using external JSON files
published: true
description: JSON schema validation in Postman using external JSON files
tags: testing, webdev, postman, api
cover_image: https://thepracticaldev.s3.amazonaws.com/i/xxaqhmiaz7se9r02jr7o.png
---

Postman is an excellent tool for testing APIs. The response for an API call can be validated against a JSON schema to ensure that the values are valid in terms of type and format. In this article, we will explore how external JSON files can be loaded into Postman to avoid duplication of schema, in turn, making the tests more maintainable.

Postman does not (as of v7.3.4) support the ability to reference external libraries and files. Which means that we will have to get the schema loaded in the environment variable to parse and use it.

##Primer on JSON schema & Tiny Validator library
Before we begin, it would be wise to have some understanding of [JSON schema](https://json-schema.org/understanding-json-schema/) and [Tiny validator library](https://geraintluff.github.io/tv4/) which is used for the schema validation. For the purpose of demonstration, we have four entities Campaign, Media, Sponsor, and MediaType. Campaign requires an object of Media and optionally a Sponsor. Sponsor requires an object of Media.

![](https://thepracticaldev.s3.amazonaws.com/i/1q1tci34cqgb6lc6sbqc.png)

The following are the schemas for the above-listed entities.
* `common-schema.json` — Contains the schema for common elements that are to be reused across the entire application
* `advertisement-schema.json` — Contains schema for all elements corresponding to a module called advertisement in the application.

![Figure-1 common-schema.json](https://thepracticaldev.s3.amazonaws.com/i/v0kmle7nkb08cgi636xg.png)
<figcaption>Figure-1 common-schema.json</figcaption>

View on GitHub: [https://gist.github.com/charanraj-golla/82bd2e51733cec512aab8f2d1e2713e0](https://gist.github.com/charanraj-golla/82bd2e51733cec512aab8f2d1e2713e0)

![Figure-2 advertisement-schema.json](https://thepracticaldev.s3.amazonaws.com/i/93fttos2rvohltxydaa6.png)
<figcaption>Figure-2 advertisement-schema.json</figcaption>

View on GitHub: [https://gist.github.com/charanraj-golla/1823c488895c177c4c449c4cbc11c407](https://gist.github.com/charanraj-golla/1823c488895c177c4c449c4cbc11c407)


Following methods from tiny Validator can be used to validate the results from an API response:
* `tv4.validate()`
* `tv4.validateResult()`
* `tv4.validateMultiple()`

These methods accept four parameters:
* `data`
* `schema`
* `checkRecursion`
* `banUnknownProperties`

The first two are mandatory without which the validation won’t work. Passing `true` for `checkRecursion` will recursively validate the nested schema. Setting `banUnknownProperties` to `true` will result in a schema error if there are any additional properties apart from those which were defined in the schema. This is the bare minimum about this library that we must know for writing the tests.

Next, we need to have some idea about `$ref` and `$id` keywords in JSON Schema. `$ref` gets logically replaced with the thing that it points to. This referenced section can be within the same file or in an external file. The value of `$ref` is a URI, and the part after `#` sign (pound sign) is “the fragment” or “named anchor” and is in a format called JSON Pointer.

![Figure-3 The underlined section will be replaced with value for the key “sponsor”, available in the same file. Refer Figure-1 for details of the sponsor](https://thepracticaldev.s3.amazonaws.com/i/t4uatwled5rjqbocw079.png)

Next in line is the `$id` property. The value of `$id` is a URI that serves two purposes:
* It declares a unique identifier for the schema. (Figure-4)
* It declares a base URI against which `$ref` URIs are resolved. (Figure-5)

`$id` given to a subschema, in this case, the address provides a way to refer to subschema without using JSON Pointer. This means you can refer to them by a unique name as shown in the below example (Figure-4).

![Figure-4 Unique identifier in a schema.](https://thepracticaldev.s3.amazonaws.com/i/t14z0wzgse3mzorb09rk.png)
<figcaption>Figure-4 Unique identifier in a schema.</figcaption>

In the case where `$id` is used to provide the base URI, a subschema present in the same file can be referenced as `"$ref" : "#/definitions/sponsor"` which essentially means :
1. Go to the root of this document
2. Find value with the key definition
3. Within that object find the value of the key sponsor

![Figure-6 Using JSON pointer](https://thepracticaldev.s3.amazonaws.com/i/0i0b5s44yzknf53krdc0.png)
<figcaption>Figure-6 Using JSON pointer</figcaption>

Going back to our example, Media property in Campaign object expects an array of objects of the type Media. The schema for the array item must be specified against the items property. The schema for media is present in a separate file named common-schema.json (Figure-1). Here we are using absolute URI along with JSON pointer. The intent of using an absolute URI will be clear once we start writing the tests. Note that Postman does not make any network calls to the given URI.

> Even though the value of a `$ref` is a URI, it is not a network locator, only an identifier. This means that the schema doesn’t need to be accessible at that URI, but it may be. It is basically up to the validator implementation how external schema URIs will be handled, but one should not assume the validator will fetch network resources indicated in `$ref` values.


##Setup for validation
The schema needs to be loaded into Postman’s environment variable before running tests for the collection. Include all schemas in the solution and add a controller for reading the schema files.

![Figure-7 Visual Studio solution setup](https://thepracticaldev.s3.amazonaws.com/i/l56x7ektqws7skir00lg.png)
<figcaption>Figure-7 Visual Studio solution setup</figcaption>


{% gist https://gist.github.com/charanraj-golla/e15bf1fd837722ded838f045c038f45a %}

Add a folder to the collection right before any other requests are made and add requests to GetSchema action method.

![Figure-8 Test setup in Postman](https://thepracticaldev.s3.amazonaws.com/i/mv5ms74imd18eolg1iq1.png)
<figcaption>Figure-8 Test setup in Postman</figcaption>

In test tab for each request in the TestSetup folder, save the response to a unique environment variable. Paste the following code in the tests tab:

{% gist https://gist.github.com/charanraj-golla/01a0683b0ac8efe2ca21a0fecbefe5fc %}

This setup gives you full IDE support for editing the JSON files and saves the time you would have spent trying to edit the JSON string in the single-line text box every time there were changes are made to the schema.

![Figure-9 Environment variable set after GET request was executed](https://thepracticaldev.s3.amazonaws.com/i/8u8hu8o9bi5wct9g3hno.png)
<figcaption>Figure-9 Environment variable set after GET request was executed</figcaption>

Finally, in order to validate the schema, all the required schemas which are currently available in the environment variables (stored as a string) must be parsed to JSON and registered in the Tiny Validator. This can be done using `tv4.addSchema()`. It accepts two parameters URI and schema object. An important point to note is that the URI used for registering the schema overrides the value specified for `$id` key in the JSON file while registering the schema. This means that the URI you use to register the schema in `tv4.addSchema()` function must be used while specifying the JSON pointer. When all the required schemas are registered using the `tv4.addSchema()` function, any references in the schema will be automatically resolved.


{% gist https://gist.github.com/charanraj-golla/1dcf4e1f09cef04d3fb0b3c1533aefe4 %}

A response body similar to the one listed below would successfully pass the test.

{% gist https://gist.github.com/charanraj-golla/67828e5fb057e86ddb64d665d1ec5a38 %}

![](https://thepracticaldev.s3.amazonaws.com/i/see5cka9eaaktojqtqb3.png)

`tv4.validate()` will stop at first error and return a false value. It would be ideal to have a list of all errors for a request. `tv4.validateMultiple()` returns an array of validation result which can be iterated over to find the error details for a property. Remember to keep the console (Ctrl + Alt + C) window open when you are running the test.

To verify if the schema validation really works as expected we can alter the response making it invalid. Value for alternateName in sponsor → media is changed to a number instead of a string and an unknown property called `aBadField` is added as well.

{% gist https://gist.github.com/charanraj-golla/231de100907725394d64ad4b40aead39 %}

The validation fails and the postman console logs the exact path and the cause of the error.

![Test fails due to invalid property values](https://thepracticaldev.s3.amazonaws.com/i/x6h8oornbcysebj0qndw.png)
<figcaption>Test fails due to invalid property values</figcaption>

![Exact path of error logged in Postman console](https://thepracticaldev.s3.amazonaws.com/i/f53af6q4yf4bj4gyqhih.png)
<figcaption>Exact path of error logged in Postman console</figcaption>

Hope this post saves you some time while testing your APIs. I would appreciate your constructive feedback in improving this post. Got any handy tips on validating the APIs? Let's discuss :)


*This article was originally published on [SkillHive Blog](https://medium.com/skillhive/json-schema-validation-in-postman-using-external-json-files-2f3f0741800f "JSON schema validation in Postman using external JSON files")*