[📝 Docs]: Create guide "How to validate data against a JSON schema"

[valeriahhdez]

What Docs changes are you proposing?

We need a guide to teach users how to validate data against a JSON schema that is tool agnostic. Any ideas on this topic are welcome!

Code of Conduct

• I agree to follow this project's Code of Conduct

[rnd-debug]

Hello,
I am a simple user, but I was thinking : jwt.io does something similar in a user-friendly way. What if "teaching users how to validate a JSON against a schema in an agnostic way" consisted in providing the feature directly on the website ? In the case of jwt.io, for example, tokens are decoded and an error message (if needed) is directly displayed.
Or do you have something different in mind for this issue? (Maybe a guide about how to actually implement the validation ?)

PS: jwt.io also have a way of displaying a list of libraries that implement tokens en/decoding for different languages and different "levels" of implementation (https://jwt.io/libraries), but this is a different topic.

[valeriahhdez]

Hello @rnd-debug,

Thank you for sharing these ideas; we'll take at look at the examples you provided. I updated the status of this issue because we haven't started it, yet. So, if you'd like to help us write this guide, you can claim this issue.

[kapoorsaumitra]

hi @valeriahhdez

i'd like to contribute, can you please provide more context and details for this issue?

[harshita9104]

hello @valeriahhdez , @benjagm ,

Could you please assign me this issue,

I propose this solution:

1. Progressive Type Validation
   Instead of validating everything at once, structure your schemas to validate data in layers:

{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "User Profile",
"type": "object",
"properties": {
"userId": {
"type": "string",
"pattern": "^[A-Za-z0-9-]+$",
"minLength": 3,
"maxLength": 50,
"description": "Alphanumeric user identifier"
}
}
}

This approach:

• Validates basic type first
• Then checks format constraints
• Finally applies business rules

2. Smart Defaults with ValidationCombine default values with validation to ensure data consistency:

{
"type": "object",
"properties": {
"userSettings": {
"type": "object",
"properties": {
"theme": {
"type": "string",
"enum": ["light", "dark", "system"],
"default": "system"
},
"notifications": {
"type": "boolean",
"default": true
}
}
}
}
}
3. Conditional Validation Pattern
Use if/then/else to create dynamic validation rules:

{
"type": "object",
"properties": {
"userType": {
"type": "string",
"enum": ["individual", "business"]
}
},
"if": {
"properties": {
"userType": { "const": "business" }
}
},
"then": {
"required": ["companyName", "vatNumber"]
},
"else": {
"required": ["firstName", "lastName"]
}
}

Best Practices

1. Use Semantic Property Names
   Create schemas with clear, semantic property names that reflect their purpose:

{
"type": "object",
"properties": {
"emailAddress": {
"type": "string",
"format": "email"
},
"phoneNumber": {
"type": "string",
"pattern": "^\+?[1-9]\d{1,14}$"
}
}
}

2. Custom Formats
   Define reusable custom formats for common validation patterns:

{
"type": "object",
"properties": {
"productCode": {
"$ref": "#/definitions/productCodeFormat"
}
},
"definitions": {
"productCodeFormat": {
"type": "string",
"pattern": "^[A-Z]{2}-[0-9]{6}$",
"description": "Product code in format XX-123456"
}
}
}

3. Error Messages
   Include clear descriptions and examples to help users understand validation requirements:

{
"type": "object",
"properties": {
"password": {
"type": "string",
"minLength": 8,
"pattern": "^(?=.[A-Za-z])(?=.\d)[A-Za-z\d]{8,}$",
"description": "Password must be at least 8 characters and contain both letters and numbers",
"examples": ["securePass123"]
}
}
}

Advanced Patterns

1. Composition Using allOf, anyOf, oneOf
   Combine multiple validation rules using logical operators:

{
"type": "object",
"properties": {
"data": {
"oneOf": [
{
"type": "object",
"properties": {
"type": { "const": "text" },
"content": { "type": "string" }
},
"required": ["type", "content"]
},
{
"type": "object",
"properties": {
"type": { "const": "number" },
"value": { "type": "number" }
},
"required": ["type", "value"]
}
]
}
}
}

2. Schema Versioning
   Include version information in your schemas:

{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://example.com/schemas/user/v1.0.0",
"title": "User Schema v1.0.0",
"type": "object",
"properties": {
"schemaVersion": {
"type": "string",
"const": "1.0.0"
}
}
}

[oluwatobi2001]

Hi @valeriahhdez please can I be assigned to this issue? Thank you