{}FireSchema

Firestore 的 JSON Schema：完整指南

学习编写描述 Firestore 集合的 Schema

JSON Schema 是一个描述 JSON 数据结构的开放标准。Google、Microsoft 和 AWS 等公司使用它来验证配置文件、API 和数据模型。FireSchema 使用 JSON Schema 来描述您的 Firestore 集合 — 为您提供一种强大的、标准化的方式来记录数据库。 了解为什么它是正确的选择.

什么是 JSON Schema？

JSON Schema 定义了 JSON 文档的结构：有哪些字段、它们的类型、哪些是必填的以及什么值是有效的。它是一个标准（draft 2020-12）,支持每种主要语言的验证器。

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

这个 Schema 表示：数据是一个对象,包含一个必填的 name（字符串）和一个可选的 age（非负整数）。

FireSchema 的基本结构

FireSchema 将 JSON Schema 包装在集合元数据信封中。每个 .schema.json 文件具有以下结构：

schemas/users.schema.jsonJSON
{
  "$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"
      }
    }
  }
}

顶层字段：

  • - $schema — JSON Schema 版本（始终使用 2020-12）
  • - collection — Firestore 集合名称
  • - description — 该集合的人类可读描述
  • - documentCount — 可选的预估文档数量
  • - schema — 描述该集合中每个文档的 JSON Schema

常用字段类型

JSON Schema 支持 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" }
        }
      }
    }
  }
}

可用类型：

  • - string — 文本值（名称、邮箱、ID）
  • - number — 小数（价格、分数）
  • - integer — 整数（计数、版本）
  • - boolean — 布尔值（标志、开关）
  • - array — 值的列表（标签、项目）
  • - object — 嵌套对象（地址、元数据）

Firestore 特有模式

Firestore 有特定的数据类型,可以很好地映射到 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/.+$"
      }
    }
  }
}

验证规则

添加约束让您的 Schema 更具描述性和实用性：

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

常用约束：

  • - format — email、date-time、uri、uuid
  • - enum — 允许值的列表
  • - minimum / maximum — 数字范围
  • - minLength / maxLength — 字符串长度限制
  • - pattern — 正则表达式验证

完整示例：Orders 集合

这是 users 中 orders 子集合的完整 Schema。将其保存为 schemas/users/orders.schema.json：

schemas/users/orders.schema.jsonJSON
{
  "$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"]
  }
}

这个 Schema 记录了集合名称、预估文档数量、每个字段及其类型和描述,以及枚举、模式和最小值等验证规则。当被 FireSchema 渲染时,它会变成交互式的可浏览文档。

工具和资源

以下工具可帮助您编写和验证 JSON Schema 文件：

下一步

快速开始指南

5 分钟内使用您的第一个 Schema 设置 FireSchema

Firestore 数据库结构

10 个真实集合模式及 JSON Schema 示例

团队文档

团队如何使用 FireSchema 进行新人培训和协作

试用 FireSchema

快速开始指南

快速开始指南View Live Demo