Todo equipo de desarrollo enfrenta el mismo problema: nuevos desarrolladores se incorporan, preguntan "¿cómo son los datos?", y nadie tiene una respuesta clara. El conocimiento vive en hilos de Slack, páginas desactualizadas de Notion o en la cabeza de los desarrolladores senior. FireSchema resuelve esto convirtiendo tu esquema de Firestore en una fuente de verdad navegable y versionada.
El Problema de la Documentación
La mayoría de los equipos documentan la estructura de su base de datos de alguna de estas formas:
- -Páginas de Notion o Confluence que se desactualizan en semanas
- -Archivos README con tablas en markdown que nadie actualiza
- -Conocimiento tribal — los desarrolladores senior explican el modelo de datos una y otra vez
- -Sin documentación — los desarrolladores hacen ingeniería inversa desde el código
El resultado: onboarding más lento, más bugs por suposiciones incorrectas y tiempo perdido respondiendo las mismas preguntas.
FireSchema como Tu Fuente de Verdad
Los archivos de FireSchema viven en tu repositorio, junto a tu código. Están versionados, revisables en PRs y siempre actualizados porque son parte de tu flujo de desarrollo — no un sistema de documentación separado.
- Versionado — los cambios se rastrean en git junto con tu código
- Revisable en PRs — los cambios de esquema pasan por revisión de código
- Siempre preciso — los desarrolladores actualizan los esquemas al actualizar el código
- Sin mantenimiento — no hay una plataforma de documentación separada que gestionar
Cómo los Equipos Usan FireSchema
Onboarding de Desarrolladores
Un nuevo desarrollador se une a tu equipo. En lugar de programar una sesión de 2 horas sobre el modelo de datos, lo diriges a la documentación de FireSchema. Pueden explorar cada colección, ver tipos de campo y descripciones, entender las relaciones de subcolecciones y revisar las reglas de validación — todo en una interfaz interactiva que pueden navegar a su propio ritmo.
Planificación de Funcionalidades
Antes de construir una nueva funcionalidad, tu equipo revisa los esquemas relevantes. "¿Qué campos tiene la colección orders? ¿Cuál es el enum de status? ¿Es createdAt obligatorio?" En lugar de buscar en el código, todos abren la documentación de esquemas y tienen el mismo punto de referencia para las discusiones de planificación.
Revisiones de Código
Un PR agrega un nuevo campo a una colección de Firestore. El revisor verifica la actualización del esquema correspondiente: ¿es correcto el tipo de campo? ¿Está documentado? ¿Tiene sentido la descripción? Los cambios de esquema se convierten en parte de tu checklist de revisión, evitando que cambios sin documentar pasen desapercibidos.
Flujo Real: Agregar una Nueva Colección
Así se ve el flujo de trabajo de un equipo con FireSchema:
1. Crear el archivo de esquema
El desarrollador crea un nuevo archivo .schema.json que describe la estructura de la colección:
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"collection": "notifications",
"description": "User notification preferences and history",
"schema": {
"type": "object",
"properties": {
"userId": {
"type": "string",
"description": "Reference to the user document"
},
"type": {
"type": "string",
"enum": ["email", "push", "sms"],
"description": "Notification channel"
},
"enabled": {
"type": "boolean",
"description": "Whether this notification type is active"
}
},
"required": ["userId", "type", "enabled"]
}
}2. Enviar un PR con el esquema + código
El archivo de esquema se commitea junto con el código de la funcionalidad. Los revisores pueden ver tanto la implementación como la documentación en el mismo PR.
3. La documentación de esquemas se actualiza automáticamente
Una vez mergeado, el visor de FireSchema hospedado detecta el nuevo archivo automáticamente. No se necesitan actualizaciones manuales de documentación.
Beneficios para Tu Equipo
Onboarding más rápido
Los nuevos desarrolladores entienden el modelo de datos en horas, no semanas. La documentación interactiva les permite explorar a su propio ritmo.
Menos bugs
Cuando todos conocen los tipos de campo esperados, los enums y los campos obligatorios, menos suposiciones incorrectas llegan a producción.
Mejor comunicación
Los equipos de producto, backend y frontend comparten la misma referencia de datos. "Revisa el esquema" se convierte en la respuesta estándar.
Trazabilidad
Como los esquemas viven en git, puedes ver cuándo cambió cualquier colección, quién la cambió y por qué — a través del historial de commits.
Impacto en el Mundo Real
Un equipo de ingeniería de 12 personas adoptó FireSchema para su aplicación basada en Firestore con 24 colecciones. Resultados después de 3 meses:
- -Tiempo de onboarding reducido de 2 semanas a 3 días
- -Bugs relacionados con datos se redujeron un 40%
- -Mensajes de Slack "¿qué significa este campo?" se redujeron un 60%
- -Cambios de esquema ahora son parte del 100% de los PRs relevantes
Comienza con Tu Equipo
Configurar FireSchema para tu equipo toma 5 minutos:
- 1Follow the Quick Start guide to create your first schema files
- 2Agrega una carpeta schemas/ a tu repositorio
- 3Despliega el visor en la documentación interna de tu equipo (Vercel, GitHub Pages o cualquier host estático)
- 4Agrega actualizaciones de esquema a tu checklist de PRs