# How OfficeCLI's Built-In Help System Provides Property Schemas for Office Documents

> OfficeCLI's help system dynamically loads and renders JSON schema resources, providing property schemas for Office documents in readable or machine-parseable formats.

- Repository: [OfficeAI/OfficeCLI](https://github.com/iofficeai/OfficeCLI)
- Tags: how-to-guide
- Published: 2026-08-03

---

**OfficeCLI delivers property schemas through a schema-driven help command that dynamically loads, merges, and renders JSON schema resources into human-readable documentation or machine-parseable formats.**

The `officecli help` command is built around a single source of truth: **embedded JSON schema files** that describe every supported element across Word (`docx`), Excel (`xlsx`), and PowerPoint (`pptx`) formats. Rather than hard-coding property lists, the help system discovers, loads, and renders these schemas on demand. This ensures that documentation always matches the actual implementation in the iOfficeAI/OfficeCLI repository.

## The Three-Stage Property Schema Pipeline

The help system's architecture separates concerns into **command parsing**, **schema discovery**, and **rendering** layers. Each stage is implemented in dedicated source files that work together to transform raw JSON schemas into useful output.

### Stage 1: Command Parsing and Dispatch

In [`CommandBuilder.Help.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/CommandBuilder.Help.cs), the `CommandBuilder.BuildHelpCommand` method analyzes user arguments to determine which help mode to activate. It distinguishes between three request types:

- **Format-only requests** (`officecli help docx`) — list all elements for a format
- **Element-specific requests** (`officecli help docx paragraph`) — show full schema for one element
- **Flat dump requests** (`officecli help all`) — output every schema entry in grep-friendly format

The dispatcher also handles optional **verb filtering** (`add`, `set`, `get`, `query`, `remove`) and **output format flags** (`--json`, `--jsonl`).

### Stage 2: Schema Discovery and Loading

The `SchemaHelpLoader` class in [`SchemaHelpLoader.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/SchemaHelpLoader.cs) manages all schema access:

1. **Format alias mapping** — normalizes `word` → `docx`, `excel` → `xlsx`, `powerpoint` → `pptx`
2. **Resource indexing** — builds an index of embedded JSON files under `schemas/help/`
3. **Schema loading** — resolves element aliases and loads the requested file via `LoadSchema`
4. **Inheritance resolution** — merges base schemas when `extends` is declared using `MergeSchemaJson`

The loader provides additional utilities for listing formats, validating verb support, and suggesting closest matches for mistyped element names.

### Stage 3: Schema Rendering

Two renderer classes transform the loaded `JsonDocument` into final output:

| Renderer | File | Purpose | Output Modes |
|----------|------|---------|--------------|
| `SchemaHelpRenderer` | [`SchemaHelpRenderer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/SchemaHelpRenderer.cs) | Single-element detailed documentation | Human-readable text or pretty-printed JSON |
| `SchemaHelpFlatRenderer` | [`SchemaHelpFlatRenderer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/SchemaHelpFlatRenderer.cs) | Bulk schema export for tooling | Plain text, NDJSON (`--jsonl`), or JSON array (`--json`) |

## How to Access Property Schemas: 6 Command Patterns

The built-in help system provides property schemas through three core modes, each accessible with specific command syntax.

### 1. Full Element Documentation (Human-Readable)

Display complete schema information for a single element, including all properties, operations, addressing rules, and examples:

```bash
officecli help docx paragraph

```

This invokes `SchemaHelpLoader.LoadSchema` followed by `SchemaHelpRenderer.RenderHuman`, producing:

- Element header and description
- Supported CRUD operations
- Property definitions with types, defaults, and constraints
- Usage examples
- Child element references

### 2. Verb-Filtered Property Schemas

Narrow results to properties compatible with a specific operation:

```bash
officecli help docx set paragraph

```

The `verbFilter` parameter in `SchemaHelpRenderer.RenderHuman` excludes properties that don't support the `set` operation. This is useful when you need to know which properties are **mutable** versus **read-only**.

### 3. Raw JSON Schema Export

Emit the complete merged schema as JSON for integration with external tools:

```bash
officecli help xlsx chart --json

```

This bypasses human formatting and outputs the final `JsonDocument` directly, including all inherited properties from `extends` chains.

### 4. Flat Text Dump for Shell Pipelines

Generate one line per element and property, optimized for `grep`, `awk`, and `cut`:

```bash
officecli help all | grep '^docx paragraph' | grep 'PROP' | grep align

```

`SchemaHelpFlatRenderer.RenderAll` produces rows in this format:

```

docx paragraph ELEM "A block-level content container..."
docx paragraph PROP align string r,w left,right,center,justify "Horizontal alignment of paragraph content"

```

Each `PROP` row includes: ops flags (`r` = readable, `w` = writable), JSON path, aliases, enum values, description, and first example.

### 5. NDJSON Stream for Structured Processing

Stream schema records as newline-delimited JSON for `jq` or streaming parsers:

```bash
officecli help all --jsonl | jq -r 'select(.kind=="PROP" and .name=="align") | .description'

```

`SchemaHelpFlatRenderer.RenderAllJsonl` outputs one JSON object per line with consistent fields: `format`, `element`, `kind` (`ELEM` or `PROP`), and property-specific metadata.

### 6. Complete JSON Array Export

Encapsulate all schemas in a single JSON array for bulk loading:

```bash
officecli help all --json > office_schemas.json

```

This uses `SchemaHelpFlatRenderer.RenderAllJsonArray` to wrap the NDJSON stream in a valid JSON array structure.

## Schema Inheritance and Property Merging

Properties are not always defined in a single file. The OfficeCLI help system supports **schema extension** through the `extends` field:

```json
{
  "name": "numberedParagraph",
  "extends": ["paragraph", "numberedElement"],
  "properties": {
    "listLevel": { "type": "integer", "default": 0 }
  }
}

```

When `SchemaHelpLoader` encounters `extends`, it:

1. Recursively loads each base schema
2. Merges property definitions (child overrides parent)
3. Concatenates examples and operation lists
4. Returns a unified `JsonDocument` to the renderer

This eliminates duplication across similar elements while allowing specialized overrides.

## Key Source Files for Property Schema Access

Understanding these implementation files helps when extending or debugging the help system:

- **[`src/officecli/CommandBuilder.Help.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/CommandBuilder.Help.cs)** — Entry point that parses `officecli help` arguments and routes to appropriate handlers
- **[`src/officecli/Help/SchemaHelpLoader.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Help/SchemaHelpLoader.cs)** — Locates, loads, and merges JSON schema resources; handles format and element alias resolution
- **[`src/officecli/Help/SchemaHelpRenderer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Help/SchemaHelpRenderer.cs)** — Formats single-element schemas for human consumption or pretty JSON
- **[`src/officecli/Help/SchemaHelpFlatRenderer.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Help/SchemaHelpFlatRenderer.cs)** — Generates flat, grep-friendly dumps across all schemas
- **`schemas/help/**/*.json`** — The actual schema definitions embedded as assembly resources

## Summary

- OfficeCLI's **property schemas** live as JSON resources under `schemas/help/`, not hard-coded in source
- The **three-stage pipeline** (parse → load → render) ensures flexibility and consistency
- **Three access modes** serve different workflows: detailed single-element docs, verb-filtered views, and flat bulk exports
- **Schema inheritance** via `extends` reduces duplication and maintains DRY principles
- **Multiple output formats** (human text, JSON, NDJSON) support both interactive use and automation

## Frequently Asked Questions

### How does OfficeCLI handle format aliases like "word" instead of "docx"?

The `SchemaHelpLoader` normalizes format tokens through an internal mapping before resolving schema paths. Both `officecli help word paragraph` and `officecli help docx paragraph` locate the same schema file in [`schemas/help/docx/paragraph.json`](https://github.com/iOfficeAI/OfficeCLI/blob/main/schemas/help/docx/paragraph.json) according to the source code in [`SchemaHelpLoader.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/SchemaHelpLoader.cs).

### Can I filter properties by whether they support read versus write operations?

Yes. Pass a verb argument before the element name: `officecli help docx get paragraph` shows only readable properties, while `officecli help docx set paragraph` shows only writable ones. The `SchemaHelpRenderer` applies this filter during rendering without reloading the schema.

### What happens when a schema extends another schema?

The `SchemaHelpLoader.MergeSchemaJson` method recursively merges base schemas with the overriding file. Child properties take precedence over parent definitions, and the result is a single flattened `JsonDocument` containing all inherited and local properties. This merged view is what both renderers receive.

### Where are the actual JSON schema files stored in the repository?

Schema files reside in `schemas/help/` organized by format (e.g., [`schemas/help/docx/paragraph.json`](https://github.com/iOfficeAI/OfficeCLI/blob/main/schemas/help/docx/paragraph.json), [`schemas/help/xlsx/chart.json`](https://github.com/iOfficeAI/OfficeCLI/blob/main/schemas/help/xlsx/chart.json)). These are embedded as assembly resources and indexed at runtime by `SchemaHelpLoader`. The directory structure mirrors the format/element hierarchy used in help commands.