JSON has become one of the most common formats for exchanging data between applications. Whether you are building a REST API, developing a web application, integrating third-party services, or working with a mobile application, there is a good chance that JSON is part of your daily development workflow.
But there is one problem developers frequently encounter: valid JSON does not necessarily mean correct JSON.
Consider this example:
{
"name": "John",
"email": 12345,
"age": "thirty"
}This is perfectly valid JSON syntax. However, imagine that your application expects an email address as a string and an age as a number.
The data is syntactically valid but does not follow the expected structure.
This is where JSON Schema validation becomes useful.
In this guide, we will explore what JSON Schema is, why developers use it, how to create schemas, and how to validate JSON data using practical examples.
What Is JSON Schema?
JSON Schema is a specification that allows developers to describe the expected structure, data types, and rules of a JSON document.
Think of it as a set of instructions that tells your application what valid data should look like.
For example, if you are developing a user registration API, you might expect the following:
Name must be a string.
Email must be a string.
Age must be a number.
Email and name are required.
Age must be at least 18.
JSON Schema allows you to define these requirements in a structured format.
Instead of manually checking every property in your application, you can use a JSON Schema validator to evaluate incoming data against your defined rules.
Why Is JSON Schema Validation Important?
When applications communicate with each other, they exchange data that may come from different sources.
These sources might include:
Frontend applications.
Mobile applications.
Third-party APIs.
External payment gateways.
Database records.
Microservices.
You cannot always assume that incoming data will have the expected structure.
JSON Schema validation helps catch these problems before they create unexpected application behavior.
1. Prevent incorrect data types
Suppose your application expects a product price as a number, but an API sends it as text.
Without validation, this could cause calculation errors or unexpected behavior.
2. Ensure required fields are present
Applications often depend on specific fields.
For example, an order creation API may require:
Customer ID.
Product ID.
Quantity.
Payment method.
JSON Schema can ensure these properties exist before the application processes the request.
3. Improve API reliability
When different applications communicate through APIs, both sides need a clear understanding of the expected data structure.
A shared JSON Schema provides that contract.
4. Reduce debugging time
Instead of discovering invalid data later in the application workflow, validation can identify problems closer to the point where data enters the system.
Understanding the Basic JSON Schema Structure
Let's start with a simple example.
Imagine you are building an API that accepts customer information.
The expected JSON data looks like this:
{
"name": "John Smith",
"email": "john@example.com",
"age": 28
}We can define its schema as follows:
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "Customer",
"type": "object",
"properties": {
"name": {
"type": "string"
},
"email": {
"type": "string"
},
"age": {
"type": "integer"
}
},
"required": ["name", "email", "age"]
}Let's understand the important properties.
Keyword | Purpose |
|---|---|
| Identifies the JSON Schema specification version. |
| Provides a readable schema name. |
| Defines the expected data type. |
| Defines the allowed object properties and their schemas. |
| Specifies which properties must be present. |
The example uses JSON Schema Draft 2020-12.
Common JSON Schema Data Types
JSON Schema supports several fundamental data types.
String
Used for text values.
{
"type": "string"
}Number
Used for numeric values, including integers and decimal numbers.
{
"type": "number"
}Integer
Used for whole numbers.
{
"type": "integer"
}Boolean
Used for true or false values.
{
"type": "boolean"
}Array
Used for collections of values.
{
"type": "array",
"items": {
"type": "string"
}
}Object
Used for structured key-value data.
{
"type": "object",
"properties": {
"firstName": {
"type": "string"
}
}
}Null
Used when a value is explicitly null.
{
"type": "null"
}Understanding these data types is the foundation of writing useful JSON Schemas.
Practical Example: Validating an E-commerce Product
Let's use a real-world e-commerce example.
Suppose you are building a product catalog API that receives product information.
A product might contain:
Product ID.
Product name.
Price.
Availability.
Product categories.
Stock quantity.
Here is an example of valid product data:
{
"productId": 101,
"productName": "Wireless Headphones",
"price": 79.99,
"available": true,
"categories": [
"Electronics",
"Audio"
],
"stock": 25
}Now let's create a JSON Schema for this product.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "Product",
"type": "object",
"properties": {
"productId": {
"type": "integer",
"minimum": 1
},
"productName": {
"type": "string",
"minLength": 3
},
"price": {
"type": "number",
"exclusiveMinimum": 0
},
"available": {
"type": "boolean"
},
"categories": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1
},
"stock": {
"type": "integer",
"minimum": 0
}
},
"required": [
"productId",
"productName",
"price",
"available",
"categories",
"stock"
],
"additionalProperties": false
}This schema enforces several useful rules:
Product ID must be a positive integer.
Product name must contain at least three characters.
Price must be greater than zero.
Availability must be a boolean.
Categories must be an array of strings containing at least one item.
Stock must be a non-negative integer.
Unexpected properties are not allowed.
This is particularly useful when validating product data received from different services.
Important JSON Schema Validation Keywords
JSON Schema provides many keywords that help developers define more detailed validation rules.
Here are some commonly used ones.
Required
Defines mandatory properties.
{
"required": ["name", "email"]
}Minimum and Maximum
Restricts numeric values.
{
"type": "integer",
"minimum": 1,
"maximum": 100
}MinLength and MaxLength
Restricts string length.
{
"type": "string",
"minLength": 3,
"maxLength": 50
}Pattern
Validates text against a regular expression.
{
"type": "string",
"pattern": "^[A-Z]{2}[0-9]{4}$"
}Enum
Restricts values to a predefined list.
{
"type": "string",
"enum": ["pending", "processing", "completed"]
}UniqueItems
Ensures that array elements are unique.
{
"type": "array",
"items": {
"type": "string"
},
"uniqueItems": true
}These keywords allow you to create validation rules without writing custom validation logic for every field.
JSON Syntax Validation vs. JSON Schema Validation
These two concepts are often confused, but they solve different problems.
JSON syntax validation checks whether the document follows JSON formatting rules.
For example:
{
"name": "John",
"age": 30
}This is valid JSON.
However, consider the following:
{
"name": "John",
"age": "thirty"
}This is also valid JSON syntax.
But if your application expects age to be an integer, the document fails the corresponding JSON Schema validation.
Here is the difference:
Validation type | What it checks |
|---|---|
JSON syntax validation | Correct JSON structure and formatting. |
JSON Schema validation | Expected properties, data types, values, and constraints. |
Both are important when building reliable applications.
How to Validate JSON Data Online
You do not always need to write code to inspect JSON data.
An online JSON Formatter & Validator can help you quickly check whether your JSON document is correctly formatted.
A typical workflow looks like this:
Open an online JSON validation tool.
Paste your JSON data into the editor.
Run the validation.
Review any syntax errors.
Correct the JSON structure.
Use a JSON Schema validator when you also need to verify business-specific data requirements.
Try the Agilelogics JSON Formatter & Validator: Explore our online developer tools
Note: JSON formatting and syntax validation are different from full JSON Schema validation. Use a dedicated schema validator when you need to enforce schema rules.
Common JSON Schema Validation Mistakes
Even experienced developers can make mistakes when creating validation schemas.
Here are some common issues worth avoiding.
1. Forgetting the required keyword
Defining a property inside properties does not automatically make it mandatory.
You must explicitly include its name in the required array.
2. Using the wrong data type
A numeric value and a numeric string are different.
For example:
{
"price": 99.99
}And:
{
"price": "99.99"
}The first is a number, while the second is a string.
3. Assuming format always performs strict validation
JSON Schema supports the format keyword for values such as email addresses and dates.
However, depending on the specification version and validator configuration, format may be treated as an annotation rather than an assertion.
Always check how your chosen validator handles format validation.
4. Allowing unexpected properties unintentionally
If your application expects a fixed object structure, consider using additionalProperties: false.
This prevents undeclared properties from being accepted at that schema level.
5. Ignoring nested objects
Complex API responses often contain nested objects and arrays.
Make sure your schema validates important nested properties instead of checking only the top-level structure.
Best Practices for JSON Schema Validation
For production applications, consider these recommendations:
Declare the schema version using
$schema.Give schemas meaningful titles and descriptions.
Define required fields explicitly.
Validate nested objects and arrays.
Use numeric and string constraints where appropriate.
Avoid accepting unexpected properties when strict contracts are needed.
Keep schemas version-controlled alongside your application code.
Test both valid and invalid payloads.
Ensure your validator supports the JSON Schema draft you are using.
Validate incoming API data on the server, even if frontend validation is already implemented.
Remember that JSON Schema validation checks data structure and constraints. It does not replace authentication, authorization, database constraints, or business-level security checks.
Final Thoughts
JSON is easy to work with, but accepting incorrectly structured data can create problems across an application.
JSON Schema provides a standardized way to describe what valid JSON data should look like. It helps developers define data contracts, validate API requests, enforce expected data types, and catch structural issues early.
Whether you are developing a small application or maintaining a large API-based system, adding JSON Schema validation can make your data exchange more predictable and easier to maintain.
Start with simple schemas, test them with real-world payloads, and gradually introduce more advanced validation rules as your application grows.
Have JSON data to inspect? Explore Agilelogics.com and make JSON formatting and validation part of your everyday development workflow.
Recommended internal linking
Add these internal links to improve SEO and help readers discover related tools and articles.
Anchor text |
|---|
Written by
Alex Rivera
AI/ML writer covering AI assistants, coding tools, and generative AI platforms — pricing, capabilities, and how they actually compare.