Schema Validation with OpenAPI

Yuri Kan

Schema Validation with OpenAPI

Learn schema validation with OpenAPI/Swagger for API testing. Understand specifications, JSON Schema, and automated validation tools for ensuring API

Quick Answer

Schema Validation with OpenAPI covers essential QA skills — after this lesson you can read and interpret OpenAPI/Swagger specifications.

— Yuri Kan, Senior QA Lead

What You Will Learn

Read and interpret OpenAPI/Swagger specifications
Validate API responses against JSON Schema definitions
Use schema validation tools in automated testing

Table of Contents

What Is OpenAPI?

OpenAPI Specification (formerly known as Swagger) is a standard format for describing REST APIs. It defines every aspect of an API in a machine-readable document: endpoints, HTTP methods, request parameters, response formats, authentication, and data models.

An OpenAPI spec serves as a contract between API providers and consumers. As a tester, it is your source of truth for what the API should do.

OpenAPI vs. Swagger

Swagger was the original name, created by SmartBear
OpenAPI became the standard name after the specification was donated to the Linux Foundation
Swagger UI and Swagger Editor are tools that work with OpenAPI specs
Current version: OpenAPI 3.1 (aligned with JSON Schema)

Reading an OpenAPI Specification

OpenAPI specs are written in YAML or JSON. Here’s a simplified example:

openapi: 3.1.0
info:
  title: User Management API
  version: 1.0.0
  description: API for managing users

servers:
  - url: https://api.example.com/v1

paths:
  /users:
    get:
      summary: List all users
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
            maximum: 100
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
    post:
      summary: Create a new user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUser'
      responses:
        '201':
          description: User created
        '400':
          description: Validation error

components:
  schemas:
    User:
      type: object
      required: [id, name, email]
      properties:
        id:
          type: integer
        name:
          type: string
          minLength: 1
          maxLength: 100
        email:
          type: string
          format: email
        role:
          type: string
          enum: [admin, user, viewer]
        createdAt:
          type: string
          format: date-time

    CreateUser:
      type: object
      required: [name, email]
      properties:
        name:
          type: string
          minLength: 1
        email:
          type: string
          format: email
        role:
          type: string
          enum: [admin, user, viewer]
          default: user

Key Sections

Section	Purpose
`info`	API title, version, description
`servers`	Base URLs for different environments
`paths`	Endpoints with methods and parameters
`components/schemas`	Reusable data models
`security`	Authentication requirements

JSON Schema Fundamentals

JSON Schema defines the structure and validation rules for JSON data. OpenAPI uses JSON Schema for request and response bodies.

Common Types and Constraints

# String with constraints
name:
  type: string
  minLength: 1
  maxLength: 255
  pattern: "^[A-Za-z ]+$"

# Number with range
age:
  type: integer
  minimum: 0
  maximum: 150

# Enum (allowed values)
status:
  type: string
  enum: [active, inactive, suspended]

# Array with item type
tags:
  type: array
  items:
    type: string
  minItems: 1
  maxItems: 10
  uniqueItems: true

# Nullable field
deletedAt:
  type: ["string", "null"]
  format: date-time

Test Cases from Schema

Every schema constraint generates test cases:

Schema Rule	Positive Test	Negative Test
`required: [name]`	Include `name` field	Omit `name` field
`minLength: 1`	Send `"A"`	Send `""` (empty)
`maxLength: 100`	Send 100 chars	Send 101 chars
`minimum: 0`	Send `0`	Send `-1`
`enum: [a, b, c]`	Send `"a"`	Send `"d"`
`type: integer`	Send `42`	Send `"forty-two"`
`format: email`	Send `a@b.com`	Send `not-an-email`

Schema Validation in Practice

Validating with Postman

Use Postman’s built-in JSON Schema validation:

// In Tests tab
const schema = {
  type: "object",
  required: ["id", "name", "email"],
  properties: {
    id: { type: "number" },
    name: { type: "string" },
    email: { type: "string", format: "email" },
    role: { type: "string", enum: ["admin", "user", "viewer"] }
  },
  additionalProperties: false
};

pm.test("Response matches schema", function () {
  const response = pm.response.json();
  const valid = tv4.validate(response, schema);
  pm.expect(valid).to.be.true;
});

Validating with Python (jsonschema)

import jsonschema
import requests

schema = {
    "type": "object",
    "required": ["id", "name", "email"],
    "properties": {
        "id": {"type": "integer"},
        "name": {"type": "string", "minLength": 1},
        "email": {"type": "string", "format": "email"}
    }
}

response = requests.get("https://api.example.com/users/1")
data = response.json()

