# Understanding the Schema Help System in OfficeCLI: JSON-Driven Documentation > Explore OfficeCLI's schema help system. Access machine-readable JSON documentation directly from the command line with simple commands. Learn how to get help efficiently. - Repository: [OfficeAI/OfficeCLI](https://github.com/iofficeai/OfficeCLI) - Tags: deep-dive - Published: 2026-07-14 --- **OfficeCLI utilizes a schema-driven help system that embeds JSON Schema files into the binary at build time, allowing you to access machine-readable documentation via commands like `officecli --help --json`.** Unlike traditional CLI tools that rely on static man-pages, the **schema help system in OfficeCLI** generates documentation dynamically from structured JSON files. According to the iOfficeAI/OfficeCLI source code, every **format-element-operation** combination is formally described in the `schemas/help/` directory and baked into the executable, ensuring the help output always reflects the actual implementation. ## Architecture of the Schema Help System The documentation layer is composed of a validating root schema and concrete element definitions that follow a strict contract. ### The Root Schema Contract The file [`schemas/help/_schema.json`](https://github.com/iOfficeAI/OfficeCLI/blob/main/schemas/help/_schema.json) defines the master structure that all help entries must follow. This JSON-Schema specifies the required fields for format identifiers, element names, supported operations (`add`, `set`, `get`), property type definitions, path traversal rules, and child element relationships. ### Element-Specific Definitions Concrete documentation lives in individual files such as [`schemas/help/docx/paragraph.json`](https://github.com/iOfficeAI/OfficeCLI/blob/main/schemas/help/docx/paragraph.json) and [`schemas/help/pptx/chart.json`](https://github.com/iOfficeAI/OfficeCLI/blob/main/schemas/help/pptx/chart.json). These files populate the root schema with implementation-specific details including human-readable descriptions, accepted property values, working CLI examples, and conditional logic declared via the `appliesWhen` field. ### Build-Time Embedding At compile time, the entire `schemas/help/` directory is **embedded into the binary**. This architectural decision eliminates filesystem dependencies at runtime, allowing the CLI to render help instantly even in restricted environments or containerized deployments. ## Accessing Documentation via the CLI The entry point in [`src/officecli/Program.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Program.cs) normalizes all `--help` flags into a single `help` sub-command, funneling every documentation request through a unified renderer. To display the available elements and operations for a specific format: ```bash # Show the full help index for DOCX files officecli docx --help ``` To retrieve structured schema data for scripting or agent integration: ```bash # Get JSON-encoded help for paragraph operations officecli docx add paragraph --help --json ``` For detailed property inspection with formatted output: ```bash # Query PPTX chart properties and pipe to jq officecli pptx get chart --help --json | jq . ``` ## Runtime Implementation Details The actual rendering logic resides in [`src/officecli/CommandBuilder.Help.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/CommandBuilder.Help.cs). When you invoke the help command, this class deserializes the embedded JSON schemas and prints either human-readable text or a machine-parseable JSON document depending on whether you include the `--json` flag. The normalization logic in [`src/officecli/Program.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Program.cs) intercepts `--help` arguments and rewrites them to the `help` sub-command before execution, maintaining a **single source of truth** for all documentation. ## Schema Validation and Continuous Integration The help system serves a critical role in quality assurance through **contract testing**. Each schema claim—such as supported operations or valid property ranges—is automatically tested against the real implementation. When a schema includes `"enforcement": "strict"`, any divergence between the JSON documentation and the code logic will fail the CI pipeline, preventing documentation drift. Additionally, these schemas can be transformed into markdown documentation for release notes and wiki generation, ensuring that external documentation remains synchronized with the CLI capabilities. ## Summary - **Schema location**: Master schema at [`schemas/help/_schema.json`](https://github.com/iOfficeAI/OfficeCLI/blob/main/schemas/help/_schema.json), element files in format subdirectories like [`schemas/help/docx/paragraph.json`](https://github.com/iOfficeAI/OfficeCLI/blob/main/schemas/help/docx/paragraph.json). - **No static files**: Documentation is embedded into the binary at build time for filesystem-independent operation. - **Access methods**: Use `officecli --help` for human-readable output or add `--json` for machine-readable schemas. - **CI enforcement**: Strict mode in contract tests ensures documentation accuracy by failing builds when schemas drift from implementation. - **Single source of truth**: The [`Program.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/Program.cs) normalization guarantees all help requests route through the same embedded schema renderer. ## Frequently Asked Questions ### Where are the schema files located in the OfficeCLI repository? The schema files are stored in the `schemas/help/` directory. You will find the master contract at [`schemas/help/_schema.json`](https://github.com/iOfficeAI/OfficeCLI/blob/main/schemas/help/_schema.json), while individual elements are defined in subdirectories such as [`schemas/help/docx/paragraph.json`](https://github.com/iOfficeAI/OfficeCLI/blob/main/schemas/help/docx/paragraph.json) and [`schemas/help/pptx/chart.json`](https://github.com/iOfficeAI/OfficeCLI/blob/main/schemas/help/pptx/chart.json). The [`schemas/README.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main/schemas/README.md) file provides the layout specification and editing guidelines. ### How do I get machine-readable help output for automation? Append the `--json` flag to any help query. For example, executing `officecli docx add paragraph --help --json` returns a JSON document containing the element's property definitions, allowed values, and usage examples. This output is designed specifically for consumption by automated agents and shell scripts. ### What happens if the schema documentation doesn't match the implementation? When a schema specifies `"enforcement": "strict"`, the contract tests will fail the CI pipeline if the documented operations or properties diverge from the actual code behavior. This prevents stale documentation and ensures the help system accurately reflects the CLI's capabilities at all times. ### Can I generate markdown documentation from the schemas? Yes. Since the JSON schemas contain structured descriptions, examples, and property metadata, you can transform them into markdown for release notes or wiki pages. This capability allows the project to generate external documentation websites directly from the same `schemas/help/` files that power the CLI's built-in help system.