Introducing Postman Collection Format Schema

Aniket

July 2, 2015

In our last blog post on collection formats, we talked about the new collection file format that Postman is heading towards. With the learnings from the collection format V1, we knew that we needed an easy way of answering whether a given JSON file is indeed a valid Collection.

This was the perfect opportunity to put JSON-Schema to use. Traditionally, JSON-Schema is used to validate inputs to HTTP endpoints, but validation of a JSON file is one of several valid use cases. Besides, there’s already some great tooling around JSON schema, and libraries such as is-my-json-valid really make the job easier. The support for $ref doesn’t hurt either, references help to keep the schema modular.

As part of the initial work towards Collections-V2, we decided to release a schema for the current Collection format (V1), and the associated documentation for it. This schema will validate collections if they’re exported from client versions 1.x.x and above.

The schema file is located at https://schema.getpostman.com/json/collection/v1/

The associated documentation can be found at https://schema.getpostman.com/json/collection/v1/docs/

Everything neatly stored on GitHub: https://github.com/postmanlabs/schemas

Putting the schema to (good) use

As the name suggests, schemas help with data validation. There are a number of options for validating JSON data using schemas. Here ‘s a short example using is-my-json-valid.

var https = require('https'),
    // use the is-my-json-valid module.
    // ensure you have installed it.
    validate = require('is-my-json-valid');

// this is our sample input (blank) JSON.
var input = {
    /* JSON of a collection V1 */
};

// we fetch the schema from server and when it is received, 
// validate our input JSON against it.
https.get('https://schema.getpostman.com/json/collection/v1/', function (response) {
    var body = '';

    response.on('data', function (d) {
        body += d;
    });

    response.on('end', function () {
        var validate = validator(JSON.parse(body));
        console.log(validate(input) ? 'It is valid!' : 'It is invalid!');
    });
});

We are also planning to release command line utilities and libraries that will allow you to easily slice-and-dice Postman collections. Stay tuned!