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

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, 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 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	Single-element detailed documentation	Human-readable text or pretty-printed JSON
SchemaHelpFlatRenderer	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:

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:

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:

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:

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:

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:

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:

{
  "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 — Entry point that parses officecli help arguments and routes to appropriate handlers
• src/officecli/Help/SchemaHelpLoader.cs — Locates, loads, and merges JSON schema resources; handles format and element alias resolution
• src/officecli/Help/SchemaHelpRenderer.cs — Formats single-element schemas for human consumption or pretty JSON
• 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 according to the source code in 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, 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.

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