How to Use the OfficeCLI Validate Command to Check OpenXML Schema Compliance

The officecli validate command executes Open XML schema validation on Office documents, returning exit code 0 for compliant files and exit code 1 for schema violations while supporting machine-readable JSON output for automation pipelines.

The OfficeCLI validate command provides a robust mechanism for verifying that Word, Excel, and PowerPoint documents adhere strictly to the Open XML standard. As implemented in the iOfficeAI/OfficeCLI repository, this command-line tool enables developers to automate schema compliance checks within continuous integration pipelines and pre-commit hooks. Whether you are validating a single contract or batch-processing an entire document library, the validate command delivers detailed diagnostics through both human-readable reports and machine-parseable JSON envelopes.

Command Syntax and Supported Formats

The validation command follows a straightforward syntax requiring only the target file path:

officecli validate <path-to-file>

According to the source code in src/officecli/CommandBuilder.Check.cs (lines 12-20), the command accepts a required <file> argument and supports the global --json option for structured output. The command automatically detects document types based on file extensions, instantiating the appropriate handler for Word (.docx), Excel (.xlsx), and PowerPoint (.pptx) formats through the DocumentHandlerFactory class.

The Validation Pipeline Architecture

When you invoke the validate command, OfficeCLI executes a six-stage pipeline defined across several core modules.

1. Command Construction

The entry point resides in src/officecli/CommandBuilder.Check.cs, where the validate verb is registered with its argument schema and action callback.

2. Resident-Mode Optimization

If a resident server is already handling the file, the request forwards to ResidentServer.cs (lines 22-27) to avoid re-opening the document, significantly improving performance for batch operations.

3. Document Handler Resolution

The DocumentHandlerFactory.Open method in src/officecli/Handlers/DocumentHandlerFactory.cs creates the appropriate handler instance based on the file extension.

4. Schema Validation Execution

Each handler implements a Validate() method that walks the Open XML parts and invokes the Open XML SDK validator. For Word documents, this logic lives in src/officecli/Handlers/Word/WordHandler.cs, collecting ValidationError objects for any structural violations.

5. Result Formatting

Human-readable output writes errors to stderr (lines 47-57), while JSON mode serializes errors via FormatValidationErrors in CommandBuilder.cs (lines 18-34), wrapping them in a standard envelope using OutputFormatter.WrapEnvelope.

6. Exit Code Semantics

The command returns exit code 0 for clean documents and exit code 1 when validation errors are present (line 60), enabling straightforward shell scripting logic.

Output Formats and Error Handling

OfficeCLI provides two output modes tailored to different consumption contexts.

Human-Readable Mode

By default, the command prints a concise success message or detailed error diagnostics to stderr. This separation allows CI pipelines to capture validation failures distinctly from informational stdout:

officecli validate report.docx
#> Validation passed: no errors found.

On failure, errors appear with specific violation types and XML paths:

#> Found 3 validation error(s):
#>   [InvalidTag] Unexpected element <w:tbl> ...

JSON Mode

When invoked with --json, the command outputs a structured envelope containing error counts, descriptions, and document paths:

officecli validate --json report.docx

The JSON structure includes a count field and an errors array with objects containing type, description, and path properties, parsed by the FormatValidationErrors method.

Exit Codes and CI Integration

The validate command implements standard Unix exit codes that integrate seamlessly with shell operators and CI gates. As implemented in CommandBuilder.Check.cs (line 60), the process returns:

• Exit code 0: Document passes all Open XML schema checks
• Exit code 1: One or more validation errors detected

This enables simple conditional logic:

if officecli validate --json contract.docx; then
  echo "Document is schema-compliant"
else
  echo "Document has schema errors – see output above"
fi

You can also pipe JSON output directly to processing tools like jq:

officecli validate --json presentation.pptx | jq '.errors[] | .description'

Practical Validation Examples

Basic schema check with human-readable output:

officecli validate report.docx

JSON output for programmatic processing:

officecli validate --json report.docx

Exit code verification in scripts:

officecli validate contract.docx && echo "OK" || echo "Validation failed"

Filtering specific error descriptions with jq:

officecli validate --json presentation.pptx | jq '.errors[] | .description'

Summary

• The officecli validate command checks Word, Excel, and PowerPoint documents against Open XML schema requirements according to the iOfficeAI/OfficeCLI source code.
• Command definition and orchestration reside in src/officecli/CommandBuilder.Check.cs, utilizing handlers from DocumentHandlerFactory.cs.
• Resident mode (ResidentServer.cs lines 22-27) optimizes performance by avoiding duplicate document opens.
• Output formats include human-readable text (errors to stderr) and structured JSON via the FormatValidationErrors method in CommandBuilder.cs.
• Exit code semantics (0 for success, 1 for failure) enable direct integration with CI/CD gates and shell scripting.

Frequently Asked Questions

What file formats does the OfficeCLI validate command support?

The validate command supports all major Open XML document types, specifically Word (.docx), PowerPoint (.pptx), and Excel (.xlsx). The DocumentHandlerFactory class automatically instantiates the appropriate handler—such as WordHandler for Word documents—based on the file extension.

How does resident mode optimize validation performance?

When a resident server is already managing the target file, the command forwards the validation request to ResidentServer.cs (lines 22-27) rather than reopening the document. This resident-mode shortcut eliminates redundant file I/O operations, significantly improving throughput when processing multiple documents or performing repeated validations.

What exit codes does the validate command return?

According to line 60 in CommandBuilder.Check.cs, the command returns exit code 0 when the document contains no schema violations and exit code 1 when any validation errors are detected. This binary return status conforms to standard Unix conventions, making it ideal for conditional logic in shell scripts and CI pipeline gates.

How do I parse validation errors in a CI/CD pipeline?

Use the --json flag to output machine-readable error data, then pipe the results to tools like jq for filtering. The JSON envelope generated by FormatValidationErrors in CommandBuilder.cs (lines 18-34) includes a count field and an errors array with structured details including error type, description, and document path, enabling automated parsing and reporting in build systems.

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