[📝 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

• [X] 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

[vtushar06]

Hi @valeriahhdez 👋,

I’d like to work on this guide! I propose organizing it into sections like: • Intro to JSON Schema and validation • Core concepts (types, formats, keywords) • Tool-agnostic examples (CLI, code samples in JS/Python/Java) • Best practices and advanced patterns (if/then/else, allOf, schema versioning) • Troubleshooting and common errors

I can include examples and explain how to use various tools/libraries to validate JSON. Please assign me if this approach works!

Thanks, @vtushar06

[Dule-martins]

Hello Checking in to know if the issue is still open for contribution