Cada palabra clave de JSON Schema explicada con tipos, restricciones, ejemplos y reglas de validación.
$schemaCore / Metase aplica a: rootDeclares the JSON Schema dialect version
{ "$schema": "https://json-schema.org/draft/2020-12/schema" }ℹ Always include at root to declare the dialect
$idCore / Metase aplica a: anySets the base URI for the schema
{ "$id": "https://example.com/schemas/user.json" }titleCore / Metase aplica a: anyHuman-readable title for the schema or property
{ "title": "User", "type": "object" }descriptionCore / Metase aplica a: anyHuman-readable description of the schema's purpose
{ "description": "A registered user account", "type": "object" }$commentCore / Metase aplica a: anyDeveloper comment — not rendered to users
{ "$comment": "Added 2024-01 to support OAuth users" }$defs / definitionsCore / Metase aplica a: rootRepository for reusable sub-schemas
{ "$defs": { "email": { "type": "string", "format": "email" } } }ℹ $defs is draft 2020-12+; use definitions in draft-07
$refCore / Metase aplica a: anyReference to another schema by URI or JSON Pointer
{ "$ref": "#/$defs/email" }ℹ Can reference internal (#/$defs/…) or external schemas
type: stringTypesse aplica a: stringValue must be a JSON string
{ "type": "string" }type: numberTypesse aplica a: numberValue must be a JSON number (integer or float)
{ "type": "number" }type: integerTypesse aplica a: numberValue must be a whole number (no fractional part)
{ "type": "integer" }type: booleanTypesse aplica a: booleanValue must be true or false
{ "type": "boolean" }type: nullTypesse aplica a: nullValue must be JSON null
{ "type": "null" }type: arrayTypesse aplica a: arrayValue must be a JSON array
{ "type": "array" }type: objectTypesse aplica a: objectValue must be a JSON object
{ "type": "object" }type: [multiple]Typesse aplica a: anyValue may be one of the listed types
{ "type": ["string", "null"] }ℹ Useful for optional/nullable fields
minLength / maxLengthStringsse aplica a: stringMinimum and maximum number of Unicode code points
{ "type": "string", "minLength": 1, "maxLength": 100 }patternStringsse aplica a: stringValue must match a ECMA 262 regular expression
{ "type": "string", "pattern": "^[a-z0-9_]+$" }ℹ Partial match — use ^ and $ to anchor
formatStringsse aplica a: stringSemantic validation hint (implementation-dependent)
{ "type": "string", "format": "email" }ℹ Common values: email, uri, uuid, date, date-time, ipv4, ipv6, hostname
enumStringsse aplica a: anyValue must be one of the listed values
{ "type": "string", "enum": ["active", "inactive", "pending"] }constStringsse aplica a: anyValue must exactly equal the given value
{ "const": "v1" }ℹ Equivalent to enum with a single value
minimum / maximumNumbersse aplica a: numberInclusive lower and upper bounds
{ "type": "number", "minimum": 0, "maximum": 100 }exclusiveMinimum / exclusiveMaximumNumbersse aplica a: numberExclusive lower and upper bounds (value < max, value > min)
{ "type": "number", "exclusiveMinimum": 0 }ℹ In draft-07 these were booleans; draft 2019+ they are numbers
multipleOfNumbersse aplica a: numberValue must be a multiple of the given number
{ "type": "integer", "multipleOf": 5 }propertiesObjectsse aplica a: objectSchema for each named property
{ "type": "object", "properties": { "name": { "type": "string" }, "age": { "type": "integer" } } }requiredObjectsse aplica a: objectArray of property names that must be present
{ "type": "object", "required": ["id", "email"] }additionalPropertiesObjectsse aplica a: objectSchema or boolean controlling unknown properties
{ "type": "object", "additionalProperties": false }ℹ false = no extra properties allowed; a schema validates extra properties
patternPropertiesObjectsse aplica a: objectSchemas applied to properties whose name matches the regex key
{ "patternProperties": { "^S_": { "type": "string" } } }minProperties / maxPropertiesObjectsse aplica a: objectMin/max number of properties in the object
{ "type": "object", "minProperties": 1, "maxProperties": 10 }items (draft-07)Arraysse aplica a: arraySchema for all items (or tuple schemas as array)
{ "type": "array", "items": { "type": "string" } }ℹ In draft-2020-12, items applies to all remaining items after prefixItems
prefixItems (2020-12)Arraysse aplica a: arrayPer-index schemas for a tuple
{ "type": "array", "prefixItems": [{ "type": "string" }, { "type": "number" }] }ℹ Replaces tuple form of items from draft-07
minItems / maxItemsArraysse aplica a: arrayMin/max number of array elements
{ "type": "array", "minItems": 1, "maxItems": 50 }uniqueItemsArraysse aplica a: arrayAll items must be unique
{ "type": "array", "items": { "type": "string" }, "uniqueItems": true }containsArraysse aplica a: arrayAt least one item must match the given schema
{ "type": "array", "contains": { "const": "admin" } }ℹ Use minContains / maxContains to control how many must match
allOfCompositionse aplica a: anyValue must be valid against ALL listed schemas
{ "allOf": [{ "type": "string" }, { "minLength": 5 }] }ℹ Intersection — use for schema composition/extension
anyOfCompositionse aplica a: anyValue must be valid against AT LEAST ONE listed schema
{ "anyOf": [{ "type": "string" }, { "type": "number" }] }oneOfCompositionse aplica a: anyValue must be valid against EXACTLY ONE listed schema
{ "oneOf": [{ "type": "string" }, { "type": "number" }] }ℹ Validates all and ensures exactly one matches — slower than anyOf
notCompositionse aplica a: anyValue must NOT be valid against the given schema
{ "not": { "type": "null" } }if / then / elseCompositionse aplica a: anyConditional validation: if condition matches, then/else applies
{ "if": { "properties": { "type": { "const": "email" } } }, "then": { "required": ["email"] }, "else": { "required": ["phone"] } }{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://example.com/schemas/user.json",
"title": "User",
"description": "A registered user account",
"type": "object",
"required": ["id", "email", "role"],
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"email": {
"type": "string",
"format": "email",
"maxLength": 255
},
"name": {
"type": ["string", "null"],
"maxLength": 100
},
"role": {
"type": "string",
"enum": ["admin", "editor", "viewer"]
},
"tags": {
"type": "array",
"items": { "type": "string" },
"uniqueItems": true,
"maxItems": 20
},
"createdAt": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false
}{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$defs": {
"address": {
"type": "object",
"required": ["street", "city", "country"],
"properties": {
"street": { "type": "string" },
"city": { "type": "string" },
"zip": { "type": "string", "pattern": "^[0-9]{5}$" },
"country":{ "type": "string", "minLength": 2, "maxLength": 2 }
}
}
},
"type": "object",
"properties": {
"billing": { "$ref": "#/$defs/address" },
"shipping": { "$ref": "#/$defs/address" }
}
}JSON Schema es un vocabulario que permite anotar y validar documentos JSON. Un JSON Schema es en sí mismo un documento JSON que describe la estructura, restricciones y documentación de otro documento JSON. Se usa ampliamente para validar solicitudes/respuestas de API, archivos de configuración y formularios.
El draft-07 (2018) es la versión más ampliamente soportada, usada por Ajv, everit-org de Java y jsonschema de Python por defecto. El draft-2020-12 introdujo $defs (reemplazando definitions), prefixItems para tuplas de array, las palabras clave unevaluatedProperties/unevaluatedItems y referencias dinámicas ($dynamicRef).
allOf requiere que un valor sea válido contra TODOS los esquemas listados (intersección). anyOf requiere que sea válido contra AL MENOS UNO (unión). oneOf requiere que sea válido contra EXACTAMENTE UNO (exclusivo). Usa allOf para componer esquemas, anyOf para aceptar múltiples tipos, y oneOf cuando exactamente una rama debe coincidir.
Define esquemas reutilizables bajo la clave $defs (draft 2020-12) o definitions (draft-07), luego referencialos con $ref: '#/$defs/MiTipo'. También puedes referenciar esquemas externos por URI completa: $ref: 'https://example.com/schemas/address.json'. La mayoría de los validadores soportan referencias circulares.