JSON Schema es un estándar abierto para describir la estructura de datos JSON. Es usado por empresas como Google, Microsoft y AWS para validar archivos de configuración, APIs y modelos de datos. FireSchema usa JSON Schema para describir tus colecciones de Firestore — ofreciéndote una forma potente y estandarizada de documentar tu base de datos. Descubre por qué es la elección correcta.
¿Qué es JSON Schema?
JSON Schema define la estructura de documentos JSON: qué campos existen, sus tipos, cuáles son obligatorios y qué valores son válidos. Es un estándar (draft 2020-12) soportado por validadores en todos los lenguajes principales.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"name": { "type": "string" },
"age": { "type": "integer", "minimum": 0 }
},
"required": ["name"]
}Este esquema dice: el dato es un objeto con un name obligatorio (string) y un age opcional (entero no negativo).
Estructura Básica para FireSchema
FireSchema envuelve JSON Schema en un sobre de metadatos de colección. Cada archivo .schema.json tiene esta estructura:
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"collection": "users",
"description": "Registered app users",
"schema": {
"type": "object",
"properties": {
"displayName": {
"type": "string",
"description": "User's full name"
}
}
}
}Campos de nivel superior:
- -
$schema— La versión de JSON Schema (usa siempre 2020-12) - -
collection— El nombre de la colección de Firestore - -
description— Una descripción legible de esta colección - -
documentCount— Cantidad estimada de documentos (opcional) - -
schema— El JSON Schema que describe cada documento de esta colección
Tipos de Campo Comunes
JSON Schema soporta todos los tipos que necesitas para documentos de Firestore:
{
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Product title"
},
"price": {
"type": "number",
"description": "Price in USD",
"minimum": 0
},
"inStock": {
"type": "boolean",
"description": "Whether the product is available"
},
"tags": {
"type": "array",
"items": { "type": "string" },
"description": "Product tags for search"
},
"metadata": {
"type": "object",
"description": "Additional product metadata",
"properties": {
"createdBy": { "type": "string" },
"version": { "type": "integer" }
}
}
}
}
}Tipos disponibles:
- -
string— Valores de texto (nombres, emails, IDs) - -
number— Números decimales (precios, puntuaciones) - -
integer— Números enteros (conteos, versiones) - -
boolean— Valores verdadero/falso (flags, toggles) - -
array— Listas de valores (etiquetas, elementos) - -
object— Objetos anidados (direcciones, metadatos)
Patrones Específicos de Firestore
Firestore tiene tipos de datos específicos que se mapean bien a formatos de JSON Schema:
{
"schema": {
"type": "object",
"properties": {
"createdAt": {
"type": "string",
"format": "date-time",
"description": "Firestore Timestamp"
},
"location": {
"type": "object",
"description": "Firestore GeoPoint",
"properties": {
"latitude": { "type": "number", "minimum": -90, "maximum": 90 },
"longitude": { "type": "number", "minimum": -180, "maximum": 180 }
},
"required": ["latitude", "longitude"]
},
"authorRef": {
"type": "string",
"description": "Firestore DocumentReference to users collection",
"pattern": "^users/.+$"
}
}
}
}- -
format: "date-time"— Representa Timestamps de Firestore - - Objeto anidado con
latitude/longitude— Representa GeoPoints - -
patterncon formato de ruta — Representa DocumentReferences
Reglas de Validación
Agrega restricciones para hacer tus esquemas más descriptivos y útiles:
{
"schema": {
"type": "object",
"properties": {
"email": {
"type": "string",
"format": "email",
"description": "Must be a valid email"
},
"age": {
"type": "integer",
"minimum": 13,
"maximum": 120,
"description": "User age (13+ required)"
},
"role": {
"type": "string",
"enum": ["admin", "editor", "viewer"],
"description": "One of the allowed roles"
},
"username": {
"type": "string",
"minLength": 3,
"maxLength": 20,
"pattern": "^[a-z0-9_]+$",
"description": "Lowercase alphanumeric, 3-20 chars"
}
}
}
}Restricciones comunes:
- -
format— email, date-time, uri, uuid - -
enum— Lista de valores permitidos - -
minimum/maximum— Rangos numéricos - -
minLength/maxLength— Límites de longitud de texto - -
pattern— Validación con expresiones regulares
Ejemplo Completo: Colección Orders
Aquí tienes un esquema completo para una subcolección orders dentro de users. Guárdalo como schemas/users/orders.schema.json:
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"collection": "orders",
"description": "User purchase orders",
"documentCount": 15000,
"schema": {
"type": "object",
"properties": {
"orderNumber": {
"type": "string",
"pattern": "^ORD-[0-9]{6}$",
"description": "Order ID in format ORD-000000"
},
"status": {
"type": "string",
"enum": ["pending", "confirmed", "shipped", "delivered", "cancelled"],
"description": "Current order status"
},
"items": {
"type": "array",
"description": "Ordered items",
"items": {
"type": "object",
"properties": {
"productId": { "type": "string" },
"name": { "type": "string" },
"quantity": { "type": "integer", "minimum": 1 },
"price": { "type": "number", "minimum": 0 }
},
"required": ["productId", "name", "quantity", "price"]
}
},
"total": {
"type": "number",
"minimum": 0,
"description": "Order total in USD"
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "When the order was placed"
}
},
"required": ["orderNumber", "status", "items", "total", "createdAt"]
}
}Este esquema documenta el nombre de la colección, la cantidad estimada de documentos, cada campo con su tipo y descripción, y reglas de validación como enums, patrones y mínimos. Cuando FireSchema lo renderiza, se convierte en documentación interactiva y navegable.
Herramientas y Recursos
Estas herramientas te ayudan a escribir y validar archivos JSON Schema:
- -JSON Schema Validator — Valida tus esquemas en línea en jsonschemavalidator.net
- -Extensión de VS Code — Instala la extensión JSON Schema para autocompletado y validación en línea
- -Generación con IA — Usa la plantilla de prompt incluida para generar esquemas desde descripciones en lenguaje natural