try:
    jsonschema.validate(instance=data, schema=schema)
    print("Schema validation passed")
except jsonschema.ValidationError as e:
    print(f"Schema validation failed: {e.message}")

Automated Schema Testing with Schemathesis

Schemathesis generates test cases automatically from your OpenAPI spec:

pip install schemathesis

# Run against a live API
schemathesis run https://api.example.com/openapi.json

# With specific checks
schemathesis run https://api.example.com/openapi.json \
  --checks all \
  --stateful=links

It automatically tests boundary values, invalid types, missing fields, and more — all derived from the spec.

Testing Strategy Based on Specs

Spec vs. Implementation Testing

Does the implementation match the spec? — Validate that actual responses conform to documented schemas
Is the spec complete? — Check for undocumented endpoints, fields, or error codes
Are constraints enforced? — Verify that minLength, maxLength, enum, format validations actually work
Are edge cases handled? — Test nullable fields, optional fields, additional properties

Common Schema Bugs

Bug	How to Find
Missing required fields in response	Validate against schema
Wrong data types returned	Schema validation catches `string` vs `integer`
Undocumented fields in response	Use `additionalProperties: false`
Enum values not enforced	Send invalid enum values in requests
Format not validated	Send malformed email, date, URI

Hands-On Exercise

Read a spec: Explore the Petstore API spec in Swagger UI. Identify all endpoints, schemas, and required fields.
Write a JSON Schema for a product object with: id (integer), name (string, 1-200 chars), price (number, min 0), category (enum), inStock (boolean).
Validate responses: Use Postman to send requests to JSONPlaceholder and write schema validation tests for the /posts and /users endpoints.
Find spec violations: Intentionally send invalid data and verify the API returns proper validation errors matching the spec.

Key Takeaways

OpenAPI specifications define the complete contract of an API — endpoints, parameters, request/response schemas, and authentication
JSON Schema provides validation rules (types, ranges, patterns, required fields) that map directly to test cases
Every schema constraint generates both positive and negative test scenarios
Automated tools like Schemathesis can generate comprehensive tests directly from OpenAPI specs
Schema validation catches data type mismatches, missing fields, and contract violations automatically

Knowledge Check

1. What is the primary purpose of an OpenAPI specification?

2. In JSON Schema, what does the 'required' array specify?

3. Which tool generates interactive API documentation from OpenAPI specs?

Frequently Asked Questions

What is schema validation with openapi?

Schema Validation with OpenAPI is a key concept in API and Backend Testing. This lesson teaches you to read and interpret OpenAPI/Swagger specifications, providing practical skills you can apply immediately in your testing work.

How do I apply schema validation with openapi in real projects?

Start by practicing the core techniques covered in this lesson. Specifically, you should validate API responses against JSON Schema definitions. Apply these skills in your current project to see immediate results.

Why is schema validation with openapi important for QA engineers?

Schema Validation with OpenAPI is a core skill that employers look for in QA professionals. It directly impacts test coverage, defect detection, and team efficiency. Mastering it strengthens your API and Backend Testing capabilities and makes you more effective at delivering quality software.

What should I know before learning schema validation with openapi?

You should have a basic understanding of software testing fundamentals. Familiarity with openapi validation will help, but the lesson includes review sections for key prerequisites.

How does schema validation with openapi help my QA career?

Knowledge of schema validation with openapi is frequently listed in QA job descriptions and interview questions. It demonstrates expertise in openapi validation, schema validation and shows you can contribute to quality assurance at a professional level. Senior roles especially value this competency.

Schema Validation with OpenAPI

What You Will Learn

What Is OpenAPI? #

OpenAPI vs. Swagger #

Reading an OpenAPI Specification #

Key Sections #

JSON Schema Fundamentals #

Common Types and Constraints #

Test Cases from Schema #

Schema Validation in Practice #

Validating with Postman #

Validating with Python (jsonschema) #

Automated Schema Testing with Schemathesis #

Testing Strategy Based on Specs #

Spec vs. Implementation Testing #

Common Schema Bugs #

Hands-On Exercise #

Key Takeaways #

Knowledge Check

Frequently Asked Questions

What Is OpenAPI?

OpenAPI vs. Swagger

Reading an OpenAPI Specification

Key Sections

JSON Schema Fundamentals

Common Types and Constraints

Test Cases from Schema

Schema Validation in Practice

Validating with Postman

Validating with Python (jsonschema)

Automated Schema Testing with Schemathesis

Testing Strategy Based on Specs

Spec vs. Implementation Testing

Common Schema Bugs

Hands-On Exercise

Key Takeaways