# Understanding the Schema-Driven Help System in OfficeCLI: Architecture and Access Methods

> Explore the schema-driven help system in OfficeCLI. Learn how JSON-Schema dynamically generates docs and access them with `officecli help` or the --json flag for programmatic use.

- Repository: [OfficeAI/OfficeCLI](https://github.com/iofficeai/OfficeCLI)
- Tags: architecture
- Published: 2026-08-08

---

**The OfficeCLI help system uses JSON-Schema files to generate documentation dynamically, accessible via `officecli help <format> <element>` and the `--json` flag for programmatic consumption.**

The OfficeCLI repository implements a **schema-first help architecture** where documentation and validation logic share the same source of truth. Rather than hardcoding help text, the CLI derives all element descriptions, property lists, and usage examples directly from JSON-Schema definitions. This ensures that help output automatically stays synchronized with the actual capability of each command handler.

## How the Schema-Driven Help System Works

The help system operates through a three-stage pipeline that transforms static schema files into either human-readable documentation or machine-readable JSON.

### Stage 1: Schema Discovery and Mapping

When you invoke the help command, the CLI first resolves the canonical schema path. The mapping between command arguments and file locations is defined in [`schemas/README.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main/schemas/README.md), which documents the directory structure for all supported formats:

- **Word documents (.docx)**: `schemas/help/docx/`
- **Excel workbooks (.xlsx)**: `schemas/help/xlsx/`
- **PowerPoint presentations (.pptx)**: `schemas/help/pptx/`

The CLI normalizes format aliases during this stage. For example, `word` resolves to `docx` before locating the schema file.

### Stage 2: Schema Parsing and Rendering

The selected JSON-Schema file undergoes two possible render paths based on your flags:

**Default path (human-readable)**: The parser traverses the schema object and converts property definitions into formatted output. Each property displays its name, type, default value, accepted values, and inline examples. This rendering logic respects schema annotations such as `description`, `enum`, and `default` fields.

**JSON path (machine-readable)**: When `--json` is present, the CLI bypasses rendering and returns the parsed schema object directly. This preserves all metadata—including `$ref` resolutions and validation constraints—for downstream consumption.

### Stage 3: Contract Validation

The repository maintains **contract tests** that verify every schema claim against the actual handler implementation. As documented in [`plugins/plugin-protocol.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main/plugins/plugin-protocol.md), these tests validate that operations marked as supported in the schema (`add`, `set`, `get`, `readback`) execute correctly against real Office documents. This guarantees that help output never drifts from actual functionality.

## Accessing the Schema-Driven Help System

The help system exposes two primary interfaces depending on your use case: interactive terminal exploration and programmatic schema retrieval.

### Interactive Documentation Mode

Display formatted, human-readable documentation for any supported element:

```bash
officecli help <format> <element>

```

**Common examples:**

```bash

# View all paragraph properties and formatting options

officecli help docx paragraph

# Explore Excel chart configuration options

officecli help xlsx chart

# Inspect PowerPoint shape manipulation capabilities

officecli help pptx shape

```

This mode renders property tables with type information, defaults, and usage examples suitable for quick reference during development.

### Programmatic Schema Export

Retrieve the raw JSON-Schema for integration with scripts, agents, or custom tooling:

```bash
officecli help <format> <element> --json

```

**Practical integration patterns:**

```bash

# Extract specific property definitions with jq

officecli help xlsx conditionalformatting --json | jq '.properties.rules'

# Save schema to file for offline validation

officecli help docx table --json > docx-table-schema.json

# Validate user input against schema in a shell script

SCHEMA=$(officecli help pptx slide --json)

# Apply validation logic using $SCHEMA

```

### Global Help and Command Enumeration

Running help without format or element arguments lists all available verbs and global options:

```bash
officecli help

```

This displays every supported operation including `add`, `set`, `get`, `query`, `remove`, and `validate`, along with flags that apply across all commands.

## Key Schema Files and Their Roles

| File Path | Purpose |
|-----------|---------|
| [`schemas/README.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main/schemas/README.md) | Documents the overall schema directory structure and mapping conventions |
| [`main/SKILL.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main/main/SKILL.md) | Defines the `help` verb interface and provides usage examples |
| [`schemas/help/docx/paragraph.json`](https://github.com/iOfficeAI/OfficeCLI/blob/main/schemas/help/docx/paragraph.json) | Schema definition for Word paragraph elements |
| [`schemas/help/xlsx/chart.json`](https://github.com/iOfficeAI/OfficeCLI/blob/main/schemas/help/xlsx/chart.json) | Schema definition for Excel chart elements |
| [`schemas/help/pptx/shape.json`](https://github.com/iOfficeAI/OfficeCLI/blob/main/schemas/help/pptx/shape.json) | Schema definition for PowerPoint shape elements |
| [`plugins/plugin-protocol.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main/plugins/plugin-protocol.md) | Specifies contract testing requirements between schemas and implementations |

## Summary

- **Schema-first design**: Help content derives from JSON-Schema files, eliminating documentation drift
- **Dual output modes**: Human-readable tables via default invocation, raw JSON via `--json` flag
- **Automatic synchronization**: Contract tests ensure schema claims match handler implementations
- **Alias normalization**: Format names like `word` resolve to canonical identifiers (`docx`) before schema lookup
- **Extensible architecture**: Adding new elements requires only new schema files, no code changes to the help system itself

## Frequently Asked Questions

### How does OfficeCLI ensure help output stays accurate with code changes?

The repository runs **contract tests** that execute every operation declared in a schema against real Office document handlers. These tests verify that properties marked as supported actually function as documented, catching discrepancies during CI rather than at runtime.

### Can I use the schema output to build my own validation layer?

Yes. The `--json` flag returns complete JSON-Schema definitions that include type constraints, enum values, required fields, and nested property structures suitable for validation libraries like `ajv`, `jsonschema`, or native implementations in Python, Go, or other languages.

### What happens if I request help for an unsupported format or element?

The CLI performs schema path resolution against the canonical mapping in [`schemas/README.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main/schemas/README.md). If no matching schema file exists, the command returns a clear error indicating that the format or element is not recognized, rather than generating invalid or incomplete documentation.

### Does the help system support custom schema extensions or plugins?

The schema directory structure documented in [`schemas/README.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main/schemas/README.md) follows a predictable convention. While the core repository defines standard Office formats, the plugin protocol in [`plugins/plugin-protocol.md`](https://github.com/iOfficeAI/OfficeCLI/blob/main/plugins/plugin-protocol.md) implies that consistent schema placement enables the same help generation pipeline to work for extended functionality.