Referencia ao Schema com o $id especificado.

Cada aplicação que recebe datos de fuentes externas enfrenta a mesma pergunta fundamental: posso confiar em estes datos? Ya sejam corpos de requisição API, arquivos de configuração, mensajes de cola o importaciones de datos, os datos no confiáveis devem validarse antes de ingresar a tua sistema. JSON Schema proporciona uma forma estandarizada e independiente do lenguaje para definir como se veem os datos válidos e validar que os datos entrantes se ajusten a essa definição. Esta guia cobre todo, desde escrever tua primer Schema até patrones avanzados de validação compleja, com exemplos práticos que podes aplicar imediatamente.

Novo em Draft 2020-12. Soporta referencias dinámicas a Schemas.

JSON Schema é um documento JSON que descreve a estrutura e as restricciones de outros documentos JSON. É um vocabulario que te permite anotar e validar datos JSON, estandarizado por o Internet Engineering Task Force (IETF). JSON Schema define regras sobre quê campos devem existir, que tipos devem ter, que valores são aceitáveis e como devem estructurarse os objetos e arrays.

Pensa em JSON Schema como o contrato de tuas datos. Así como um esquema de base de datos define as columnas, tipos e restricciones de uma tabla, JSON Schema define as propriedades, tipos e restricciones dois documentos JSON. Qualquer dato JSON que cumpla todas as restricciones do Schema se chama instancia válida, enquanto que os datos que violan qualquer restricção são inválidos.

OpenAPI (extensão)

• No é um formato de datos: JSON Schema no define como se serializan o transmitem os datos. Solo descreve como se veem os datos válidos.
• No é um sustituto de a lógica de negócio: a validação Schema verifica a correcção estructural (tipos, formato, rangos). As regras de negócio complejas (como "um usuario no pode transferir mais que seu saldo") pertencem ao código da aplicação.
• No é um esquema de base de datos: embora conceptualmente similar, JSON Schema valida documentos JSON, no tablas de base de datos. No entanto, podes usar JSON Schema junto com as restricciones de base de datos para uma defensa em profundidade.

Faz referencia a um Schema desde um arquivo externo.

JSON Schema ha evolucionado através de múltiples borradores, cada um adicionando funcionalidades e refinando o vocabulario. Compreender estas versiones te ajuda a escolher a correta para tua projeto e evitar problemas de compatibilidade.

sem espaço

Comencemos com um exemplo simple: um Schema para um objeto de usuario com nombre, email e edade.

{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "$id": "https://example.com/schemas/user.json",
    "title": "User",
    "description": "A user account in the system",
    "type": "object",
    "properties": {
        "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100,
            "description": "The user's full name"
        },
        "email": {
            "type": "string",
            "format": "email",
            "description": "The user's email address"
        },
        "age": {
            "type": "integer",
            "minimum": 0,
            "maximum": 150,
            "description": "The user's age in years"
        }
    },
    "required": ["name", "email"],
    "additionalProperties": false
}

Este Schema declara que um usuario válido deve ser um objeto onde name e email são propriedades de cadena requeridas. A propriedade age é opcional mas se está presente deve ser um inteiro entre 0 e 150. A restricção additionalProperties: false evita qualquer propriedade no definida no Schema, lo que detecta erros tipográficos e campos inesperados.

com espaço (recomendado)

JSON Schema proporciona um rico vocabulario de palavras clave para definir restricciones. Aquí estão as mais importantes, organizadas por categoria.

Schema por defecto para todos os elementos do array.

Valida por tipo de elemento.

Verifica que os elementos do array sejam únicos.

Verifica que o array tenga pelo menos um elemento.

Valida cada elemento contra todos os Schemas para detectar coincidencias.

Versão do Draft

Os Schemas do mundo real frequentemente requerem patrones que vão mais lá de a simple verificação de tipos. Aquí estão os patrones mais utilizados.

if/then/else para validação condicional

Usa lógica condicional para aplicar diferentes restricciones segundo os valores das propriedades. Por exemplo, um objeto de pago requer diferentes campos segundo o método de pago.

