Using Postman to Test Schemas: ReadMe Documentation

This guide explains how to use Postman to test and validate schemas effectively. Postman is a powerful tool for API development that allows you to send requests, validate responses, and test schemas for compliance.

Prerequisites

Before testing schemas with Postman, ensure you have:

• Postman installed on your system. Download it from Postman’s website.
• A basic understanding of API requests and responses.
• Access to the API you wish to test, including:
  • Endpoint URL
  • Authentication details (if required)
  • API documentation
• The schema you want to test (e.g., JSON Schema).

Importing the API Schema

1. Open Postman and navigate to the Collections tab.
2. Click the "+" button to open up a new tab.

3. In the URL bar, add the BaseURL and add the endpoint to the BaseUrl. E.g. https://api.example.com/v1/status
4. 
   

1. Click on the ... (More options) menu and choose Add Schema.
2. Paste or upload your schema (e.g., JSON Schema).
3. Save the schema to associate it with your collection.

Setting Up Your Environment

1. Go to the Environments tab in Postman.
2. Create a new environment and add variables for dynamic values, such as:
   • base_url
   • api_key
3. Use these variables in your requests (e.g., {{base_url}}/endpoint).

Creating Requests

1. Go to the Collections tab and select your collection.
2. Click Add Request to create a new request.
3. Fill in the details:
   • Request Type: GET, POST, PUT, DELETE, etc.
   • URL: Include your endpoint URL.
   • Headers: Add necessary headers (e.g., Content-Type: application/json).
   • Body: Add the request payload if required.
4. Save your request.

Testing Schemas

Step 1: Attach the Schema to a Request

1. Open the request you wish to test.
2. Scroll to the Tests tab below the request builder.
3. Add a script to validate the response schema against the imported schema.

Step 2: Write Schema Validation Script

Here’s a sample script for JSON Schema validation:

const schema = pm.collectionVariables.get('schema'); // Retrieve schema
const response = pm.response.json(); // Get response as JSON

pm.test('Response matches schema', function () {
    pm.expect(tv4.validate(response, JSON.parse(schema))).to.be.true;
});

Alternatively, if you’re using ajv (recommended for complex schemas):

const Ajv = require('ajv');
const ajv = new Ajv();
const schema = pm.collectionVariables.get('schema');
const response = pm.response.json();

pm.test('Response matches schema', function () {
    const validate = ajv.compile(JSON.parse(schema));
    const valid = validate(response);
    pm.expect(valid).to.be.true;
    if (!valid) console.log(validate.errors);
});

Using Tests for Schema Validation

1. Send the request to the API endpoint.
2. Postman will validate the response against the schema.
3. If the schema validation passes, the test will succeed. If not, errors will appear in the test results.

Troubleshooting Common Issues

Invalid Schema

• Check that your schema follows the correct JSON Schema format.
• Use an online schema validator to verify.

Test Script Errors

• Ensure your schema is correctly stored as a variable in Postman.
• Verify your test script syntax.

Schema Mismatch

• Ensure the API response matches the schema structure, data types, and required fields.

By following this guide, you can effectively test and validate schemas using Postman, ensuring your API responses meet the expected structure and data requirements.