What is JSON Schema?
JSON Schema is a vocabulary for describing the structure of JSON documents. A schema is itself a JSON object that declares: what type each field should be, which fields are required, what format strings must follow, and how to handle nested objects and arrays.
JSON Schema is used for: - API request validation — reject malformed payloads before your business logic runs - Configuration validation — verify that config files have all required fields with valid values - Documentation — schemas are machine-readable contracts that tools can use to generate docs and SDKs - Code generation — tools like quicktype generate TypeScript or Go types from schemas
Basic Schema Structure
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"name": { "type": "string" },
"age": { "type": "integer", "minimum": 0, "maximum": 150 },
"email": { "type": "string", "format": "email" },
"tags": { "type": "array", "items": { "type": "string" } }
},
"required": ["name", "age", "email"],
"additionalProperties": false
}This schema says: - The document must be an object - It must have name (string), age (integer 0-150), and email (valid email format) - tags is optional; if present, every item must be a string - No extra fields are allowed (additionalProperties: false)
Types in JSON Schema
JSON Schema supports these types: string, number, integer, boolean, null, object, array. Use integer when the field must have no decimal part. Use number when decimals are allowed.
You can allow multiple types with an array: {"type": ["string", "null"]} means the field can be a string or null.
String Formats
The format keyword validates string content:
{"type": "string", "format": "email"}
{"type": "string", "format": "date"} // YYYY-MM-DD
{"type": "string", "format": "date-time"} // ISO 8601
{"type": "string", "format": "uuid"}
{"type": "string", "format": "uri"}
{"type": "string", "format": "ipv4"}Note: format validation is optional in most validators. Some implementations skip format checks unless explicitly configured.
Go Validation
// go get github.com/xeipuuv/gojsonschema
import "github.com/xeipuuv/gojsonschema"
schema := gojsonschema.NewStringLoader(`{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"name": {"type": "string"},
"age": {"type": "integer", "minimum": 0},
"email": {"type": "string", "format": "email"}
},
"required": ["name", "age", "email"]
}`)
document := gojsonschema.NewStringLoader(`{"name":"Ravi","age":28,"email":"ravi@example.com"}`)
result, err := gojsonschema.Validate(schema, document)
if err != nil { panic(err) }
if !result.Valid() {
for _, e := range result.Errors() {
fmt.Println("-", e.String())
}
}Reusable Definitions
Use $defs and $ref to avoid repeating schemas:
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$defs": {
"Address": {
"type": "object",
"properties": {
"city": {"type": "string"},
"country": {"type": "string", "minLength": 2, "maxLength": 2}
},
"required": ["city", "country"]
}
},
"type": "object",
"properties": {
"name": {"type": "string"},
"address": {"$ref": "#/$defs/Address"}
},
"required": ["name", "address"]
}Use JSONKit's JSON Schema Generator to automatically create a draft 2020-12 schema from any JSON object, then refine it with your constraints.