{
    "type": "object",
    "properties": {
        "method": { "enum": ["credit_card", "bank_transfer"] },
        "card_number": { "type": "string" },
        "routing_number": { "type": "string" }
    },
    "required": ["method"],
    "if": {
        "properties": { "method": { "const": "credit_card" } }
    },
    "then": {
        "required": ["card_number"]
    },
    "else": {
        "required": ["routing_number"]
    }
}

allOf, anyOf, oneOf para composição

As palavras clave de composição te permitem combinar Schemas de maneira potente:

• allOf: Os datos devem satisfacer todos os sub-Schemas. Se usa para combinar múltiples restricciones o misturar fragmentos de Schema reutilizaveis.
• anyOf: Os datos devem satisfacer pelo menos um sub-Schema. Se usa para tipos de unión onde múltiples formas são aceitáveis.
• oneOf: Os datos devem satisfacer exatamente um sub-Schema. Se usa para alternativas mutuamente excludentes.

{
    "oneOf": [
        {
            "type": "object",
            "properties": {
                "type": { "const": "email" },
                "address": { "type": "string", "format": "email" }
            },
            "required": ["type", "address"]
        },
        {
            "type": "object",
            "properties": {
                "type": { "const": "phone" },
                "number": { "type": "string", "pattern": "^\\+?[1-9]\\d{1,14}$" }
            },
            "required": ["type", "number"]
        }
    ]
}

$ref para reutilização de Schema

A palavra clave $ref te permite referenciar e reutilizar Schemas, eliminando a duplicação e mantendo os Schemas manteniveis. Podes referenciar Schemas dentro do mesmo documento o em arquivos externos.

{
    "$id": "https://example.com/schemas/order.json",
    "type": "object",
    "properties": {
        "customer": { "$ref": "#/$defs/address" },
        "shipping": { "$ref": "#/$defs/address" },
        "billing": { "$ref": "#/$defs/address" },
        "items": {
            "type": "array",
            "items": { "$ref": "#/$defs/lineItem" },
            "minItems": 1
        }
    },
    "required": ["customer", "items"],
    "$defs": {
        "address": {
            "type": "object",
            "properties": {
                "street": { "type": "string" },
                "city": { "type": "string" },
                "zip": { "type": "string", "pattern": "^\\d{5}(-\\d{4})?$" },
                "country": { "type": "string", "minLength": 2, "maxLength": 2 }
            },
            "required": ["street", "city", "zip", "country"]
        },
        "lineItem": {
            "type": "object",
            "properties": {
                "product": { "type": "string" },
                "quantity": { "type": "integer", "minimum": 1 },
                "price": { "type": "number", "exclusiveMinimum": 0 }
            },
            "required": ["product", "quantity", "price"]
        }
    }
}

Tipos nullavel

Em JSON Schema Draft 2020-12, os tipos nullavel se expresan usando um array de tipos que inclui "null":

{
    "type": ["string", "null"],
    "description": "An optional display name, or null if not set"
}

Em borradores anteriores, a especificação OpenAPI usaba a palavra clave nullavel: true. Para JSON Schema estándar, usa siempre o abordagem de array de tipos.

Sintaxe de nullavel

A palavra clave format proporciona validação semántica mais lá de a verificação estructural. Especifica que uma cadena deve ajustarse a um formato conhecido. Os formatos comumente soportados incluem:

Draft 2020-12

A validação de Schema é mais útil quando se integra no código de tua aplicação. Aquí há exemplos usando bibliotecas populares em diferentes lenguajes.

JavaScript com Ajv

Ajv é o validador JSON Schema mais utilizado em JavaScript. Soporta todas as versiones de borrador e oferece um performance excelente através de a compilação JIT de Schemas.

import Ajv from 'ajv';
import addFormats from 'ajv-formats';

const ajv = new Ajv();
addFormats(ajv);

const schema = {
    type: 'object',
    properties: {
        name: { type: 'string', minLength: 1 },
        email: { type: 'string', format: 'email' },
        age: { type: 'integer', minimum: 0 }
    },
    required: ['name', 'email'],
    additionalProperties: false
};

const validate = ajv.compile(schema);
const valid = validate({ name: 'Alice', email: 'alice@example.com', age: 30 });

if (!valid) {
    console.log(validate.errors);
    // [{ keyword: 'required', params: { missingProperty: 'email' }, ... }]
}

Python com jsonschema

