Validating JSON Against Schemas via API
What is JSON Schema Validation?
JSON Schema is a vocabulary that lets you annotate and validate JSON documents.
It defines the structure, required fields, value types, and constraints for a JSON payload.
Rather than writing custom validation logic in every service, you can express your rules
declaratively in a .json schema file and validate any payload against it.
Why Validate at the API Layer?
Pushing validation to an API endpoint means:
- Language-agnostic — any client (Python, JS, Go, curl) can validate the same way
- Consistent errors — a single source of truth for schema definitions
- CI-friendly — easy to integrate into pipelines without adding a library dependency
Using the Convert API
Send a POST to the validation endpoint with two fields: schema and data.
{
"schema": {
"type": "object",
"required": ["email", "age"],
"properties": {
"email": { "type": "string", "format": "email" },
"age": { "type": "integer", "minimum": 0 }
}
},
"data": {
"email": "[email protected]",
"age": -1
}
}
The API returns a structured result listing every validation error with the path, keyword that failed, and a human-readable message.
Common Schema Patterns
| Pattern | Schema snippet |
|---|---|
| Required string | "type": "string" |
| Integer range | "minimum": 1, "maximum": 100 |
| Enum | "enum": ["active", "inactive"] |
| Array of objects | "type": "array", "items": { "$ref": "#/defs/Item" } |
| Optional field | Omit from required array |
Error Response Shape
{
"valid": false,
"errors": [
{
"path": "/age",
"keyword": "minimum",
"message": "-1 is less than the minimum of 0"
}
]
}
When valid is true, the errors array is empty.
Integrating Into a CI Pipeline
Add a validation step to your GitHub Actions workflow:
- name: Validate API payload
run: |
curl -sf -X POST https://api.toolkitapi.io/v1/convert/json-schema-validate \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d @tests/fixtures/payload.json | jq -e '.valid == true'
This fails the build if any payload violates the schema, catching breaking changes before deployment.