JSON Schema is an open standard for describing the structure of JSON data. It's used by companies like Google, Microsoft, and AWS to validate configuration files, APIs, and data models. FireSchema uses JSON Schema to describe your Firestore collections — giving you a powerful, standardized way to document your database. Learn why it's the right choice.
What Is JSON Schema?
JSON Schema defines the structure of JSON documents: what fields exist, their types, which are required, and what values are valid. It's a standard (draft 2020-12) supported by validators in every major language.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"name": { "type": "string" },
"age": { "type": "integer", "minimum": 0 }
},
"required": ["name"]
}This schema says: the data is an object with a required name (string) and an optional age (non-negative integer).
Basic Structure for FireSchema
FireSchema wraps JSON Schema in a collection metadata envelope. Each .schema.json file has this 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"
}
}
}
}Top-level fields:
- -
$schema— The JSON Schema version (always use 2020-12) - -
collection— The Firestore collection name - -
description— A human-readable description of this collection - -
documentCount— Optional estimated document count - -
schema— The JSON Schema describing each document in this collection
Common Field Types
JSON Schema supports all the types you need for Firestore documents:
{
"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" }
}
}
}
}
}Available types:
- -
string— Text values (names, emails, IDs) - -
number— Decimal numbers (prices, scores) - -
integer— Whole numbers (counts, versions) - -
boolean— True/false values (flags, toggles) - -
array— Lists of values (tags, items) - -
object— Nested objects (addresses, metadata)
Firestore-Specific Patterns
Firestore has specific data types that map well to JSON Schema formats:
{
"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"— Represents Firestore Timestamps - - Nested object with
latitude/longitude— Represents GeoPoints - -
patternwith path format — Represents DocumentReferences
Validation Rules
Add constraints to make your schemas more descriptive and useful:
{
"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"
}
}
}
}Common constraints:
- -
format— email, date-time, uri, uuid - -
enum— List of allowed values - -
minimum/maximum— Number ranges - -
minLength/maxLength— String length limits - -
pattern— Regular expression validation
Complete Example: Orders Collection
Here's a full schema for an orders subcollection inside users. Save this as 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"]
}
}This schema documents the collection name, estimated document count, every field with its type and description, and validation rules like enums, patterns, and minimums. When rendered by FireSchema, it becomes interactive, browsable documentation.
Tools & Resources
These tools help you write and validate JSON Schema files:
- -JSON Schema Validator — Validate your schemas online at jsonschemavalidator.net
- -VS Code Extension — Install the JSON Schema extension for autocomplete and inline validation
- -AI Generation — Use the included LLM prompt template to generate schemas from natural language descriptions