Understanding the Schema Help System in OfficeCLI: JSON-Driven Documentation

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 <format> <op> <element> --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 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 and 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 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:

# Show the full help index for DOCX files

officecli docx --help

To retrieve structured schema data for scripting or agent integration:

# Get JSON-encoded help for paragraph operations

officecli docx add paragraph --help --json

For detailed property inspection with formatted output:

# 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. 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 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, element files in format subdirectories like 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 <format> --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 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, while individual elements are defined in subdirectories such as schemas/help/docx/paragraph.json and schemas/help/pptx/chart.json. The 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}