How to validate JSON schemas from a Data API in Python: step by step

This tutorial shows how to validate JSON schemas from a Data API in Python to ensure that the received data is in the expected format and reduce downstream errors. Validation is useful to detect missing fields, wrong types and unexpected structures before processing or loading data.

Prerequisites

• Python 3.8+ installed
• Pip to install packages (requests, jsonschema)
• Basic knowledge of JSON and Python

Step 1: Why validate JSON from a Data API

APIs can change, return optional fields or different types. Validating with a schema prevents processing code from failing silently and makes logging and alerts easier. A JSON Schema (standard) is used to describe structure, types and required fields.

Step 2: Install dependencies

Install the necessary packages: requests to call the API and jsonschema to validate. It’s simple and quick.

pip install requests jsonschema

Step 3: Define a minimal JSON Schema

Create a schema that describes the essential fields you expect from the API. Here is an example for user data with id, name and email. Adjust according to your API.

user_schema = {
    "type": "object",
    "properties": {
        "id": {"type": "integer"},
        "name": {"type": "string"},
        "email": {"type": "string", "format": "email"},
        "created_at": {"type": "string", "format": "date-time"}
    },
    "required": ["id", "name", "email"]
}

Step 4: Call the API and validate a single response

Use requests to get JSON and jsonschema.validate to check it. Handle exceptions to report clear errors (type, missing field, format).

import requests
from jsonschema import validate, ValidationError

url = "https://api.exemplo.com/users/123"  # substitui pela tua endpoint
resp = requests.get(url, timeout=10)
resp.raise_for_status()
data = resp.json()

try:
    validate(instance=data, schema=user_schema)
    print("Validação OK")
except ValidationError as e:
    print("Validação falhou:", e.message)

Step 5: Validate lists of records and collect errors

When the API returns a list, validate each item and accumulate errors. That way you can process valid records and log the invalid ones for inspection.

url = "https://api.exemplo.com/users"
resp = requests.get(url, params={"page": 1}, timeout=10)
resp.raise_for_status()
items = resp.json()

valid_items = []
errors = []
for i, item in enumerate(items):
    try:
        validate(instance=item, schema=user_schema)
        valid_items.append(item)
    except ValidationError as e:
        errors.append({"index": i, "error": e.message, "item": item})

print(f"{len(valid_items)} registos válidos, {len(errors)} inválidos")

Step 6: Deal with optional fields and flexible schemas

If the API has additional fields, use "additionalProperties": true or define a subschema for extra fields. For schemas that change frequently, validate only the essential fields (minimize false positives).

flex_schema = {
    "type": "object",
    "properties": {
        "id": {"type": "integer"},
        "name": {"type": "string"}
    },
    "required": ["id"],
    "additionalProperties": True
}

Step 7: Common errors and how to fix them

Common errors: missing format (use formats or validate manually), integer types sent as string (convert or accept both with "oneOf"), and optionally absent fields. Log the raw response when detecting an error for diagnosis.

from jsonschema import Draft7Validator

validator = Draft7Validator(user_schema)
for error in sorted(validator.iter_errors(data), key=str):
    print(error.message)

Verify the result

Test with real calls: you should see "Validação OK" for conforming records and receive clear messages for failures. For lists, confirm that valid_items contains only valid records and that errors has entries with error messages. Add logs with URL, status code and payload when a validation fails.

Conclusion

Validating JSON schemas from a Data API in Python reduces failures and makes it easier to detect API changes. Next steps: integrate validation into an ETL pipeline, automate tests with fixtures and use CI to alert when the API changes. Tip: start by validating only critical fields and expand the schema as you gain confidence — do you have any specific API you want to validate?