from jsonschema import validate, ValidationError

schema = {
    "type": "object",
    "properties": {
        "name": {"type": "string", "minLength": 1},
        "email": {"type": "string", "format": "email"},
        "age": {"type": "integer", "minimum": 0}
    },
    "required": ["name", "email"],
    "additionalProperties": False
}

try:
    validate(instance={"name": "Alice", "email": "alice@example.com"}, schema=schema)
except ValidationError as e:
    print(f"Validation failed: {e.message}")

Draft 7 e anteriores

Uma das aplicaciones mais valiosas de JSON Schema é validar datos de requisição e respuesta de API. Isto asegura que tua API reciba entradas bem formadas e devuelva datos no formato esperado, detectando erros temprano e proporcionando mensajes de error claros a os clientes.

Middleware de Express.js

import Ajv from 'ajv';

const ajv = new Ajv({ allErrors: true });

function validateBody(schema) {
    const validate = ajv.compile(schema);
    return (req, res, next) => {
        if (!validate(req.body)) {
            return res.status(400).json({
                error: 'Validation failed',
                details: validate.errors
            });
        }
        next();
    };
}

app.post('/api/users',
    validateBody({
        type: 'object',
        properties: {
            name: { type: 'string', minLength: 1, maxLength: 100 },
            email: { type: 'string', format: 'email' },
            role: { enum: ['admin', 'editor', 'viewer'] }
        },
        required: ['name', 'email'],
        additionalProperties: false
    }),
    (req, res) => {
        // req.body is guaranteed valid here
        createUser(req.body);
    }
);

OpenAPI e JSON Schema

OpenAPI (anteriormente Swagger) utiliza um subconjunto de JSON Schema para definir os Schemas de requisição e respuesta de API. Se ya estás usando OpenAPI, podes extrair Schemas de tua especificação API e usarlos para validação em tiempo de execução. Ferramentas como openapi-schema-validator e express-openapi-validator podem automatizar este proceso, asegurando que tua documentação API e lógica de validação permanezcan siempre sincronizadas.

Draft 4

• Siempre estabelece $schema: Inclui a palavra clave $schema para declarar que versão de borrador usa tua Schema. Isto previne ambigüedades e asegura que os validadores interpreten tua Schema correctamente.
• Usa $id para identificação de Schema: A palavra clave $id proporciona um identificador único para tua Schema e sirve como URI base para resolver referencias $ref. Siempre configúrala, inclusive para Schemas locales.
• Estabelece additionalProperties: false: Por defecto, JSON Schema permite qualquer propriedade adicional nos objetos. Estabelecer additionalProperties: false detecta erros tipográficos e campos inesperados, fazendo tua Schema mais estricto e tua API mais previsível.
• Usa $defs para componentes reutilizaveis: Define Schemas comuns em $defs e refiérete a eles usando $ref. Isto reduce a duplicação e faz que os Schemas sejam mais fáciles de manter.
• Adiciona descrições: Cada propriedade e Schema deve ter um campo description. Isto sirve como documentação e ajuda a outros desenvolvedores a entender o propósito e as restricciones de cada campo.
• Valida nos límites do sistema: Aplica a validação Schema nos bordes de tua sistema: endpoints API, consumidores de mensajes, tuberías de importação de datos e cargadores de configuração. No valides datos que tua próprio código ya ha produzido e nos que confías.
• Habilita o modo estricto nos validadores: Configura tua validador para rechazar palavras clave desconocidas, forzar a validação de formatos e reportar todos os erros em vez de detenerse no primero. Isto captura mais problemas em uma única passada de validação.
• Versiona tuas Schemas: Inclui a versão do Schema no URI $id (por exemplo, https://example.com/schemas/user/v2.json). Isto te permite evolucionar os Schemas sem romper os consumidores existentes.
• Experimenta tuas Schemas: Escreve experimentas unitarias para tuas Schemas com exemplos válidos e inválidos. Isto asegura que tua Schema aplique as restricciones que pretendes e detecta regresiones quando os Schemas se modifican.
• Usa format para validação semántica: Prefere format: "email" sobre patrones regex complejos. Os formatos são mais legíveis, mais manteniveis e se benefician de a lógica de validação bem testada nas bibliotecas validadoras.