JSON Schema pour Firestore : Guide complet

JSON Schema est un standard ouvert pour décrire la structure des données JSON. Il est utilisé par des entreprises comme Google, Microsoft et AWS pour valider des fichiers de configuration, des API et des modèles de données. FireSchema utilise JSON Schema pour décrire vos collections Firestore — vous offrant un moyen puissant et standardisé de documenter votre base de données. Découvrez pourquoi c'est le bon choix.

Qu'est-ce que JSON Schema ?

JSON Schema définit la structure des documents JSON : quels champs existent, leurs types, lesquels sont obligatoires et quelles valeurs sont valides. C'est un standard (draft 2020-12) supporté par des validateurs dans tous les langages majeurs.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "age": { "type": "integer", "minimum": 0 }
  },
  "required": ["name"]
}

Ce schéma indique : les données sont un objet avec un champ name obligatoire (chaîne de caractères) et un champ age optionnel (entier non négatif).

Structure de base pour FireSchema

FireSchema encapsule le JSON Schema dans une enveloppe de métadonnées de collection. Chaque fichier .schema.json a cette structure :

{
  "$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"
      }
    }
  }
}

Types de champs courants

JSON Schema supporte tous les types dont vous avez besoin pour les documents 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" }
        }
      }
    }
  }
}

Patterns spécifiques à Firestore

Firestore possède des types de données spécifiques qui se mappent bien aux formats 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" — Représente les Timestamps Firestore
• - Objet imbriqué avec latitude/longitude — Représente les GeoPoints
• - pattern avec format de chemin — Représente les DocumentReferences

Règles de validation

Ajoutez des contraintes pour rendre vos schémas plus descriptifs et utiles :

{
  "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"
      }
    }
  }
}

Exemple complet : Collection Orders

Voici un schéma complet pour une sous-collection orders à l'intérieur de users. Enregistrez-le sous 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"]
  }
}

Ce schéma documente le nom de la collection, le nombre estimé de documents, chaque champ avec son type et sa description, ainsi que les règles de validation comme les enums, les patterns et les minimums. Lorsqu'il est rendu par FireSchema, il devient une documentation interactive et navigable.

Outils et ressources

Ces outils vous aident à écrire et valider des fichiers JSON Schema :

• -JSON Schema Validator — Validez vos schémas en ligne sur jsonschemavalidator.net
• -Extension VS Code — Installez l'extension JSON Schema pour l'autocomplétion et la validation en ligne
• -Génération par IA — Utilisez le modèle de prompt LLM inclus pour générer des schémas à partir de descriptions en langage naturel

Prochaines étapes