JSON Schema é um padrão aberto para descrever a estrutura de dados JSON. É usado por empresas como Google, Microsoft e AWS para validar arquivos de configuração, APIs e modelos de dados. FireSchema usa JSON Schema para descrever suas coleções Firestore — oferecendo uma forma poderosa e padronizada de documentar seu banco de dados. Saiba por que é a escolha certa.
O Que É JSON Schema?
JSON Schema define a estrutura de documentos JSON: quais campos existem, seus tipos, quais são obrigatórios e quais valores são válidos. É um padrão (draft 2020-12) suportado por validadores em todas as principais linguagens.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"name": { "type": "string" },
"age": { "type": "integer", "minimum": 0 }
},
"required": ["name"]
}Este schema diz: os dados são um objeto com um name obrigatório (string) e um age opcional (inteiro não-negativo).
Estrutura Básica para FireSchema
FireSchema envolve JSON Schema em um envelope de metadados de coleção. Cada arquivo .schema.json tem esta estrutura:
{
"$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 nível superior:
- -
$schema— A versão do JSON Schema (sempre use 2020-12) - -
collection— O nome da coleção Firestore - -
description— Uma descrição legível desta coleção - -
documentCount— Contagem estimada de documentos (opcional) - -
schema— O JSON Schema que descreve cada documento nesta coleção
Tipos de Campo Comuns
JSON Schema suporta todos os tipos que você precisa para documentos 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 disponíveis:
- -
string— Valores de texto (nomes, emails, IDs) - -
number— Números decimais (preços, pontuações) - -
integer— Números inteiros (contagens, versões) - -
boolean— Valores verdadeiro/falso (flags, toggles) - -
array— Listas de valores (tags, itens) - -
object— Objetos aninhados (endereços, metadados)
Padrões Específicos do Firestore
Firestore possui tipos de dados específicos que mapeiam bem para formatos 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 do Firestore - - Objeto aninhado com
latitude/longitude— Representa GeoPoints - -
patterncom formato de caminho — Representa DocumentReferences
Regras de Validação
Adicione restrições para tornar seus schemas mais descritivos e úteis:
{
"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"
}
}
}
}Restrições comuns:
- -
format— email, date-time, uri, uuid - -
enum— Lista de valores permitidos - -
minimum/maximum— Intervalos numéricos - -
minLength/maxLength— Limites de comprimento de string - -
pattern— Validação por expressão regular
Exemplo Completo: Coleção de Pedidos
Aqui está um schema completo para uma subcoleção orders dentro de users. Salve 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 schema documenta o nome da coleção, contagem estimada de documentos, cada campo com seu tipo e descrição, e regras de validação como enums, patterns e minimums. Quando renderizado pelo FireSchema, se torna documentação interativa e navegável.
Ferramentas e Recursos
Estas ferramentas ajudam você a escrever e validar arquivos JSON Schema:
- -JSON Schema Validator — Valide seus schemas online em jsonschemavalidator.net
- -Extensão VS Code — Instale a extensão JSON Schema para autocomplete e validação inline
- -Geração com IA — Use o modelo de prompt LLM incluído para gerar schemas a partir de descrições em linguagem natural