diff --git a/README.md b/README.md
index fefa919..e822e31 100644
--- a/README.md
+++ b/README.md
@@ -23,9 +23,17 @@
       <img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="Typesync CLI is released under the MIT license." /></a>
 </p>
 
-Typesync is an open-source schema management tool that simplifies managing [Firestore](https://cloud.google.com/firestore) databases. Typesync allows you to maintain a single source of truth for your Firestore architecture in a special _schema_. With this schema in place, you can seamlessly auto-generate type definitions for multiple platforms like TypeScript, Swift, Python, and more using the CLI tool.
+Typesync is an open-source schema management tool for [Firestore](https://cloud.google.com/firestore) databases. You maintain a single source of truth for your Firestore architecture in a _schema_, then use the CLI to generate code and validate data from that schema.
 
-Typesync keeps your database and application code consistent and up-to-date at all times. In addition to type definitions, it lets you generate other useful things like Security Rules, Mermaid graphs visualizing your database architecture and documentation for your data models.
+Typesync helps keep your database, generated application code, and validation checks aligned as your schema changes.
+
+# How Typesync Helps You
+
+- Generate Firestore models for TypeScript, Swift, and Python from one schema.
+- Validate live Firestore documents with `typesync validate-data`.
+- Generate Security Rules validators from the same model definitions.
+- Visualize your Firestore architecture with Mermaid graphs.
+- Carry schema documentation into generated model output.
 
 [**View the full documentation (docs) ▸**](https://docs.typesync.org)
 
@@ -42,6 +50,7 @@ Explore our comprehensive [documentation](https://docs.typesync.org) for detaile
 - [Quickstart](https://docs.typesync.org/quickstart): Get up and running with Typesync quickly.
 - [Upgrading](https://docs.typesync.org/upgrading): Guidelines on upgrading to the latest version of the CLI.
 - [Types](https://docs.typesync.org/schema/types): Details on the types supported by Typesync’s type system.
+- [validate-data](https://docs.typesync.org/cli/validate-data): Validate Firestore documents against your schema.
 
 # License
 
diff --git a/docs/cli/generate-graph.mdx b/docs/cli/generate-graph.mdx
index 5e2592e..53a6feb 100644
--- a/docs/cli/generate-graph.mdx
+++ b/docs/cli/generate-graph.mdx
@@ -1,15 +1,15 @@
 ---
-title: "generate-graph"
-icon: "rectangle-terminal"
+title: 'generate-graph'
+icon: 'rectangle-terminal'
 ---
 
-import DefinitionOption from "/snippets/cli-option-definition.mdx";
-import OutFileOption from "/snippets/cli-option-out-file.mdx";
-import IndentationOption from "/snippets/cli-option-indentation.mdx";
-import DebugOption from "/snippets/cli-option-debug.mdx";
-import ExampleDefinitionGraph from "/snippets/example-definition-graph.mdx";
-import ExampleGenerationGraphBefore from "/snippets/example-generation-graph-before.mdx";
-import ExampleGenerationGraph from "/snippets/example-generation-graph.mdx";
+import DebugOption from '/snippets/cli-option-debug.mdx';
+import DefinitionOption from '/snippets/cli-option-definition.mdx';
+import IndentationOption from '/snippets/cli-option-indentation.mdx';
+import OutFileOption from '/snippets/cli-option-out-file.mdx';
+import ExampleDefinitionGraph from '/snippets/example-definition-graph.mdx';
+import ExampleGenerationGraphBefore from '/snippets/example-generation-graph-before.mdx';
+import ExampleGenerationGraph from '/snippets/example-generation-graph.mdx';
 
 Generates a [Mermaid](https://mermaid.js.org) graph for the specified schema and injects it into the specified Markdown file. The generated graph is the visual representation of the database architecture inferred from your schema. You can specify where the graph is inserted within the file using the `--startMarker` and `--endMarker` options. For a detailed guide, see the full [example](#example) below.
 
@@ -39,14 +39,9 @@ typesync generate-graph --definition <filePathOrPattern> --outFile <filePath> --
   the `<!--` (see [example](#example)).
 </ParamField>
 
-<ParamField
-  type='"vertical" | "horizontal"'
-  path="orientation"
-  default="horizontal"
->
-  The orientation of the generated Mermaid graph. Can be either `"vertical"` or
-  `"horizontal"` which correspond to the `"TB"` and `"LR"` Mermaid options,
-  respectively.
+<ParamField type='"vertical" | "horizontal"' path="orientation" default="horizontal">
+  The orientation of the generated Mermaid graph. Can be either `"vertical"` or `"horizontal"` which correspond to the
+  `"TB"` and `"LR"` Mermaid options, respectively.
 </ParamField>
 
 <DebugOption />
diff --git a/docs/cli/generate-py.mdx b/docs/cli/generate-py.mdx
index 24d7be2..b0cd680 100644
--- a/docs/cli/generate-py.mdx
+++ b/docs/cli/generate-py.mdx
@@ -1,13 +1,13 @@
 ---
-title: "generate-py"
-icon: "rectangle-terminal"
+title: 'generate-py'
+icon: 'rectangle-terminal'
 ---
 
-import DefinitionOption from "/snippets/cli-option-definition.mdx";
-import OutFileOption from "/snippets/cli-option-out-file.mdx";
-import TargetOption from "/snippets/cli-option-target.mdx";
-import IndentationOption from "/snippets/cli-option-indentation.mdx";
-import DebugOption from "/snippets/cli-option-debug.mdx";
+import DebugOption from '/snippets/cli-option-debug.mdx';
+import DefinitionOption from '/snippets/cli-option-definition.mdx';
+import IndentationOption from '/snippets/cli-option-indentation.mdx';
+import OutFileOption from '/snippets/cli-option-out-file.mdx';
+import TargetOption from '/snippets/cli-option-target.mdx';
 
 Generates Python/Pydantic type definitions for the specified schema and writes them to the specified file. Typesync first “flattens” your schema, creating new aliases for inline types defined within. It then generates the classes, enums, aliases, etc. including serializers and deserializers.
 
@@ -34,9 +34,8 @@ Example values:
 </ParamField>
 
 <ParamField type="string" path="undefinedSentinelName" default="UNDEFINED">
-  The name of the sentinel value used to indicate that a field should be missing
-  from a given object. This is generated as a variable alongside your model
-  definitions.
+  The name of the sentinel value used to indicate that a field should be missing from a given object. This is generated
+  as a variable alongside your model definitions.
 </ParamField>
 
 <IndentationOption />
diff --git a/docs/cli/generate-rules.mdx b/docs/cli/generate-rules.mdx
index 0fc351a..ab6c3db 100644
--- a/docs/cli/generate-rules.mdx
+++ b/docs/cli/generate-rules.mdx
@@ -1,27 +1,25 @@
 ---
-title: "generate-rules"
-icon: "rectangle-terminal"
+title: 'generate-rules'
+icon: 'rectangle-terminal'
 ---
 
-import DefinitionOption from "/snippets/cli-option-definition.mdx";
-import OutFileOption from "/snippets/cli-option-out-file.mdx";
-import IndentationOption from "/snippets/cli-option-indentation.mdx";
-import DebugOption from "/snippets/cli-option-debug.mdx";
-import ExampleDefinition from "/snippets/example-definition.mdx";
-import ExampleGenerationRulesBefore from "/snippets/example-generation-rules-before.mdx";
-import ExampleGenerationRules from "/snippets/example-generation-rules.mdx";
+import DebugOption from '/snippets/cli-option-debug.mdx';
+import DefinitionOption from '/snippets/cli-option-definition.mdx';
+import IndentationOption from '/snippets/cli-option-indentation.mdx';
+import OutFileOption from '/snippets/cli-option-out-file.mdx';
+import ExampleDefinition from '/snippets/example-definition.mdx';
+import ExampleGenerationRulesBefore from '/snippets/example-generation-rules-before.mdx';
+import ExampleGenerationRules from '/snippets/example-generation-rules.mdx';
 
 Generates validator functions for Firestore Security Rules (version 2) and injects them into the specified file. These validators ensure that request data adheres to defined model interfaces and detect any modifications to read-only fields during write operations.
 
 Since Security Rules are centralized in a single file (typically `firestore.rules`), and developers often implement custom rules alongside type validations, Typesync inserts only the necessary validator functions, without overriding your custom rules. You can specify where these validators are added within the file using the `--startMarker` and `--endMarker` options. For a detailed guide, see the full [example](#example) below.
 
 <Info>
-  Note that these validators must adhere to the intrinsic limitations of
-  Security Rules. For example, while it's feasible to verify if `x` is a list
-  with the `x is list` predicate, determining whether it's a list of strings is
-  not possible since loop constructs are not available in Security Rules.
-  Typesync will provide the most stringent validation possible within these
-  constraints.
+  Note that these validators must adhere to the intrinsic limitations of Security Rules. For example, while it's
+  feasible to verify if `x` is a list with the `x is list` predicate, determining whether it's a list of strings is not
+  possible since loop constructs are not available in Security Rules. Typesync will provide the most stringent
+  validation possible within these constraints.
 </Info>
 
 ## Usage
@@ -44,10 +42,9 @@ typesync generate-rules --definition <filePathOrPattern> --outFile <filePath> --
   </ParamField>
 
 <ParamField type="string" path="endMarker" default="typesync-end">
-  A marker that indicates the line before which the generated code should be
-  inserted. Make sure to use a string that is unique within the file. The line
-  containing the marker must be commented i.e. the marker needs to appear after
-  the `//` (see [example](#example)).
+  A marker that indicates the line before which the generated code should be inserted. Make sure to use a string that is
+  unique within the file. The line containing the marker must be commented i.e. the marker needs to appear after the
+  `//` (see [example](#example)).
 </ParamField>
 
 <ParamField
@@ -68,40 +65,42 @@ typesync generate-rules --definition <filePathOrPattern> --outFile <filePath> --
   The name of the parameter taken by each type validator.
 </ParamField>
 
-{/* <ParamField
-  type="string"
-  path="readonlyFieldValidatorNamePattern"
-  default="isReadonlyFieldAffectedFor{modelName}"
->
-  The pattern that specifies how the generated readonly field validators are named. The pattern must be a string that contains the `"{modelName}"` substring (this is a literal value).
-  
-  Example values:
+{/\* <ParamField
+type="string"
+path="readonlyFieldValidatorNamePattern"
+default="isReadonlyFieldAffectedFor{modelName}"
+
+> The pattern that specifies how the generated readonly field validators are named. The pattern must be a string that contains the `"{modelName}"` substring (this is a literal value).
+
+Example values:
 
     - `"isReadonlyFieldAffectedFor{modelName}"` -> produces validators like `isReadonlyFieldAffectedForUser`, `isReadonlyFieldAffectedForProject`, `isReadonlyFieldAffectedForAccount` etc.
     - `"affectsReadonlyFieldFor{modelName}"` -> produces validators like `affectsReadonlyFieldForUser`, `affectsReadonlyFieldForProject`, `affectsReadonlyFieldForAccount` etc.
 
   </ParamField> */}
 
-{/* <ParamField
-  type="string"
-  path="readonlyFieldValidatorPrevDataParamName"
-  default="prevData"
->
-  The name of the first parameter taken by each readonly field validator
-  representing previous data. This parameter used when computing the diff
-  between next data and previous data to determine whether a readonly field has
-  been affected by a write.
+{/\* <ParamField
+type="string"
+path="readonlyFieldValidatorPrevDataParamName"
+default="prevData"
+
+> The name of the first parameter taken by each readonly field validator
+> representing previous data. This parameter used when computing the diff
+> between next data and previous data to determine whether a readonly field has
+> been affected by a write.
+
 </ParamField> */}
 
-{/* <ParamField
-  type="string"
-  path="readonlyFieldValidatorNextDataParamName"
-  default="nextData"
->
-  The name of the second parameter taken by each readonly field validator
-  representing next data. This parameter used when computing the diff between
-  next data and previous data to determine whether a readonly field has been
-  affected by a write.
+{/\* <ParamField
+type="string"
+path="readonlyFieldValidatorNextDataParamName"
+default="nextData"
+
+> The name of the second parameter taken by each readonly field validator
+> representing next data. This parameter used when computing the diff between
+> next data and previous data to determine whether a readonly field has been
+> affected by a write.
+
 </ParamField> */}
 
 <IndentationOption />
@@ -116,7 +115,6 @@ Suppose you have a schema definition file named `models.yml` and a Security Rule
   <ExampleGenerationRulesBefore />
 </CodeGroup>
 
-
 {/* TODO: Update */}
 
 To generate validators for the defined models and inject them between the `typesync-start` and `typesync-end` markers in the `firestore.rules` file, you can run the following command:
diff --git a/docs/cli/generate-swift.mdx b/docs/cli/generate-swift.mdx
index e6d9017..0c2306c 100644
--- a/docs/cli/generate-swift.mdx
+++ b/docs/cli/generate-swift.mdx
@@ -1,15 +1,17 @@
 ---
-title: "generate-swift"
-icon: "rectangle-terminal"
+title: 'generate-swift'
+icon: 'rectangle-terminal'
 ---
 
-import DefinitionOption from "/snippets/cli-option-definition.mdx";
-import OutFileOption from "/snippets/cli-option-out-file.mdx";
-import TargetOption from "/snippets/cli-option-target.mdx";
-import IndentationOption from "/snippets/cli-option-indentation.mdx";
-import DebugOption from "/snippets/cli-option-debug.mdx";
+import DebugOption from '/snippets/cli-option-debug.mdx';
+import DefinitionOption from '/snippets/cli-option-definition.mdx';
+import IndentationOption from '/snippets/cli-option-indentation.mdx';
+import OutFileOption from '/snippets/cli-option-out-file.mdx';
+import TargetOption from '/snippets/cli-option-target.mdx';
 
-Generates Swift type definitions for the specified schema and writes them to the specified file. Typesync first "flattens" your schema, creating new aliases for inline types defined within. It then generates the primary and auxiliary structs, enums, aliases, etc. including encoders and decoders.
+Generates Swift type definitions for the specified schema and writes them to the specified file. Typesync first "flattens" your schema, creating new aliases for inline types defined within. It then generates the primary and auxiliary structs, enums, aliases, encoders, and decoders.
+
+For document models, generated Swift structs include an `@DocumentID var id: String?` property by default. The Firebase Apple SDK fills this value from the document path when decoding and excludes it from the encoded document body when writing.
 
 ## Usage
 
@@ -28,3 +30,62 @@ typesync generate-swift --definition <filePathOrPattern> --target <targetEnviron
 ## Targets
 
 - `firebase@10`: For Swift projects that rely on the [Firebase Apple SDK (v10)](https://github.com/firebase/firebase-ios-sdk).
+
+## Document IDs
+
+Document model structs import `FirebaseFirestore` and include an `@DocumentID`
+property:
+
+```swift
+import FirebaseFirestore
+
+struct User: Codable {
+  @DocumentID var id: String?
+  var username: String
+}
+```
+
+If a document body already has a Firestore field named `id`, rename the generated
+document ID property on that document model:
+
+```yaml
+User:
+  model: document
+  path: users/{userId}
+  swift:
+    documentIdProperty:
+      name: documentId
+  type:
+    type: object
+    fields:
+      id:
+        type: string
+      username:
+        type: string
+```
+
+This produces `@DocumentID var documentId: String?` while keeping the body field
+named `id`.
+
+## Swift field names
+
+Use `swift.name` on a field when the generated Swift property name should differ
+from the Firestore field name. Typesync keeps encoding and decoding aligned with
+the original Firestore key through `CodingKeys`.
+
+```yaml
+User:
+  model: document
+  path: users/{userId}
+  type:
+    type: object
+    fields:
+      class:
+        type: string
+        swift:
+          name: userClass
+```
+
+Typesync fails generation if two fields resolve to the same Swift property name,
+or if a body field conflicts with the generated `@DocumentID` property. Rename
+one of the properties with `swift.name` or `swift.documentIdProperty.name`.
diff --git a/docs/cli/generate-ts.mdx b/docs/cli/generate-ts.mdx
index f95c11f..837a1c0 100644
--- a/docs/cli/generate-ts.mdx
+++ b/docs/cli/generate-ts.mdx
@@ -1,13 +1,13 @@
 ---
-title: "generate-ts"
-icon: "rectangle-terminal"
+title: 'generate-ts'
+icon: 'rectangle-terminal'
 ---
 
-import DefinitionOption from "/snippets/cli-option-definition.mdx";
-import OutFileOption from "/snippets/cli-option-out-file.mdx";
-import TargetOption from "/snippets/cli-option-target.mdx";
-import IndentationOption from "/snippets/cli-option-indentation.mdx";
-import DebugOption from "/snippets/cli-option-debug.mdx";
+import DebugOption from '/snippets/cli-option-debug.mdx';
+import DefinitionOption from '/snippets/cli-option-definition.mdx';
+import IndentationOption from '/snippets/cli-option-indentation.mdx';
+import OutFileOption from '/snippets/cli-option-out-file.mdx';
+import TargetOption from '/snippets/cli-option-target.mdx';
 
 Generates TypeScript type definitions for the specified schema and writes them to the specified file.
 
diff --git a/docs/cli/validate-data.mdx b/docs/cli/validate-data.mdx
new file mode 100644
index 0000000..0af19b7
--- /dev/null
+++ b/docs/cli/validate-data.mdx
@@ -0,0 +1,134 @@
+---
+title: 'validate-data'
+description: 'Validate live Firestore documents against your Typesync schema.'
+icon: 'rectangle-terminal'
+---
+
+import DebugOption from '/snippets/cli-option-debug.mdx';
+import DefinitionOption from '/snippets/cli-option-definition.mdx';
+
+Traverses Firestore collections for selected document models and validates each document against a Zod validator built from your Typesync schema. The command reports invalid documents and does not write to Firestore.
+
+You must explicitly choose what to scan with one or more `--model` flags or with `--all-models`.
+
+<Warning>
+  `validate-data` can read every document in the selected collections. Collections can contain hundreds of thousands of
+  documents, so a full scan can be slow and can incur Firestore read costs. Run this command when you need to audit or
+  investigate stored data, not as a routine development or deployment step.
+</Warning>
+
+## Usage
+
+```bash
+typesync validate-data --definition <filePathOrPattern> --model <modelName>
+```
+
+```bash
+typesync validate-data --definition 'definition/**/*.yml' --model User --model Post --serviceAccount ./service-account.json
+```
+
+## Options
+
+<DefinitionOption />
+
+<ParamField path="model" type="string[]" required>
+  The document model to validate. Repeat the flag to validate multiple models. Mutually exclusive with `allModels`.
+</ParamField>
+
+<ParamField path="allModels" type="boolean" default="false">
+  Validates every document model in the schema. This is opt-in because scanning a large Firestore project can be slow
+  and can incur read costs. Mutually exclusive with `model`.
+</ParamField>
+
+<ParamField path="serviceAccount" type="string">
+  Path to a Google Cloud service account JSON file. If omitted, Typesync uses the `GOOGLE_APPLICATION_CREDENTIALS`
+  environment variable when it is set.
+</ParamField>
+
+<ParamField path="projectId" type="string">
+  Overrides the Firebase project ID. This is most useful when validating data in the Firestore emulator.
+</ParamField>
+
+<ParamField path="emulatorHost" type="string">
+  Points the validator at the Firestore emulator instead of a live project. Use a `host:port` value such as
+  `localhost:8080`.
+</ParamField>
+
+<ParamField path="maxRetries" type="number" default="5">
+  Maximum retry attempts per batch for transient Firestore errors.
+</ParamField>
+
+<ParamField path="batchSize" type="number">
+  Number of documents fetched per page during traversal.
+</ParamField>
+
+<ParamField path="limit" type="number">
+  Stops validation for each selected model after this many documents. Use this for spot checks on large collections.
+</ParamField>
+
+<ParamField path="outFile" type="string">
+  Writes the full JSON validation report to the specified file.
+</ParamField>
+
+<ParamField path="json" type="boolean" default="false">
+  Prints a JSON summary to stdout instead of rendering the live progress UI.
+</ParamField>
+
+<DebugOption />
+
+## Examples
+
+### Validate selected models
+
+```bash
+typesync validate-data \
+  --definition 'definition/**/*.yml' \
+  --model User \
+  --model Post \
+  --serviceAccount ./service-account.json
+```
+
+### Validate all document models
+
+```bash
+typesync validate-data \
+  --definition 'definition/**/*.yml' \
+  --all-models \
+  --serviceAccount ./service-account.json
+```
+
+### Validate emulator data
+
+```bash
+typesync validate-data \
+  --definition 'definition/**/*.yml' \
+  --model User \
+  --projectId demo-project \
+  --emulatorHost localhost:8080
+```
+
+### Write a report file
+
+```bash
+typesync validate-data \
+  --definition 'definition/**/*.yml' \
+  --all-models \
+  --json \
+  --outFile validation-report.json
+```
+
+The command exits with code `1` when it finds invalid documents. It exits with
+code `2` when the validation run itself fails, such as when credentials are
+missing or a selected model does not exist.
+
+## Traversal support
+
+Typesync can validate top-level collections and nested subcollections whose
+collection-name segments are literal strings. For example,
+`users/{userId}/posts/{postId}` can be traversed because the collection names
+are `users` and `posts`.
+
+<Note>
+  Model paths with placeholder collection-name segments cannot be traversed by the current implementation because
+  Firestore collection-group queries require a literal collection ID.
+</Note>
diff --git a/docs/cli/validate.mdx b/docs/cli/validate.mdx
index 35709a1..7d6b9a2 100644
--- a/docs/cli/validate.mdx
+++ b/docs/cli/validate.mdx
@@ -1,14 +1,18 @@
 ---
-title: "validate"
-icon: "rectangle-terminal"
+title: 'validate'
+icon: 'rectangle-terminal'
 ---
 
-import DefinitionOption from "/snippets/cli-option-definition.mdx";
-import DebugOption from "/snippets/cli-option-debug.mdx";
-
+import DebugOption from '/snippets/cli-option-debug.mdx';
+import DefinitionOption from '/snippets/cli-option-definition.mdx';
 
 Checks if the specified schema definition is syntactically valid.
 
+<Note>
+  This command validates the schema files themselves. To validate documents that already exist in Firestore, use
+  [validate-data](/cli/validate-data).
+</Note>
+
 ## Usage
 
 ```bash
diff --git a/docs/docs.json b/docs/docs.json
index 9c2cc1e..3d97077 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -61,6 +61,7 @@
           "cli/generate-py",
           "cli/generate-rules",
           "cli/generate-graph",
+          "cli/validate-data",
           "cli/validate"
         ]
       }
diff --git a/docs/installation.mdx b/docs/installation.mdx
index f623367..7b2f726 100644
--- a/docs/installation.mdx
+++ b/docs/installation.mdx
@@ -1,12 +1,11 @@
 ---
-title: "Installation"
+title: 'Installation'
 ---
 
 You can install the Typesync CLI either globally or on a per-project basis (locally) depending on your use case. Both options are perfectly valid but, when possible, it's a good idea to install it locally to explicitly tie your project to a specific Typesync CLI version.
 
 <Info>
-  **Prerequisite:** The Typesync CLI requires [Node.js](https://nodejs.org) 18
-  or above to be installed on your machine.
+  **Prerequisite:** The Typesync CLI requires [Node.js](https://nodejs.org) 18 or above to be installed on your machine.
 </Info>
 
 <CodeGroup>
diff --git a/docs/introduction.mdx b/docs/introduction.mdx
index 1a46201..eb1f94b 100644
--- a/docs/introduction.mdx
+++ b/docs/introduction.mdx
@@ -1,27 +1,33 @@
 ---
 title: Introduction
+description: 'Learn what Typesync does for Firestore schema management, code generation, and data validation.'
 ---
 
-import ExampleDefinition from "/snippets/example-definition.mdx";
-import ExampleGenerationTSFrontend from "/snippets/example-generation-ts-frontend.mdx";
-import ExampleGenerationTSBackend from "/snippets/example-generation-ts-backend.mdx";
-import ExampleGenerationPython from "/snippets/example-generation-py.mdx";
-import ExampleGenerationSwift from "/snippets/example-generation-swift.mdx";
-import ExampleGenerationRules from "/snippets/example-generation-rules.mdx";
+import ExampleDefinition from '/snippets/example-definition.mdx';
+import ExampleGenerationPython from '/snippets/example-generation-py.mdx';
+import ExampleGenerationRules from '/snippets/example-generation-rules.mdx';
+import ExampleGenerationSwift from '/snippets/example-generation-swift.mdx';
+import ExampleGenerationTSBackend from '/snippets/example-generation-ts-backend.mdx';
+import ExampleGenerationTSFrontend from '/snippets/example-generation-ts-frontend.mdx';
 
-import ExampleUsageTSFrontend from "/snippets/example-usage-ts-frontend.mdx";
-import ExampleUsageTSBackend from "/snippets/example-usage-ts-backend.mdx";
-import ExampleUsageSwift from "/snippets/example-usage-swift.mdx";
-import ExampleUsagePython from "/snippets/example-usage-py.mdx";
+import ExampleUsagePython from '/snippets/example-usage-py.mdx';
+import ExampleUsageSwift from '/snippets/example-usage-swift.mdx';
+import ExampleUsageTSBackend from '/snippets/example-usage-ts-backend.mdx';
+import ExampleUsageTSFrontend from '/snippets/example-usage-ts-frontend.mdx';
 
-Typesync is an open-source schema management toolkit that simplifies managing [Firestore](https://cloud.google.com/firestore) databases. Typesync allows you to maintain a single source of truth for your Firestore architecture in a special _schema_. With this schema in place, you can seamlessly auto-generate type definitions for multiple platforms like TypeScript, Swift, Python, and more using the CLI tool.
+Typesync is an open-source schema management toolkit for [Firestore](https://cloud.google.com/firestore) databases. You maintain a single source of truth for your Firestore architecture in a _schema_, then use the CLI to generate code and validate data from that schema.
 
-Typesync keeps your database and application code consistent and up-to-date at all times. In addition to type definitions, it lets you generate other useful things like Security Rules, Mermaid graphs visualizing your database architecture and documentation for your data models.
+Typesync helps keep your database, generated application code, and validation checks aligned as your schema changes.
 
-<Frame
-  type="glass"
-  caption="Single source of truth for your Firestore architecture"
->
+## How Typesync helps you
+
+- **Generate application models** for TypeScript, Swift, and Python from the same Firestore schema.
+- **Validate live Firestore data** against your schema with `typesync validate-data`, using generated Zod validators under the hood.
+- **Generate Security Rules validators** so Firestore writes can be checked against the same model definitions.
+- **Visualize your database architecture** by generating Mermaid graphs from document model paths.
+- **Document your data models** with schema-level descriptions that flow into generated output.
+
+<Frame type="glass" caption="Single source of truth for your Firestore architecture">
   <img src="/images/architecture-v3.png" />
 </Frame>
 
@@ -33,7 +39,7 @@ In the example below, we define our models in `models.yml`.
 
 <ExampleDefinition />
 
-We then run the following commands to generate type definitions for four different environments and type validators for Security Rules:
+We then run the following commands to generate type definitions for four different environments, generate type validators for Security Rules, and validate existing Firestore data:
 
 <CodeGroup>
 
@@ -57,9 +63,13 @@ typesync generate-py --target firebase-admin@6 --definition models.yml # ... oth
 typesync generate-rules --definition models.yml # ... other options
 ```
 
+```bash Data validation
+typesync validate-data --definition models.yml --model User # ... other options
+```
+
 </CodeGroup>
 
-Typesync generates the following files:
+The generator commands produce the following files:
 
 <CodeGroup>
   <ExampleGenerationTSFrontend />
diff --git a/docs/quickstart.mdx b/docs/quickstart.mdx
index c2a34bc..5fa7b9b 100644
--- a/docs/quickstart.mdx
+++ b/docs/quickstart.mdx
@@ -1,9 +1,9 @@
 ---
-title: "Quickstart"
+title: 'Quickstart'
 ---
 
-import ExampleDefinition from "/snippets/example-definition.mdx";
-import ExampleGenerationTSBackend from "/snippets/example-generation-ts-backend.mdx";
+import ExampleDefinition from '/snippets/example-definition.mdx';
+import ExampleGenerationTSBackend from '/snippets/example-generation-ts-backend.mdx';
 
 <Steps titleSize="h2">
   <Step title="Install Typesync CLI">
@@ -25,10 +25,7 @@ cd definition
 
 Next, create a YAML file named `models.yml` in the `definition` directory. This file will contain the schema definitions for your Firestore documents. Here's a sample schema:
 
-<Note>
-  You can also define your models in JSON files. Typesync accepts YAML, JSON or
-  even a combination of both!
-</Note>
+<Note>You can also define your models in JSON files. Typesync accepts YAML, JSON or even a combination of both!</Note>
 
 <ExampleDefinition />
 
diff --git a/docs/schema/definition.mdx b/docs/schema/definition.mdx
index 20a0dba..ddc284c 100644
--- a/docs/schema/definition.mdx
+++ b/docs/schema/definition.mdx
@@ -1,6 +1,6 @@
 ---
-title: "Definition"
-icon: "files"
+title: 'Definition'
+icon: 'files'
 ---
 
 The Typesync schema for a project is defined in a collection of YAML/JSON files. Your definition can contain as many model definition files as you need and you can organize them any way you want.
@@ -28,19 +28,32 @@ Example values:
 </ParamField>
 
 <ParamField path="docs" type="string">
-  Optional documentation explaining the model in more detail. Typesync will add
-  this to the doc comments for the generated models.
+  Optional documentation explaining the model in more detail. Typesync will add this to the doc comments for the
+  generated models.
 </ParamField>
 
 <ParamField path="type" type="hash" required>
-  The type representing the shape of the document. A document can be represented
-  only by an [object](/schema/types#object) type.
+  The type representing the shape of the document. A document can be represented only by an
+  [object](/schema/types#object) type.
+</ParamField>
+
+<ParamField path="swift" type="object">
+  Swift-specific overrides for this document model.
+
+  <Expandable title="properties">
+    <ParamField path="documentIdProperty.name" type="string" default="id">
+      Renames the auto-generated `@DocumentID` property in Swift output for this
+      document model. Use this when the document body already has a Firestore
+      field named `id`, or when you prefer a different Swift property name such
+      as `documentId`.
+    </ParamField>
+  </Expandable>
 </ParamField>
 
 ### Example
 
 ```yaml user.yml
-# yaml-language-server: $schema=https://schema.typesync.org/v0.13.json
+# yaml-language-server: $schema=https://schema.typesync.org/v0.15.json
 
 User:
   model: document
@@ -65,19 +78,18 @@ An alias model is used for convenience purposes to define reusable type aliases.
 </ParamField>
 
 <ParamField path="docs" type="string">
-  Optional documentation explaining the model in more detail. Typesync will add
-  this to the doc comments for the generated models.
+  Optional documentation explaining the model in more detail. Typesync will add this to the doc comments for the
+  generated models.
 </ParamField>
 
 <ParamField path="type" type="string | hash" required>
-  The type of which this model is an alias. Can be any Typesync
-  [type](/schema/types).
+  The type of which this model is an alias. Can be any Typesync [type](/schema/types).
 </ParamField>
 
 ### Example
 
 ```yaml user.yml
-# yaml-language-server: $schema=https://schema.typesync.org/v0.13.json
+# yaml-language-server: $schema=https://schema.typesync.org/v0.15.json
 
 UserRole:
   model: alias
@@ -101,7 +113,7 @@ UserRole:
     of each definition file.
 
     ```yaml
-    # yaml-language-server: $schema=https://schema.typesync.org/v0.13.json
+    # yaml-language-server: $schema=https://schema.typesync.org/v0.15.json
     ```
 
     This indicates to your IDE that the file is not just any YAML file but a part of a Typesync definition by linking it to the relevant JSON Schema.. This will allow your IDE to provide Intellisense/autocomplete for definition fields.
@@ -121,7 +133,7 @@ UserRole:
 
       ```json
       {
-        "$schema": "https://schema.typesync.org/v0.13.json"
+        "$schema": "https://schema.typesync.org/v0.15.json"
         // ...
       }
       ```
diff --git a/docs/schema/types.mdx b/docs/schema/types.mdx
index 973e66c..0a617fb 100644
--- a/docs/schema/types.mdx
+++ b/docs/schema/types.mdx
@@ -1,6 +1,6 @@
 ---
-title: "Types"
-icon: "cube"
+title: 'Types'
+icon: 'cube'
 ---
 
 Here, you'll find a comprehensive list of all types supported by the Typesync specification. Typesync's powerful type system is designed to support a wide array of complex and useful types.
@@ -268,7 +268,8 @@ function isValidExample(data) {
 Represents a literal type.
 
 <Info>
-  Literal types are not supported in Swift. Typesync currently compiles literal types to the type of the literal value in Swift.
+  Literal types are not supported in Swift. Typesync currently compiles literal types to the type of the literal value
+  in Swift.
 </Info>
 
 <CodeGroup>
@@ -325,7 +326,7 @@ UserRole:
 ```
 
 ```ts models.ts
-export type UserRole = "owner" | "admin" | "member";
+export type UserRole = 'owner' | 'admin' | 'member';
 ```
 
 ```swift models.swift
@@ -347,7 +348,7 @@ class UserRole(enum.Enum):
 
 ```javascript firestore.rules
 function isValidUserRole(data) {
-  return data == "owner" || data == "admin" || data == "member";
+  return data == 'owner' || data == 'admin' || data == 'member';
 }
 ```
 
@@ -526,6 +527,33 @@ function isValidExample(data) {
 
 </CodeGroup>
 
+### Swift-specific options
+
+Use `swift.name` on an object field to override only the generated Swift property
+name. The Firestore field name stays the same.
+
+```yaml
+Example:
+  model: alias
+  type:
+    type: object
+    fields:
+      class:
+        type: string
+        swift:
+          name: userClass
+```
+
+```swift
+struct Example: Codable {
+  var userClass: String
+
+  private enum CodingKeys: String, CodingKey {
+    case userClass = "class"
+  }
+}
+```
+
 ## `union`
 
 Represents a union of multiple types. Typesync supports two types of unions: _simple union_ and _discriminated union_. Both are defined in the same way using `variants`, except a discriminated union definition has a `discriminant` key and requires every variant to be of `object` (or `alias` resolving to `object`) type.
@@ -639,13 +667,13 @@ Pet:
 
 ```ts models.ts
 export type Cat = {
-  type: "cat";
+  type: 'cat';
   name: string;
   lives_left: number;
 };
 
 export type Dog = {
-  type: "dog";
+  type: 'dog';
   name: string;
   breed: string;
 };
diff --git a/docs/snippets/cli-option-indentation.mdx b/docs/snippets/cli-option-indentation.mdx
index 22fd2ed..358b953 100644
--- a/docs/snippets/cli-option-indentation.mdx
+++ b/docs/snippets/cli-option-indentation.mdx
@@ -1,3 +1,3 @@
 <ParamField type="int" path="indentation" default={2}>
   Indentation or tab width for the generated code.
-</ParamField>
\ No newline at end of file
+</ParamField>
diff --git a/docs/snippets/cli-option-target.mdx b/docs/snippets/cli-option-target.mdx
index 478140b..71f7024 100644
--- a/docs/snippets/cli-option-target.mdx
+++ b/docs/snippets/cli-option-target.mdx
@@ -1,6 +1,4 @@
 <ParamField type="string" path="target" required>
-  The target environment for which the types are generated. This option
-  specifies the target SDK and version, ensuring that the output is compatible
-  with the chosen environment. See the list of available targets
-  [here](#targets).
+  The target environment for which the types are generated. This option specifies the target SDK and version, ensuring
+  that the output is compatible with the chosen environment. See the list of available targets [here](#targets).
 </ParamField>
diff --git a/docs/snippets/example-definition-graph.mdx b/docs/snippets/example-definition-graph.mdx
index 612fef2..8d825d3 100644
--- a/docs/snippets/example-definition-graph.mdx
+++ b/docs/snippets/example-definition-graph.mdx
@@ -1,5 +1,5 @@
 ```yaml models.yml
-# yaml-language-server: $schema=https://schema.typesync.org/v0.13.json
+# yaml-language-server: $schema=https://schema.typesync.org/v0.15.json
 
 Author:
   model: document
@@ -35,4 +35,4 @@ Translation:
   type:
     type: object
     fields: {}
-
+```
diff --git a/docs/snippets/example-definition.mdx b/docs/snippets/example-definition.mdx
index e632b74..eda5b9d 100644
--- a/docs/snippets/example-definition.mdx
+++ b/docs/snippets/example-definition.mdx
@@ -1,5 +1,5 @@
 ```yaml models.yml
-# yaml-language-server: $schema=https://schema.typesync.org/v0.13.json
+# yaml-language-server: $schema=https://schema.typesync.org/v0.15.json
 
 UserRole:
   model: alias
diff --git a/docs/snippets/example-generation-graph.mdx b/docs/snippets/example-generation-graph.mdx
index 840d76e..fb6fabf 100644
--- a/docs/snippets/example-generation-graph.mdx
+++ b/docs/snippets/example-generation-graph.mdx
@@ -1,9 +1,10 @@
-```md graph.md
+````md graph.md
 # Architecture
 
 This graph explains how our database is structured.
 
 <!-- typesync-start -->
+
 ```mermaid
 graph LR
     node1["authors"] --> node2["{authorId}"]
@@ -19,3 +20,4 @@ graph LR
 
 This graph is automatically generated.
 ```
+````
diff --git a/docs/snippets/example-generation-py.mdx b/docs/snippets/example-generation-py.mdx
index 39a4de7..a43e1a4 100644
--- a/docs/snippets/example-generation-py.mdx
+++ b/docs/snippets/example-generation-py.mdx
@@ -30,4 +30,4 @@ class User(TypesyncModel):
     if name == "website_url" and value is None:
       raise ValueError("'website_url' field cannot be set to None")
     super().__setattr__(name, value)
-```
\ No newline at end of file
+```
diff --git a/docs/snippets/example-generation-rules-before.mdx b/docs/snippets/example-generation-rules-before.mdx
index 4c8b178..84459cf 100644
--- a/docs/snippets/example-generation-rules-before.mdx
+++ b/docs/snippets/example-generation-rules-before.mdx
@@ -12,4 +12,4 @@ service cloud.firestore {
     }
   }
 }
-```
\ No newline at end of file
+```
diff --git a/docs/snippets/example-generation-rules.mdx b/docs/snippets/example-generation-rules.mdx
index 0de6107..47c0e51 100644
--- a/docs/snippets/example-generation-rules.mdx
+++ b/docs/snippets/example-generation-rules.mdx
@@ -26,4 +26,4 @@ service cloud.firestore {
     }
   }
 }
-```
\ No newline at end of file
+```
diff --git a/docs/snippets/example-generation-swift.mdx b/docs/snippets/example-generation-swift.mdx
index 3d84cce..8aae73d 100644
--- a/docs/snippets/example-generation-swift.mdx
+++ b/docs/snippets/example-generation-swift.mdx
@@ -1,5 +1,6 @@
 ```swift models.swift
 import Foundation
+import FirebaseFirestore
 
 /// Represents a user's role within a project.
 enum UserRole: String, Codable {
@@ -10,6 +11,7 @@ enum UserRole: String, Codable {
 
 /// Represents a user that belongs to a project.
 struct User: Codable {
+  @DocumentID var id: String?
   /// A string that uniquely identifies the user within a project.
   var username: String
   var role: UserRole
@@ -23,4 +25,4 @@ struct User: Codable {
     case createdAt = "created_at"
   }
 }
-```
\ No newline at end of file
+```
diff --git a/docs/snippets/example-generation-ts-backend.mdx b/docs/snippets/example-generation-ts-backend.mdx
index 66454e6..08164f6 100644
--- a/docs/snippets/example-generation-ts-backend.mdx
+++ b/docs/snippets/example-generation-ts-backend.mdx
@@ -12,4 +12,4 @@ export interface User {
   website_url?: string;
   created_at: firestore.Timestamp;
 }
-```
\ No newline at end of file
+```
diff --git a/docs/snippets/example-generation-ts-frontend.mdx b/docs/snippets/example-generation-ts-frontend.mdx
index 7026db6..2a75137 100644
--- a/docs/snippets/example-generation-ts-frontend.mdx
+++ b/docs/snippets/example-generation-ts-frontend.mdx
@@ -12,4 +12,4 @@ export interface User {
   website_url?: string;
   created_at: firestore.Timestamp;
 }
-```
\ No newline at end of file
+```
diff --git a/docs/snippets/example-usage-py.mdx b/docs/snippets/example-usage-py.mdx
index 15a3c28..453beb9 100644
--- a/docs/snippets/example-usage-py.mdx
+++ b/docs/snippets/example-usage-py.mdx
@@ -7,4 +7,4 @@ db = firestore.client()
 doc_ref = db.collection('users').document('adam')
 snapshot = doc_ref.get()
 user = User.model_validate(snapshot.to_dict()) # is a User instance
-```
\ No newline at end of file
+```
diff --git a/docs/snippets/example-usage-swift.mdx b/docs/snippets/example-usage-swift.mdx
index 333263e..bb80183 100644
--- a/docs/snippets/example-usage-swift.mdx
+++ b/docs/snippets/example-usage-swift.mdx
@@ -5,7 +5,7 @@ let db = Firestore.firestore()
 
 db.document("users/adam").getDocument { snapshot, err in
   if let user = try! snapshot?.data(as: User.self) {
-    print(user) // is a User instance
+    print(user.id) // "adam"
   }
 }
-```
\ No newline at end of file
+```
diff --git a/docs/snippets/example-usage-ts-backend.mdx b/docs/snippets/example-usage-ts-backend.mdx
index 1784c3b..dbe535a 100644
--- a/docs/snippets/example-usage-ts-backend.mdx
+++ b/docs/snippets/example-usage-ts-backend.mdx
@@ -1,10 +1,9 @@
 ```ts app.ts (backend)
-import { firestore } from "firebase-admin";
-import type { User } from "./models";
+import { firestore } from 'firebase-admin';
 
-const usersColRef = firestore().collection(
-  "users"
-) as firestore.CollectionReference<User>;
-const userSnap = await usersColRef.doc("adam").get();
+import type { User } from './models';
+
+const usersColRef = firestore().collection('users') as firestore.CollectionReference<User>;
+const userSnap = await usersColRef.doc('adam').get();
 const user = userSnap.data(); // is a User object
-```
\ No newline at end of file
+```
diff --git a/docs/snippets/example-usage-ts-frontend.mdx b/docs/snippets/example-usage-ts-frontend.mdx
index d46047e..76d51ac 100644
--- a/docs/snippets/example-usage-ts-frontend.mdx
+++ b/docs/snippets/example-usage-ts-frontend.mdx
@@ -1,16 +1,11 @@
 ```ts app.ts (frontend)
-import {
-  getFirestore,
-  doc,
-  getDoc,
-  collection,
-  type CollectionReference,
-} from "firebase/firestore";
-import type { User } from "./models";
+import { type CollectionReference, collection, doc, getDoc, getFirestore } from 'firebase/firestore';
+
+import type { User } from './models';
 
 const firestore = getFirestore();
-const usersColRef = collection(firestore, "users") as CollectionReference<User>;
-const userDocRef = doc(usersColRef, "adam");
+const usersColRef = collection(firestore, 'users') as CollectionReference<User>;
+const userDocRef = doc(usersColRef, 'adam');
 const userSnap = await getDoc(userDocRef);
 const user = userSnap.data(); // is a User object
-```
\ No newline at end of file
+```
diff --git a/docs/upgrading.mdx b/docs/upgrading.mdx
index 441724a..0915ca5 100644
--- a/docs/upgrading.mdx
+++ b/docs/upgrading.mdx
@@ -1,15 +1,15 @@
 ---
-title: "Upgrading"
+title: 'Upgrading'
 ---
 
-import ExampleDefinition from "/snippets/example-definition.mdx";
-import ExampleGenerationTSBackend from "/snippets/example-generation-ts-backend.mdx";
+import ExampleDefinition from '/snippets/example-definition.mdx';
+import ExampleGenerationTSBackend from '/snippets/example-generation-ts-backend.mdx';
 
 Upgrading your Typesync version is an important step to ensure you benefit from the latest features, bug fixes, and improvements.
 
 <Warning>
-  Until we reach our v1 release, breaking changes may occur between minor
-  versions (e.g. when upgrading from v0.6 to v0.7).
+  Until we reach our v1 release, breaking changes may occur between minor versions (e.g. when upgrading from v0.6 to
+  v0.7).
 </Warning>
 
 Here's how to manage upgrades smoothly: